In builtin function parameter lists, parameters set in italic are evaluated before use, while underlined parameters aren't.
Interpreter & Debug
Constants meaning ( ) and true, respectively. These evaluate
to the same
nil and T object each time. If you need to create
new instances, you can use
The following constants are defined for error codes:
|SE_UNDEF||Undefined symbol (variable lookup failed).|
|SE_PARM||Invalid parameters (many builtins return this when they don't like their input).|
|SE_WFUNC||Invalid function (trying to run a non-function).|
|SE_IPLIST||Non-symbol in parameter list of function.|
|SE_PNUM||Insufficient parameters (when calling a builtin or user function).|
|SE_IO||I/O error (eg. upon failure to open a file to be loaded).|
|SE_NFND||Not found (the package asked for by |
|SE_LIMIT||Recursion limit exceeded.|
|SE_MEM||Memory allocation error (shouldn't happen).|
|SE_MATH||Math exception (eg. division by zero).|
|SE_LAST||The first error code not used by the system.|
*input-stream*- all read operations work on this stream, on startup equals
*output-stream*- all print operations work on this stream, on startup equals
Returns p unevaluated.
Evaluates name then sets the resulting symbol name to value.
Multiple name-value pairs may be given; returns the
value of the last assignment. Note that evaluation isn't atomic,
it happens by pairs (so
(set 'a 1 'a (+ a 1)) gives
Like set, except if it can't find the variable in the local variable context, it checks the parent variable context, and so on. It updates the first existing variable it can find; if there wasn't one, it sets the variable in the global context instead of the local one.
Set the CAR of the CONS to value. You can use this instead of
Accompanies scar: sets the CDR of the CONS to value.
Evaluate all expressions twice, so that e.g.
(eval '(+ 1 2)) will yield 3 (the first evaluation
(+ 1 2), then that gets evaluated again).
Returns the result of the last expression.
Creates a local variable context and executes all expressions in it. Returns the result of the last expression. The effect is not unlike that of a function call; sets will have only local effect.
Creates a local weak variable context, assigns some variables in it,
then executes all expressions in it. Returns the result of the last
let statement looks like this:
> (let ((a 2) (b 3) (c 0)) (set 'c (+ a b)) c) 5
The assignment list is a list of lists. Each inner list has two elements: a symbol and a value.
Context weakness means that new bindings are forwarded to the parent context:
> (set 'a 1 'b 2) (let ((a 2)) (set 'a 3) (set 'b 1)) (cons a b) (1 . 1)
Calls the function func with list given as parameters. Returns the result. When func is a user function, the elements of the parameter list get evaluated, just like a normal function call. This helps macro and builtin functions work as expected.
Calls the function func with the rest of the arguments given as parameters.
Returns the result. The difference between this and
(func ...) is that builtin object substitution
isn't done (so
(+ 1 2) doesn't get rewritten
(builtin:+ 1 2)).
This is a variation of apply. It does the same thing, except the function is executed in the parent variable context. Note that while the evaluation of the parameter list argument to elev happens in the current variable context, the evaluation of each parameter (before passing to the function) is performed in the parent variable context.
Returns the list the macro func would expand to if called with the args argument list.
Returns T if all objs evaluate to the same object in memory.
If the objects are all from the same type: integer, number, symbol or string, returns T if all objects have the same value. Otherwise, returns T if the objects are the same object in memory.
Like eql, but checks objects
CONSes and arrays) deeply for value equivalence.
Simply evaluates all its parameters and returns the last result.
Returns a user function that receives parameters by the names
listed in paramlist, with a body executing all expressions.
The function will return the result of the last expression.
(set 'square (lambda (x) (* x x))) (square 3) 9
Returns a user macro. The result works like a function, except
for two things: the parameters aren't evaluated as they're registered
in the function variable context (i.e. if the user passes
the macro gets
'a instead of
a); and that
the S-expression invoking the macro gets replaced by the results of
the macro and is evaluated again.
This means that macros can be used to generate code using their arguments
and execute it transparently. Here's a sample implementation of
setq as a macro:
(set 'setq (macro (name value) (list 'set (list 'quote name) value) ))
Works exactly like macro, except the result doesn't replace the invoking S-expression; the macro function is executed each time it's invoked.
Returns a symbolic macro function. This is a special object: when any symbol evaluates to such an object, the macro function body is executed (with no arguments), the result replaces the original symbol in the code and is evaluated again. Thus, by binding symbolic macros to symbols one can create "magic variables". For example:
> (set '*rnd-count* 0) 0 > (set 'rnd (symbolic-macro () `(list ,(setg '*rnd-count* (+ 1 *rnd-count*)) ,(random 100)))) m:RND() > rnd (1 58) > rnd (2 73) > rnd (3 50)
Exactly like symbolic-macro, except the macro result doesn't replace the invoking symbol; the macro function is executed each time the symbol is evaluated. Extending the previous example:
> (set 'getrnd (lambda () rnd)) l:GETRND() > (getrnd) (22 2) > (getrnd) (22 2) ;; the same, since the symbol in the function has been replaced ;; use r-symbolic-macro to avoid this behavior > (set 'rnd (r-symbolic-macro () `(list ,(setg '*rnd-count* (+ 1 *rnd-count*)) ,(random 100)))) m:RND() > (set 'getrnd (lambda () rnd)) l:GETRND() > (getrnd) (23 26) > (getrnd) (24 33)
Returns a CONS object: ( a . b ). Both parameters are mandatory.
Returns a list with all the parameters as elements.
All parameters must be lists, except the last one, which might be an atom.
Returns the concatenation of all parameters into a single list (if the
last parameter is an atom, it is used in the list as a terminator of the
last CONS, instead of a
Returns the left object of the obj CONS.
Returns the right object of the obj CONS.
Returns the number of elements in a list.
If called with a string or a blob argument, returns the number of characters in the string or blob.
Calls func with consecutive parallel sets of elements from the lists until the shortest list runs out. Returns the list built from the return values.
Like mapcar, except the parameters given to the function are the full remainders of the lists instead of cars.
Like mapcar, except the return list is built from those values of the lists for which the function returns true. If there's more than one list, the return list will contain lists of the parallel sets:
> (filter (lambda (x y) (> (+ x y) 5)) '(4 5 6) '(1 2 3)) ((5 2) (6 3))
Like filter, except the parameters given to the function are the full remainders of the lists instead of cars. The return list is still built the same way.
If tval isn't
nil, executes trueexp. If tval
nil, the optional falseexp is executed if given.
Returns the result of the executed expression.
Each clause for cond has to be a list. The first element of the
first clause is evaluated; if this results in non-
the rest of the elements in the clause are evaluated and the result of the
last one is returned. Otherwise, processing moves on to the next clause.
If there are no more clauses left (all tests returned
nil is returned.
This is a loop construct: first evaluates exp and exits if it's
nil. After, it executes the (optional) body expressions, then
repeats the cycle. Returns the result of the last evaluation of the truth
nil that is; except when return
was called inside to return a specific value.
A do statement looks like this:
> (do ((x 1 (+ x 1)) (y 1 (* y 2))) ((> x 5) y) (println y) (println 'working) ) 1 working 2 working 4 working 8 working 16 working 32
The first part of a
do specifies what variables to bind, what
their initial values are, and how to update them. The second part specifies a
termination condition and a return value. The last part is the body. A
do form binds its variables to their initial values like a let, then checks the termination condition. As long as the
condition is false, it executes the body repeatedly; when the condition becomes
true, it returns the value of the return-value form (if given; otherwise it
returns the non-
nil value of the condition).
Catch/process an error. codelist should contain a list of integers:
codes for the errors one wishes to catch; or it can be
everything (any error) needs to be caught. If evaluating the expressions
generates a suitable error, func will be called with three parameters:
error code, error message, and an error object if supplied (
nil if not);
the result is returned. If no error occurs, it evaluates all expressions
and returns the result of the last one. If there's an uncaught error, it passes
it down. (This means if an error occurs, caught or uncaught, no futher
expressions will be evaluated.)
> (catch (list SE_PARM) (lambda (code msg obj) (list code msg obj)) (+ 1 2) (/ 2 0)) ERROR SE_MATH: Division by zero at stdin:1 > (catch (list SE_MATH) (lambda (code msg obj) (list code msg obj)) (+ 1 2) (/ 2 0)) (12 "Division by zero" nil) > (catch (list SE_PARM) (lambda (code msg obj) (list code msg obj)) (throw SE_PARM "go away" '(1 2 3))) (2 "go away" (1 2 3))
Create an error of code (integer, see error codes), with optional message and optional object.
Throws a SE_RET with no message and the object set to val
Returns T if obj equals
Returns the first
nil parameter and doesn't evaluate the rest.
If there's none, returns the value of the last parameter.
Returns the first non-
nil parameter and doesn't evaluate
the rest. If there's none, returns
Primitive algebraic functions. Without parameters + returns 0,
* returns 1 (the identity). With one parameter given, -
returns 0 - n, / returns (1 / n).
+ supports strings (concatenation).
There's a special kind of multiplication supported: string by integer (only in the
(* string integer) special form).
(* "abc" 3) gives
"abcabcabc". Negative integers
will flip the result:
(* "abc" -3) gives
Where applicable, if floats are mixed with integers in the argument list,
these functions will promote integers to floats. For example,
(/ 5 2) gives
2 (an integer), but
(/ 5 2.0) gives
Algebraic predicates. If given one parameter, they all return T;
otherwise, they return T only if the respective relation is true
for any two neighboring parameter.
These predicates support strings and symbols (by case sensitive strcmp comparison). Integers and floats can be compared, but strings and symbols cannot (without type conversion).
Returns num1 modulo num2 (modulo num3 etc).
~int (bitwise negation).
Returns the arguments bitwise OR-ed together (inclusive OR). When called with zero arguments, it returns 0 (identity).
Returns the arguments bitwise AND-ed together. When called with zero arguments, it returns -1 (identity).
Returns the arguments bitwise XOR-ed together (exclusive OR). When called with zero arguments, it returns 0 (identity).
The following standard mathematical functions are available:
Returns a random floating point number between 0 and 1 (multiplied by mult, if supplied).
Returns a random integer between 0 (inclusive) and limit (exclusive). If limit is negative, all returned integers will be negative too.
If limit is a list, returns a random element.
Creates an array. Dimensions is a mandatory parameter: a list of integers that specifies the sizes of array dimensions. The maximum number of dimensions an array can have are limited at compile time.
The initializer is an optional list to initialize the array content.
If the array has multiple dimensions, the list will have to be a nested list.
The array is initialized to
nils by default.
Here's an example involving a multidimensional array:
> (set 'ar (make-array '(2 2 3) '(((1 2 3) (4 5 6)) ((7 8 9) (10 11 12))))) #A<<<1 2 3> <4 5 6>> <<7 8 9> <10 11 12>>> > (aref ar 0 1 2) 6 > (aset ar 0 1 2 "!") "!" > ar #A<<<1 2 3> <4 5 "!">> <<7 8 9> <10 11 12>>>
Returns an item from an array, located by the specified indices. The number of indices given must be equal to the number of dimensions of the array.
Sets an item in an array located by the specified indices. The number of indices given must be equal to the number of dimensions of the array.
Returns the dimensions list of an array.
Returns a new, empty dictionary. A dictionary maps arbitrary keys to values. Keys have to be atomic: use integers, floating point numbers, symbols and strings, nothing else.
Returns the value associated with key in the dictionary.
If the key is not found, returns
Assigns the value to the key in the dictionary. If the dictionary already has a value bound to key, the binding is updated.
Deletes an item from the dictionary (returns
an item was found and deleted,
Returns a list of all keys in the dictionary.
Returns a portion of string, beginning at start
(default 0, the string is just copied), up to len characters
(by default, until the end of the string). If start is negative,
it's interpreted relative to the end of the string (e.g.
(substr "stutter" -3) gives "ter"). If len is negative,
it's also interpreted relative to the end of the string (e.g.
(substr "stutter" 1 -3) gives "tut").
Returns string with all characters capitalized.
Returns string with all characters converted to lower case.
Returns a list of strings, each of which is a substring of string formed by splitting it on boundaries formed by the string separator. If limit is set, the returned list will contain a maximum of limit elements with the last element containing the rest of string.
If separator is an empty string, returns
Returns the string with head and tail whitespace removed.
Returns the byte from the character (as an integer).
Returns a character of byte code.
This function takes a UTF-8 encoded string and returns the number of characters in it.
Prints the obj CONS object recursively, using the full dotted
Dumps name-value bindings in the current variable context.
Performs garbage collection. Returns number of objects freed.
Enables tracing for a user function.
Disables tracing for a user function.
Parses the files in the global variable context. If there's a parse error, returns immediately; otherwise, returns the result of the last expression in the last file.
Parses the files in the local variable context. If there's a parse error, returns immediately; otherwise, returns the result of the last expression in the last file.
Looks for a file named package.stt in the specified include path and loads the first one found (in the global variable context).
Looks for a file named package.stt in the specified include path and loads the first one found (in the local variable context).
Evaluates the specified expressions while setting the recursion limit. Use it with trace to track down infinite recursion bugs.
Exits the interpreter with the optional returnvalue (0 by default).
Returns obj converted to a number, if it can.
Returns obj converted to an integer, if it can.
Returns obj converted to a string, if it can.
Returns obj converted to a symbol, if it can.
Returns obj converted to a blob, if it can.
Returns t if obj isn't a
Returns t if obj is a valid list:
or a list that has
nil in the last
Returns t if obj is a user-defined or builtin function.
Returns t if symbol resolves to a value in the current variable context (i.e. whether it's defined in the current context or any of its parents).
Returns t if symbol is defined in the local variable context.
These additional predicates exist for checking types:
Prints the values of objects, separated by spaces. Returns the value of the last evaluated object.
Works exactly like print, except it prints a final newline.
Prints the values of objects, separated by spaces. Returns the value of the last evaluated object. Doesn't print quotes around strings.
Works exactly like princ, except it prints a final newline.
Reads and returns one expression; throws SE_PARSE on a
parse error. Returns
EOF on EOF.
The stream parameter
*input-stream* is used by default.
Reads a single character and returns it.
EOF on EOF.
The stream parameter is optional,
*input-stream* is used by default.
Reads a single line and returns it. Returns
The stream parameter is optional,
*input-stream* is used by default.
Unreads a character into a stream, so the next read from the stream will yield the character as the result. No two subsequent unreads may be done on a stream without an intermittent read.
Returns a user stream created from the lambda function.
Opens a file and returns a stream. Both arguments have to be
strings. The mode argument
works like that of
fopen (in fact, the function itself
is mostly a wrapper for
fopen), but is optional
"r"). Close this stream by
close-file when you're done with it.
SE_IO on error (if, for example, the file
to be opened for reading doesn't exist).
Closes a file stream.
Returns a special, write-only stream that collects all output inside. You have to empty the container to retrieve the output (as a string or a blob) and to free up memory. After this, the bucket is fully reset and reusable.
Returns the contents of a bucket stream as a string, and empties the bucket. If the blob? argument is given and true, the data is returned as a blob.
Connects as a client to a named internet host, on the specified
port. Returns a readable/writable (blocking) stream. Throws
SE_IO on any sort of error (e.g. DNS lookup error, connection
Closes TCP stream. Might throw
SE_IO on error.
Returns number of seconds since the Epoch (an integer).
Returns time in a decoded form (the time parameter is an optional integer (number of seconds since the Epoch), if not supplied, the current time is used). You get a list of nine elements:
(seconds minutes hours day-of-month month year day-of-week daylight-savings-p time-zone)
0 is Monday for
Returns number of seconds since the Epoch, with (floating point) sub-second precision.
Constructs unix time from a broken down representation.
Sleep t (integer) seconds.
Returns the value of the environment variable by name,
nil if it's not found.
Renames/moves file "name1" to "name2". Throws
SE_IO on error.
Unlinks file. Throws
SE_IO on error.
Reads the directory at path; returns a
cons with a
car that's the list of directories, and a
that's the list of files found there. Throws
SE_IO on error.
Outputs the contents of the blob to
Reads at most size bytes from
and returns the result as a blob. May return
EOF if there
was nothing to read.
Returns a part of the blob. Semantics are similar to that of substr.
Find a blob inside another blob. Returns offset, or -1 if not found.
By default, returns the leftmost result. If the right? parameter is given and is true, returns the rightmost result.
If given, the start parameter specifies the position where to begin the search. When right? is true, should be given as the offset of the first byte after the last potential needle (in other words, the origin is the length of the haystack).
Compares two blobs (like
memcmp; returns an integer).
Tries to take the string value of a blob. Will throw
if the blob contains a zero byte.
Opens database dbname and returns an SQLite handle.
Closes an SQLite session.
Executes a query and returns the results in a list of rows. Each row is returned as a list. Before the first row, the names of the columns are returned (also in a list).
If the optional lambda is specified, the behavior is different:
the user function is called for each row with two arguments (the row
as a list and a list of column names). At the end,
Prepares/compiles an SQL statement (only one). Returns a statement handle. This handle needs to be freed with sqlite-finalize before sqlite-close is called.
Finalizes (frees) a statement.
Binds a value to a statement parameter. The parameter index
must either be an integer (starting with 1), or a string to bind
named parameters. The value can be an
nil (for NULL).
Returns the number of parameters a statement takes.
Resets a statement (so it can be executed again with sqlite-step, possibly with different parameter bindings).
Returns the names of columns of the resultset a statement would return.
Executes/continues execution of a statement. Each call will return
the next row of the results in a list; or
nil when there
are no more rows to be returned (it's an error to call again after this
has happened (before a statement reset)).
This is a Tesco Value SAX-style XML parser. It reads from
*input-stream*. For each start tag, it calls func-start:
(func-start "tagname" attribute-list)
attribute-list is an assoclist. For each end tag,
it calls func-end with the tagname; and for each block of character data,
it calls func-text with a string.
It returns when
EOF is encountered (and in this case, returns
or whenever one of the callbacks returns
nil (so if you want
continuous reading until
EOF, you can always return
Character data is returned as it is in the file, but
entities will be decoded into
This returns the string encoded so it can be included in XML output.
(So characters like
get replaced with entities, etc.)
Use utf8-xmlencode instead.
This is like xmlencode, but it's
aware. Better use this one.
Returns the string encoded so it can be included in a URL.
Decodes a urlencoded string and returns the result.
Connects to a PostgreSQL database using the conninfo connection
description. Returns a connection handle, or throws
Closes the connection described by the conn handle. Done automatically when the handle is harvested by the GC.
Executes the SQL script given in the string command. Returns
a resultset handle for the last executed statement, or throws
SE_PGSQL on error.
Executes a single SQL statement, binding the strings in the
params list as arguments, and returns a resultset
handle. All input data has to be specified as strings.
> (pq-get (pq-exec-params conn "SELECT $1::INTEGER + $2::INTEGER" '("1" "2")) 0 0) "3"
Frees memory associated with a resultset. The resultset can't be used any more. Done automatically when the handle is harvested by the GC.
Returns the number of tuples (rows) in a resultset (an integer).
Returns the number of fields (columns) in a resultset (an integer).
Returns the name of the field with number col (starting with 0).
Returns the number of the field with the specified name.
Retrieves a value from the resultset, from the cell with the
specified coordinates (row and column numbering starts from 0). If the
value is NULL,
nil is returned; otherwise a string.
Returns a full row from the resultset in a list.
Creates a prepared statement, under name stmtname, from the
specified query, with nparams arguments. If the given stmtname
is the empty string, an anonymous prepared statement is created;
this replaces the previous such statement. With named statements, the
same name may be used only once per session (or you can remove
the prepared statement by the SQL command
Invokes the prepared statement by the specified name, with the arguments in the params list. Returns a resultset handle.
Compiles pattern as a Perl 5 compatible regular expression,
and returns a handle the matching functions would use.
SE_PCRE on error.
Tries to match the pattern (a handle got from
pcre-compile) to the subject string.
Returns offset of the matching substring (an integer), or
nil if there was no match.
Finds the first match of the pattern on the subject string. On a succesful
match, a list is returned that contains the substrings captured by parentheses,
plus the entire matching substring first; on no match,
Tries to match the pattern to the subject string as many times as possible. A list is returned that has as many elements as successful matches were made; each element is a list itself, similar to what pcre-match1 would yield.
Splits up the subject string at boundaries matched by the pattern. Returns a list of the resulting pieces.
Replaces the first occurrence of the pattern in the subject string
by a replacement string, and returns the result.
The replacement string may countain references
to the parent's captured substrings, as
is a single digit between 0 and 9) or
is an integer not smaller than 0). The zeroth substring is the entire
matched string; the captured subtrings follow from 1. A literal backslash
as replacement has to be escaped as
Works similarly to pcre-replace1, but replaces all occurrences.