Back to index

Catalog of Language Elements # - C

Catalog of Language Elements D - L

Alphabetic catalog of Language elements M - R

macro

macro replaces an expression with another one at compile time.

Category Special form
Format
(macro (var arg) expr1 expr2 ...)
Parameters
var a variable name to be used as the keyword of a new special form
arg a symbol bound to the original expression
expri the expressions which are evaluated in the extended environment when the macro is expanded.
Description macro creates a new special form with keyword var.

When compiling an expression whose first subexpression is a symbol and this symbol is bound by an macro definition, the entire expression (unevaluated) is bound to the parameter arg and the expri are evaluated in order from left to right. The last expri should evaluate to another expression, which is compiled instead of the original expression.

As macro expansions can't be interrupted by the Break button for technical reasons, there are two limits:

  • a macro single expansion may take only a limited number of VM steps.
  • the number of macro expansions during a single compilation is limited, too
If you find these limits (indicated by this error) too restrictive, please email me at bugs@lispme.de.

macro-definitions are allowed at top-level only, not inside other expressions.

Macros may be recursive.

The return value of a macro definition is #n in this implementation.

R4RS Compliance LispMe extension, but according to several other macro systems
Examples
(macro (my-or expr)
  (let ((name (gensym)))
    (cond ((null? (cdr expr)) #f)
          ((null? (cddr expr)) (cadr expr))
          (else `(let ((,name ,(cadr expr)))
                   (if ,name ,name
                     (my-or ,@(cddr expr))))))))
=> creates a special form my-or, which behaves exactly like or. Note the usage of gensym to create a new temporary name to avoid name clashes with other symbols and how to take advantage of the quasiquote syntax.

macro?

macro? recognizes macros.

Category Primitive procedure
Format (macro? obj)
Parameters
objany object
Description macro? returns #t for a macro created by the macro special form and #f for any other object.
R4RS Compliance Full
Examples
(macro? (lambda (x) x)) => #f
(macro? my-or) => #t, assuming the definition above is used

magnitude

magnitude computes the magnitude of a complex number.

Category Primitive procedure (MathLib required)
Format (magnitude z)
Parameters
zany number
Description magnitude computes the magnitude (or absolute value) of the number z.
R4RS Compliance Full
Examples
(magnitude 5) => 5
(magnitude -1) => 1
(magnitude 0.5+2i) => 2.06155281280883

make-polar

make-polar constructs a complex number from a magnitude and angle.

Category Primitive procedure (MathLib required)
Format (make-polar mag ang)
Parameters
maga real number
anga real number
Description make-polar constructs a complex number from the magnitude mag and the angle ang.
R4RS Compliance Full
Examples
(make-polar 5 -2) => -2.08073418273571-4.546487134412841i
(eqv? (make-polar 7.2 1.8) 7.2@1.8) => #t

make-rectangular

make-rectangular constructs a complex number from the real and imaginary part.

Category Primitive procedure (MathLib required)
Format (make-rectangular re im)
Parameters
rea real number
ima real number
Description make-rectangular constructs a complex number from the real part re and the imaginary part re.
R4RS Compliance Full
Examples
(make-rectangular 5 -2) => 5-2i
(make-rectangular -1.1 0) => -1.1

make-string

make-string creates a new string.

Category Primitive procedure
Format (make-string len char)
Parameters
lena positive integer
chara character
Description make-string creates a newly allocated string of length len, where each character is initialized to char.
R4RS Compliance Fill char is required
Examples
(make-string 5 #\x) => "xxxxx"

make-vector

make-vector creates a new vector.

Category Primitive procedure
Format (make-vector len fill)
Parameters
lena positive integer
fillany object
Description make-vector creates a newly allocated vector of length len, where each element is initialized to fill.
R4RS Compliance Fill value is required
Examples
(make-vector 3 'havanna) => #(havanna havanna havanna)

map

map applies a procedure to each element of a list.

Category Library procedure
Format (map proc list)
Parameters
proca procedure of one argument
lista proper list
Description map creates a newly allocated lists, where each element is the result of applying proc to the corresponding element of list.
R4RS Compliance Supports only one list
Examples
(map (lambda (x) (* x x)) '(2 3 4 5)) => (4 9 16 25)

max

max returns the largest of some objects.

Category Library procedure
Format (max comp1 comp2 ...)
Parameters
compia comparable object
Description max returns the largest of some objects, according to the > procedure. Note that max handles chars and strings, too. At least one object must be specified.
R4RS Compliance Full and works for strings and characters, too.
Examples
(max 50 30 10 80) => 80
(max "Baz" "Foo") => "Foo"

member memq memv

member, memq, and memv search lists for an element.

Category Library procedures
Formats
(member obj list)
(memq obj list)
(memv obj list)
Parameters
objany object
lista proper list
Description These procedures return the first sublist of list, whose car is obj. If none is found, #f is returned. To compare obj with the car, member uses equal?, memq uses eq?, and memv uses eqv?.
R4RS Compliance Full
Examples
(member 'b '(a b c d)) => (b c d)
(member 'c '(a b)) => #f
(memq '(b) '(a (b) c)) => #f
(member '(b) '(a (b) c)) => ((b) c)

menu

menu is posted when a menu item has been selected.

Category UI event
Format (menu id)
Parameters
idthe id of the menu item
Description menu is the event posted when the user has selected a menu item or invoked a menu command by a command stroke shortcut.

message

message displays a message box.

Category Primitive procedure
Format (message obj)
Parameters
objany object
Description message prints obj using display to a message box (see User message). The return value is #n.
R4RS Compliance LispMe extension
Examples
(message "Hello, world") => #n, displays Hello, world in a message box

min

min returns the smallest of some objects.

Category Library procedure
Format (min comp1 comp2 ...)
Parameters
compia comparable object
Description min returns the smallest of some objects, according to the < procedure. Note that min handles chars and strings, too. At least one object must be specified.
R4RS Compliance Full and works for strings and characters, too.
Examples
(min 50 30 10 80) => 10
(min "Baz" "Foo") => "Baz"

modulo

modulo divides two integers and returns the remainder.

Category Library procedure
Format (modulo int1 int2)
Parameters
int1an integer
int2an integer
Description modulo divides two integer numbers and returns the remainder. The sign of the result is always the sign of the divisor, in contrast to remainder. Division by zero is an error.
R4RS Compliance Full
Examples
(modulo 13 4) => 1
(modulo -13 4) => 3
(modulo 13 -4) => -3
(modulo -13 -4) => -1
(modulo 13 0) => error

negative?

negative? tests, if a number is negative.

Category Library procedure
Format (negative? num)
Parameters
numa number
Description negative? returns #t, if num is negative. Otherwise it returns #f. See also positive? and zero?.
R4RS Compliance Full
Examples
(negative? -17) => #t
(negative? 0) => #f

newline

newline starts a new line in the output area.

Category Library procedure
Format (newline [outport])
Parameters
outport(optional) an output port
Description newline prints a linefeed character to the output field or to the output port outport. newline returns the line feed character. For related information, see display and write.
R4RS Compliance Full
Examples
(newline) => () and prints a linefeed to the output area.

none?

none? recognizes the non-printing object.

Category Primitive procedure
Format (none? obj)
Parameters
objany object
Description none? returns #t for #n and #f for any other object.
R4RS Compliance LispMe extension
Examples
(none? 42) => #f
(none? #n) => #t

not

not negates a boolean value.

Category Primitive procedure
Format (not obj)
Parameters
objany object
Description not returns #t if obj is false, otherwise it returns #t. Remember that in LispMe () and #f are distinct objects, so not is not the same procedure as null?.
R4RS Compliance Full
Examples
(not '(a b c)) => #f
(not '()) => #f
(not #f) => #t

null?

null? recognizes the empty list.

Category Primitive procedure
Format (null? obj)
Parameters
objany object
Description null? returns #t for the empty list () and #f for any other object. Remember that in LispMe () and #f are distinct objects, so null? is not the same procedure as not.
R4RS Compliance Full
Examples
(null? '(a b c)) => #f
(null? '()) => #t
(null? #f) => #f

number?

number? recognizes numbers.

Category Primitive procedure
Format (number? obj)
Parameters
objany object
Description number? returns #t for integer, real and complex numbers and #f for any other object.
R4RS Compliance Full
Examples
(number? 42) => #t
(number? -1.234e-55) => #t
(number? 3.5-17i) => #t
(number? 'foo) => #f

object->string

object->string prints an object to a string.

Category Primitive procedure
Format (object->string obj)
Parameters
objany object
Description object->string uses the standard LispMe printer to build the textual representation of obj as a string. The printing convention of write is used. The resulting string is truncated to 4096 characters.
R4RS Compliance LispMe extension. object->string subsumes R4RS procedures symbol->string and number->string.
Examples
(object->string 'Foobar) => "foobar"
(object->string "Foobar") => "\"Foobar\""
(object->string #\x) => "\#\\x"
(object->string '(a (b) c)) => "(a (b) c)"
(object->string -1.234) => "-1.234"

odd?

odd? tests, if a number is odd.

Category Library procedure
Format (odd? int)
Parameters
intan integer
Description odd? returns #t, if int is odd. Otherwise it returns #f. See also even?.
R4RS Compliance Full
Examples
(odd? 42) => #f
(odd? 1.23) => error

open-append-file

open-append-file opens an existing memo for appending output.

Category Primitive procedure
Format (open-append-file string)
Parameters
stringa string naming the memo
Description open-append-file searches a memo with name string and opens it for output, which will be appended to its former contents. If the memo doesn't exist, a new one is created like by open-output-file For more information about files/memos see here.
R4RS Compliance LispMe extension
Examples
(open-append-file "foo") => [outport] and opens the memo with first line foo for output

open-input-file

open-input-file opens an existing memo for input.

For more information about files/memos see here.
Category Primitive procedure
Format (open-input-file string)
Parameters
stringa string naming the memo
Description open-input-file searches a memo with name string and returns the input port associated with the opened memo. If the memo doesn't exist, an error is raised.
R4RS Compliance Full
Examples
(open-input-file "foo") => [inport 4] provided there exists a new memo with first line foo

open-output-file

open-output-file opens a new memo for output.

Category Primitive procedure
Format (open-output-file string)
Parameters
stringa string naming the memo
Description open-output-file creates a new memo with name string and returns the output port associated with the new memo. For more information about files/memos see here.
R4RS Compliance Full
Examples
(open-output-file "foo") => [outport] and creates a new memo with first line foo

or

or is the non-strict logical disjunction of expressions.

Category Special form
Format (or expr1 ...)
Parameters
expri any expression.
Description or evaluates the expri in left to right order. If any expression is true, the evaluation is finished. In any case, the value of the last expression evaluated is returned. Remember that '() is considered true in LispMe.
R4RS Compliance Full
Examples
(or 4 5) => 4
(or #f "foo" 5) => foo
(or) => #f

output-port?

output-port? recognizes a port opened for output.

Category Primitive procedure
Format (output-port? obj)
Parameters
objany object
Description output-port? returns #t for a port opened for output by open-output-file and #f for any other object.
R4RS Compliance Full
Examples
(output-port? (open-output-file "foo")) => #t
(output-port? (open-input-file "bar")) => #f
(output-port? "baz") => #f

own-gui

own-gui switches event-handling of LispMe's dialog.

Category Primitive procedure
Format (own-gui switch)
Parameters
switchany object
Description When switch is true, most controls and fields in LispMe's main dialog are set unusable, so that they won't respond to events and you can handle events by yourself. The only exception is the break button which is never disabled to allow interrupting the process.

When switch is false, LispMe's main dialog responds to events as usual. The return value is switch.

R4RS Compliance LispMe extension
Examples
(own-gui #t) => #t

pair?

pair? recognizes a cons cell.

Category Primitive procedure
Format (pair? obj)
Parameters
objany object
Description pair? returns #t for a non-empty list (a cons-cell) and #f for any other object.
R4RS Compliance Full
Examples
(pair? '(a b c)) => #t
(pair? '()) => #f
(pair? 42) => #f

peek-char

peek-char returns the next character from an input port.

Category Primitive procedure
Format (peek-char inport)
Parameters
inportan input port
Description peek-char reads ahead the next character from the input port inport and returns it, but doesn't advance the input position. If the end of file is reached, a unique end-of-file object (which is recognized by eof-object?) is returned.
R4RS Compliance The port parameter is not optional.
Examples
(peek-char (open-input-file "foo")) => #\b, assuming the memo "foo" starts with
bar,123...

pen-down

pen-down is posted when the pen touches the screen.

Category UI event
Format (pen-down x y)
Parameters
xWindow-relative x coordinate in pixels
yWindow-relative y coordinate in pixels
Description pen-down is the first event posted when the user taps the screen with the pen. This event normally causes other events like lst-enter afterwards.

pen-move

pen-move is posted when the pen is moved on the screen.

Category UI event
Format (pen-move x y)
Parameters
xWindow-relative x coordinate in pixels
yWindow-relative y coordinate in pixels
Description pen-move is the event posted when the user moves the pen across the screen. Some kinds of UI element track pen movement by themselves, so you won't see this event.

pen-up

pen-up is posted when the pen is lifted from the screen.

Category UI event
Format (pen-up x y)
Parameters
xWindow-relative x coordinate in pixels
yWindow-relative y coordinate in pixels
Description pen-up is the event posted when the user lifts the pen from the screen. Some kinds of UI element track pen lifting by themselves, so you won't see this event.

pop-select

pop-select is posted when an item in a popup-list has been selected.

Category UI event
Format (pop-select pid lid newsel oldsel)
Parameters
pidthe form id of popup trigger
lidthe form id of the list
newselthe zero-based index of the selected item
oldselthe zero-based index of the previously selected item
Description pop-select is the event posted when the user has selected an item in a popup list.

port?

port? recognizes any port.

Category Library procedure
Format (port? obj)
Parameters
objany object
Description port? returns #t for an input port or an output port and #f for any other object.
R4RS Compliance Full
Examples
(port? (open-output-file "foo")) => #t
(port? (open-input-file "bar")) => #t
(port? "baz") => #f

positive?

positive? tests, if a number is positive.

Category Library procedure
Format (positive? num)
Parameters
numa number
Description positive? returns #t, if num is positive. Otherwise it returns #f. See also negative? and zero?.
R4RS Compliance Full
Examples
(positive? 42) => #t
(positive? 0) => #f

procedure?

procedure? recognizes procedures.

Category Primitive procedure
Format (procedure? obj)
Parameters
objany object
Description procedure? returns #t for a procedure and #f for any other object. Procedures include both closures returned by lambda and continuations created with call/cc
R4RS Compliance Full
Examples
(procedure? (lambda (x) x)) => #t
(call/cc procedure?) => #t
(procedure? 'foo) => #f

promise?

promise? recognizes promises.

Category Primitive procedure
Format (promise? obj)
Parameters
objany object
Description promise? returns #t for a promise returned by delay and #f for any other object. It doesn't matter, if the promise has already been forced.
R4RS Compliance Full
Examples
(promise? (lambda (x) x)) => #f
(call/cc promise?) => #f
(promise? (delay 5)) => #t
(promise? 5) => #f

quasiquote

quasiquote builds (almost) constant objects
Category Special form
Format
(quasiquote template)
`template
Parameters
template any object, most usually a list or a vector
Description quasiquote returns template unevaluated, if it doesn't contain any of the special forms unquote or unquote-splicing.

If a comma (called an unquote expression) appears within template, the expression following it is evaluated and the result is inserted into the template instead of the unquote expression.

If an at-sign immediately follows the comma (called an unquote-splicing expression) the expression must evaluate to a list and its elements are inserted into the template instead of the unquote-splicing expression.

quasiquote forms can be nested. Substitutions are made only for unquoted expressions at the same nesting level of the outermost quasiquote. The nesting level increases in each quasiquote and decreases in each unquotation.

In contrast to quote, the structure returned is always newly allocated.

quasiquote may be abbreviated with a back apostrophe `. The Graffiti stroke for this is "dot, stroke north-west and back".

R4RS Compliance Full
Examples
`(list ,(* 5 6) a b) => (list 30 a b)
`#(3 4 (,(sqrt 9) 5) ,@(reverse '(x y z)) foo) => #(3 4 (3 5) z y x foo)
`(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f) => (a (quasiquote (b (unquote (+ 1 2)) (unquote (foo 4 d)) e)) f)

quote

quote returns its unevaluated argument.

Category Special form
Format
(quote obj)
'obj
Parameters
obj any object
Description quote returns obj unevaluated. Use quote to imbed constants in your code. quote may be abbreviated with a single apostrophe '
R4RS Compliance Full
Examples
(quote (a b c)) => (a b c)
'(a b c) => (a b c)
''(a b c) => (quote (a b c))

quotient

quotient divides two integers ignoring the remainder.

Category Primitive procedure
Format (quotient int1 int2)
Parameters
int1an integer
int2an integer
Description quotient divides two integer numbers truncating the result to an integer. Division by zero is an error.
R4RS Compliance Full
Examples
(quotient 7 3) => 2
(quotient -5 4) => -1
(quotient 3 0) => error

random

random generates a random integer.

Category Primitive procedure
Format (random int)
Parameters
intan integer
Description random generates a random number in the range [0..abs(int)-1]. int may not be 0 or an error results.
R4RS Compliance LispMe extension
Examples
(random 100) => 47
(random 100) => 11
(random -2000) => 1234
(random 0) => error

read

read parses data read from an input port.

Category Primitive procedure
Format (read inport)
Parameters
inportan input port
Description read reads an object from the input port inport. It uses the standard LispMe parser to create an object from its textual representation, so all kind of syntax errors are possible. In this case, the input position of inport is not advanced. The type of the object is solely determined by the data input. If the end of file is found while reading, a unique end-of-file object (which is recognized by eof-object?) is returned.
R4RS Compliance The port parameter is not optional. Use input to let the user input an expression.
Examples
(read (open-input-file "foo")) => bar, assuming the memo "foo" starts with
bar,123...

read-char

read-char reads a single character from an input port.

Category Primitive procedure
Format (read-char inport)
Parameters
inportan input port
Description read-char reads a single characters from the input port inport and returns it. If the end of file is found while reading, a unique end-of-file object (which is recognized by eof-object?) is returned.
R4RS Compliance The port parameter is not optional.
Examples
(read-char (open-input-file "foo")) => #\b, assuming the memo "foo" starts with
bar,123...

read-line

read-line reads a line of text from an input port.

Category Primitive procedure
Format (read-line inport)
Parameters
inportan input port
Description read-line reads successive characters from the input port inport until a line feed is encountered and returns all chars read as a string. If the end of file is found while reading, a unique end-of-file object (which is recognized by eof-object?) is returned.
R4RS Compliance LispMe extension. Use input-string to let the user input a string.
Examples
(read-line (open-input-file "foo")) => "bar,123...", assuming the memo "foo" starts with
bar,123...

read-record

read-record reads a record from an arbitrary Pilot DB.

Category Primitive procedure
Format (read-record dbname recnum)
Parameters
dbnamea string naming the database
recnuman integer
Description read-record opens the Pilot database named dbname (case-sensitive!) and reads the record with index recnum from there. The record is returned as a string. If either the database or the index doesn't exist, #f is returned.
R4RS Compliance LispMe extension.
Examples
(read-record "MemoDB" 42) => "Whatever your memo contains#00"

read-resource

read-resource reads a resource from any open resource DB.

Category Primitive procedure
Format (read-resource restype resid)
Parameters
restypea string of 4 characters
residan integer
Description read-resource searches all open resource databases for a resource of type restype with resource id resid and returns it as a string. If the resource is not found, #f is returned.

Searched resource databases are

  1. a user interface DB opened by set-resdb
  2. LispMe itself
  3. System resources
The restype parameter determines the type of the resource to be read and is written as a string of 4 bytes, which is more readable than the Pilot API convention which builds a 32-bit integer from the 4 bytes. Please refer to the PalmOS documentation for more detailed information about Pilot resources.
R4RS Compliance LispMe extension.
Examples
(read-resource "tSTR" 9058) => "There's not enough memory to grow the memo#00", a help message from LispMe itself.

real-part

real-part computes the real part of a complex number.

Category Primitive procedure
Format (real-part z)
Parameters
zany number
Description real-part computes the real part of the number z.
R4RS Compliance Full
Examples
(real-part 5.1) => 5.1
(real-part 0.5+2i) => 0.5
(real-part 7.2@1.8) => -1.63585508179022

real?

real? recognizes real numbers.

Category Primitive procedure
Format (real? obj)
Parameters
objany object
Description real? returns #t for integer and real numbers and #f for any other object.
R4RS Compliance Full
Examples
(real? 42) => #t
(real? -1.234e-55) => #t
(real? 3.5-17i) => #f
(real? 'foo) => #f

rect

rect draws a filled rectangle.

Category Primitive procedure
Format (rect x y radius)
Parameters
xan integer
yan integer
radiusan integer
Description rect draws a filled rectangle from the current point stored in *gstate* to (x,y) using the colors, drawing pattern and drawing mode stored in *gstate*. radius is used for rectangles with rounded corners, it specifies the radius of a circle by which the corners are rounded. To draw a plain rectangle, use 0 for radius. After that, the current point is updated to (x,y).

See here for details on the graphic state. The return value is #n to avoid trashing the graphics.

R4RS Compliance LispMe extension
Examples
(rect 100 80 10) => #n and draws a rectangle to (100,80) with rounded (radius=10) corners as described above.

remainder

remainder divides two integers and returns the remainder.

Category Primitive procedure
Format (remainder int1 int2)
Parameters
int1an integer
int2an integer
Description remainder divides two integer numbers and returns the remainder. The sign of the result is always the sign of the dividend (or 0), in contrast to modulo. Division by zero is an error.
R4RS Compliance Full
Examples
(remainder 13 4) => 1
(remainder -13 4) => -1
(remainder 13 -4) => 1
(remainder -13 -4) => -1
(remainder 13 0) => error

reverse

reverse reverses a list.

Category Library procedure
Format (reverse list)
Parameters
lista proper list
Description reverse creates a newly allocated list consisting of the elements of list in reverse order.
R4RS Compliance Full
Examples
(reverse'(a b c d)) => (d c b a)
(reverse '((a b) (c d))) => ((c d) (a b))

rgb->index

rgb->index finds the nearest palette entry for a color.

Category Primitive procedure
Format (rgb->index r g b)
Parameters
ran integer in the range 0-255, red part
gan integer in the range 0-255, green part
ban integer in the range 0-255, blue part
Description rgb->index searches the system colortable (palette) for a color matching the given r g b values. The algorithm is described in the SDK docs:

Palm OS SDK Reference Palm OS 3.5 supports a maximum of 256 colors. The number of possible RGB colors greatly exceeds this amount. For this reason, an exact match may not be available. If there is no exact RGB match, then a luminance best-fit is used if the color lookup table is entirely gray scale (red, green, and blue values for each entry are identical), or a shortest-distance fit in RGB space is used if the palette contains colors. RGB shortest distance may not always produce the actual closest perceptible color, but it's relatively fast and works for the system palette.

The result is an integer denoting the best palette entry. On systems running older OS versions than 3.5, 0 is returned.

R4RS Compliance LispMe extension
Examples
(rgb->index 145 49 213) => 46 (256 colors)
(rgb->index 145 49 213) => 10 (16 grays)

round

round rounds a number to the closest integer.

Category Primitive procedure (MathLib required)
Format (round num)
Parameters
numa number
Description round converts num to a floating point number and returns the closest whole number. The result is not a LispMe integer, it's a floating point value.

See also ceiling, floor, and truncate.

R4RS Compliance Full
Examples
(round -4.3) => -4
(round 3.5) => 4

Catalog of Language Elements S - Z