Lapis Tutorial for version 0.9
By Zack Smith, copyright © 2005, all rights reserved.
Introduction
The Lapis language is an object-oriented stack language that is still
in its early stages of development.
The Stack
If you are not familiar with stack languages, they work very simply.
All computations are done on a stack. You still have variables and such,
but if you want to work with them, you must "push" them onto the stack,
perform any operation on them, and if need be, "pop" them off the stack
again.
You may be familiar with this concept from programming classes:
Stack based computations use the
postfix notation, as opposed to the more commonplace
infix notation.
Key acronyms:
TOS = top item on the stack
NOS = next item on the stack
For instance, consider the following postfix expression:
53 11 - ++ 2 *
First, thus puts two items on the stack:
53, and on top of that, 11.
The "-" subtracts 11 from 33 and replaces both
with the difference, which is 42. The "++" operator then increments
that value to 43, the 2 is pushed and we multiply 43 and 2
to get 86.
If you then want to write the result to the output i.e. send it
to the web browser, you use ".", which removes the item
printed from the stack, or you can say "write", which retains the TOS.
Another example: Suppose you want to create an RGB image
that is 320 by 240. You do this:
320 240 Image
which puts the image on the top of the stack for you to then
do more work with.
Note! Image is the name of a class. To create a new instance
of any class, one merely needs express the class's name.
Data types
- Integer = 32 bit signed integer.
- Unsigned = 32 bit unsigned integer.
- Boolean = 1 bit boolean (true or false).
- Real = 80 bit double-precision float.
- String = arbitrary length.
- Image = image composed of 24-bit RGB pixels
- Font = font data
- Style = a kind of string
- Symbol = a kind of string
- Matrix = matrix of reals
- NameValue = ordered name-value association
- Array = fixed-length array
Basic stack operations
- dup = duplicate top item
- 2dup = duplicate top two items
- drop = delete top item
- 2drop = duplicate top two items
- exch = swap the top two items
- swap = same as exch
- over = push a copy of the NOS
- rot = rotate top 3 items
- nip = drop the NOS but keep the TOS
I/O functionality
- print = write TOS to the output
- writeln = same as print but include newline
System operations
- getenv = gets the named environment variable
HTML functionality
- content-html = puts us in the HTML output mode
- body = print a BODY tag (requires a color values for
background, link, and vlink)
- br = print a BR tag
- par = print a P tag
- font-begin/end = print <FONT FACE=...> open and close tags
- pointsize-begin/end = print <SPAN STYLE=\"font-size=#pt\"> open and close tags
- small-begin/end = print small font open and close tags
- big-begin/end = print big font open and close tags
- bold-begin/end = print bold open and close tags
- italic-begin/end = print italic open and close tags
- underline-begin/end = print underline open and close tags
- title = flag the TOS as title text
- bold = flag the TOS as bold
- italic = flag the TOS as italic
- underline = flag the TOS as underlined
- superscript = flag the TOS as superscripted
- subscript = flag the TOS as subscripted
- strikeout = flag the TOS as struck out
- link = print an A tag using the TOS and NOS
- center-begin/end = centered open and close tags
- indent-begin/end = DIR tag open and close
- right-begin/end = right-align paragraph open and close tags
- table-begin/end = table open and close tags
- tablerow-begin/end = table row open and close tags
- tablecolumn-begin/end = table column open and close tags
- tablehdr-begin/end = table header column open and close tags
- list-begin/end = non-enumerated list (UL) open and close tags
- numbered-begin/end = enumerated list (OL) open and close tags
- list-item = LI tag
- description-begin/end = DL list open and close tags
- description-title = DT tag
- description-content = DD tag
- nostyle = push an empty style onto the stack
- style = convert a string into a style
- div-begin/end = DIV tag open and close (open requires a style)
- span-begin/end = SPAN tag open and close (open requires a style)
- h[1-6]-begin/end = heading open and close
String manipulations operations
Still more to add.
- String = push an empty string
- + = concatenate two strings, or a string and a number, push the result.
- left = get the n leftmost chars in a string
- right = get the n rightmost chars in a string
- char = get the nth char in a string, pushing it as an integer
- sub = get the chars from n to m
Arithmetic and bitwise operations
These work on integers and reals, although the + method
also works on strings.
- + = add
- - = subtract
- * = multiply
- / = divide
- % = remainder
- <<= left shift
- &rt;&rt; = right shift
- | = or
- & = and
- ^ = xor
Boolean operations
- true = pushes true value onto stack
- false = pushes false value onto stack
- == = equals
- != = not equals
- < = less than
- > = greater than
- <= = less than or equals
- >= = greater than or equals
- && = boolean and
- || = boolean or
- ^^ = boolean xor
Advanced math functions and constants
These work primarily on reals.
- sqrt = square root
- cbrt = cube root
- log = natural logarithm
- sin = sine
- cos = cosine
- tan = tangent
- asin = arc-sine
- acos = arc-cosine
- atan = arc-tangent
- pow = raise NOS to the power of TOS, push result
Constants
- true
- false
- null
- nostyle
- constant_pi = push the value of pi
- contant_e = push the value of e
Matrix operations
Hardly begun.
- Matrix = create a matrix that has dimensions NOS by TOS
- print = this prints the matrix as an HTML table
NameValue operations
A NameValue is an ordered name-value pairing.
- NameValue = create an empty set for name-value associations.
- get = reads a value from a map
- put = writes a name and value to a map
- print = this prints map as a two-column table
Array operations
- Array = create an array with TOS slots.
- get = reads a value from an array, slot # TOS
- put = writes value to an array at slot # TOS
- print = this prints the array single-column table
Image manipulation
- content-jpeg = puts us in the JPEG output mode
- Image = create an image that has dimensions NOS by TOS pixels, defaulting to all white pixels.
- moveto = sets the current x,y pen position
- lineto = draws a line from the current x,y pen to (NOS,TOS)
- fillrect = draws a filled rectangle from the current x,y pen
position to (NOS,TOS)
- loadconsolefont = loads one of the 8x16 Linux console fonts
(must be in an uncompressed file)
- color = converts a string to a color (if not found, result is black)
- setcolor = sets the pen color for a given image
- setfont = sets the current font for a given image
- show = draws a given string at the current x,y using
the current font with the current color
- print = in content-jpeg mode, this
writes the image to the output as a JPEG;
in content-html mode, this prints the image as a compressed
HTML table of pixels.
Example:
300 200 Image
( 20 10 ) moveto
( "blue" getcolor ) setcolor
( 100 100 ) lineto
( 15 3 * 190 ) lineto
( Font ( "rl" ) loadconsolefont ) setfont
print
drop
Variables
- /variablename = pushes a variable name onto the stack as a symbol
- def = sets the value of a variable (name and value must be on stack)
- variablename = pushes a variable's value onto the stack
Example:
/total_apples 100 =
/total_apples total_apples -- =
total_apples print
~total_apples
This will define the variable total_apples to 100,
then redefine it to the value 99 (we push its value
and decrement that), then print the value.
Another example:
/myimage 320 240 Image =
myimage ( 100 100 ) moveto ( 300 200 ) lineto
print
drop
This defines variable myimage to contain an RGB
image that is 320 by 240. To draw a line in the image
we push it onto the stack and when we're done, we "drop"
or discard the image on the top, which is actually
just a reference to the original.
Classes
Currently all classes are preset and unchangeable.
Rule: class names must begin with an uppercase letter.
Program control
Not implemented yet.
Functions
Not implemented yet.
Database access
Not implemented yet.