Library and extended functions reference

Boolean values

#f is false, and every other value is true. The default truth value is #t.

Builtin special forms

signature description
(quote val)
(cond (cond1 do1 do2 ...) (cond2 do1 do2 ...) ...)
(if cond then else)
(and ...)
(or ...)
(while cond . bodies)
(lambda args . bodies) args is a list or dotted list.
(begin ...)
(set! sym expr) set lexically-bound variable (sym is not evaluated)
(trycatch body func) if an exception occurs evaluating body, func is invoked with the exception as its argument
(for lo hi (lambda (n) body)) fast bounded iteration. the supplied function is invoked successively for n from lo to hi, inclusive.
(prog1 expr1 expr2) evaluate expr1 and expr2 in order, then return the result of expr1

Standard builtin functions


eq?, eqv?, equal?, atom?, not, null?, symbol?, number?, boolean?, bound?, pair?, builtin?, vector?, fixnum?, procedure?


cons, list, car, cdr, set-car!, set-cdr!


eval, apply, return


+, -, *, /, div, div0, mod, mod0, <, =


vector, aref, aset!, length

Nonstandard builtin functions

signature description
(raise val) raise an exception (any value)
(compare a b) perform an ordered comparison of any two values. returns -1, 0, or 1, for ab, respectively
lognot, logand, logior, logxor, ash bitwise not, and, or, xor, bit shift

Standard library


label, define, define-macro, let, let*, letrec


map, append, append!, assoc, assv, assq, member, memv, memq, caar, cadr, cdar, cddr, caaar, caadr, cadar, caddr, cdaar, cdadr, cddar, cdddr, every, any, list?, list-tail, list-ref, list*, last-pair, lastcdr, length=, length>, map!, mapcar, for-each, filter, count, foldr, foldl, reverse, reverse!, copy-list, copy-tree, map-int, iota, revappend, nreconc, delete-duplicates


char?, array?, /=, >, <=, >=, self-evaluating?, negative?, positive?, zero?, even?, odd?


when, unless, dotimes, do, case, error, throw, catch, unwind-protect, time, assert


backquote, macroexpand-1, macroexpand, list->vector, vector->list,, identity, 1+, 1-, abs, random, trace, untrace, traced?

Value constructors

signature description
(cons a b)
(list ...)
(vector ...)
(vector.alloc size [init]) make a vector of the given size, optionally initializing every element to the given value
(array ctype [elts ...]) make primitive (unboxed) array
(c-value ctype [init]) make c-value of the given type, optionally initialize
(table key val key val ...)

The following cvalue constructors are also available: int8, uint8, int16, uint16, int32, uint32, int64, uint64, byte, wchar, long, ulong, float, double


signature description
(symbol str) create an interned symbol with the given name
(gensym) create a unique symbol
(symbol-syntax sym) get the expander for a symbol, or nil if none
(set-syntax! sym function) set the macro expander function for the given head symbol
(top-level-value sym) get the top-level binding of a symbol. the argument is evaluated.
(set-top-level-value! sym val) set top-level binding. both arguments are evaluated.
(environment) get a list of bound global symbols
(constant? x) determine whether an expression is a constant
(load filename) read and evaluate all expressions in a file (filename is a string)
(exit [code]) quit interpreter

Global variables

name meaning
*install-dir* location of femtoLisp executable
*argv* list of command-line arguments (as strings)
*os-name* symbol indicating the platform where we're running
*print-pretty* enable pretty printing, default is #t
*print-width* number of columns used in prettyprinting, default 80
*print-readably* print values so they can be read back in, default #t
*stdin*, *stdout*, *stderr* io streams for standard descriptors
*input-stream*, *output-stream* current default io streams
*directory-separator* the directory separator on the local platform
*linefeed* the line terminator on the local platform


signature description
(string? x)
(string a b ...) append/construct
( str index [nchars]) increment a byte index by n characters (default 1)
(string.dec str index [nchars])
(string.count str i j) # of chars between 2 byte offsets
(string.width str) # columns when printed
(string.char str i) char at byte offset
(string.sub str i j) substring between 2 bytes offsets
(string.split str sep-str) split string on characters in sep-str string
(string.trim s at-start at-end) remove given chars from beginning and end of string
(string.reverse s)
(string.find s str|char [start offset])
( f str)
(string.encode wchar-array) convert to UTF8
(string.decode str) convert to UCS
(string.tail str n) drop n characters from the front of str
(number->string n [radix])
(string.lpad str n c) pad string to length n by adding character c on the left.
(string.rpad str n c) pad string to length n by adding character c on the right.
(string.rep s k) build a string of k copies of s
(string.join strlist sep) join strings from a list, with the given separator between them
(char.upcase c)
(char.downcase c)

Hash Tables

Hash tables use equal to compare keys.

signature description
(table? x)
(put! table key value) add or update key
(get table key [default]) look up key. if the key is not found, an exception is thrown unless a default value is specified, in which case it is returned.
(has table key) query whether table contains key
(del! table key) remove a key, throwing an exception if not found
(table.foldl f zero table) call (f k v X) for successive key/value pairs, where X is the previous result, starting at the given zero
(table.keys table)
(table.pairs table)
(hash val) compute a numeric hash for a value

IO Streams

done? signature description
Y (iostream? x)
Y (read [stream]) returns #f on end-of-file. call io.eof? after read to distinguish this from reading the false value.
Y (print val ...)
Y (io.print stream val ...)
Y (princ val ...)
Y (io.princ stream val ...)
Y (file name [mode options...]) mode options can be :read, :write, :append, :create, :truncate
Y (buffer) create an in-memory IO stream
(stream str)
Y (io.eof? s)
Y (io.write s cvalue)
Y ( s ctype)
Y (io.close s)
(io.copy to from [nbytes])
(io.copyuntil to from byte)
Y (io.flush s)
(io.pos s [new-pos])
( s offset)
(io.seekend s)
(io.trunc s size)
Y (io.getc s)
Y (io.putc c)
Y (io.tostring! s) destructively convert a buffer to a string
Y (io.readuntil s delim)
Y (io.readline s)
(io.readlines s)
(io.readall s)


done? signature description
(path.combine ...)
( p)
(path.absolute p)
(path.simplify p)
(path.homedir [user])
Y (path.cwd [new-cwd])

Time and date

done? signature description
Y (
( t)
(time.fromparts v)
Y (time.string t)
(time.fromstring s)


done? signature description
Y (os.getenv var)
Y (os.setenv var [val])


signature description
(truncate x) convert to integer of appropriate type
(fixnum x) convert to fixnum
(integer? x) is x an exact integer?
(integer-valued? x) is x integer valued?
(rand) get a random fixnum

C values

signature description
(sizeof x) size in bytes of c value or type
(typeof x) symbolic representation of the type of any value. returns one of the symbols pair, fixnum, symbol, vector, boolean, null, builtin, or function, or a cvalue type expression.
(copy x) copy a mutable c value
(plain-old-data? x) tells whether x is a plain binary data object (somtimes called a blittable object)
(dump x [offset [nbytes]]) print a hex dump of a plain-old-data value


signature description
(function str vals env) create a function object from the given bytecode string, vector of referenced values, and closed environment. femtolisp may crash if any of these is malformed.
(function:code f) get the bytecode string for a function
(function:vals f) get a function's vector of referenced values
(function:env f) get a function's closed environment
(compile lambda-expr) compile a lambda expression into equivalent bytecode
(disassemble f) print an easier-to-read representation of a compiled function