About Symbols

Symbols are very important and central to LispBM and also perhaps a bit different from identifiers/names used in languages such as C. A short introduction to symbols could be a good place to start.

One way to think about a symbol is as a name. Used as a name, a symbol can identify a value or function in the environment. A symbol can also be used as data in and of itself, more on this later.

NOTE Symbols are expressed as strings in your program such as a, let, define, + or orange. The "reader", the part of LBM that parses code, translates each symbol into a 28bit value. The string orange for example is only of interest if you print a symbol and then the runtime system will look up what string corresponds to the 28bit identifier you want to print. So the runtime system is never wasting time comparing strings to see if a symbol is this or that symbol, it's all integer comparisons.

You associate values with symbols using, define, let and you can change the value bound to a "variable" using set, setq or setvar.

Not all symbols are treated the same in LBM. Some symbols are treated as special because of their very fundamental nature. Among these special symbols you find define, let and lambda for example. These are things that you should not be able to redefine and trying to redefine them leads to an error. Symbols that start with ext- are special and reserved for use together with extensions that are loaded and bound at runtime.

Examples of symbols used as data are nil and t. nil represents "nothing", the empty list or other similar things and t represents true. But any symbol can be used as data by quoting it ', see Quotes and Quasiquotation .

Valid Symbol Names

A symbol is a string of characters following the rules: 1. The first character is a one of 'a' - 'z' or 'A' - 'Z' or '+-/=<>#!'. 2. The rest of the characters are in 'a' - 'z' or 'A' - 'Z' or '0' - '9' or '+-/=<>!?_'. 3. At most 256 characters long.

Note that lower-case and upper-case alphabetical letters are considered identical so the symbol apa is the same symbol as APA.

examples of valid symbols: apa apa? !apa kurt_russel_is_great

Numbers and numerical types

LBM supports signed and unsigned integer types as well as float and double. The numerical types in LBM are

• byte - unsigned 8bit value.
• i - signed 28bit value (56bits on 64bit platforms).
• u - unsigned 28bit value (56bits on 64bit platforms).
• i32 - signed 32bit value.
• u32 - unsigned 32bit value.
• i64 - signed 64bit value.
• u64 - unsigned 64bit value.
• f32 - (float) a 32bit floating point value.
• f64 - (double) a 64bit floating point value.

The byte and the char value have identical representation and type, thus char is an unsigned 8 bit type in LBM.

An integer literal is interpreted to be of type i, a 28/56bit signed integer value. A literal with decimal point is interpreted to be a type f32 or float value.

To specify literals of the other types, the value must be postfixed with a qualifier string. The qualifiers available in LBM are: b, i, u, i32, u32, i64, u64, f32 and f63. The i and f32 qualifiers are never strictly needed but can be added if one so wishes. An alternative way of writing byte literals is using Character literals (e.g. \#a).

So for example:

• 1b - Specifies a byte typed value of 1
• 1.0f64 - Specifies a 64bit float with value 1.0.
• \#a - Specifies a byte type value of 97.

Note that it is an absolute requirement to include a decimal when writing a floating point literal in LBM.

We are trying to make type conversions feel familiar to people who know a bit of C programming. On a 32bit platform LBM numerical types are ordered according to: byte < i < u < i32 < u32 < i64 < u64 < float < double. Operations such as (+ a b), figures out the largest type according to the ordering above and converts all the values to this largest type.

Example:

• (+ 1u 3i32) - Promotes the 1u value type i32 and performs the addition, resulting in 4i32.
• (+ 1 3.14) - Here the value 1 is of type i which is smaller than f32, the result 4.14f32.

A potential source of confusion is that f32 is a larger type than i64 and u64. this means that if you, for example, add 1.0 to an i64 value you will get an f32 back. If you instead wanted the float to be converted into a double before the addition, this has to be done manually.

Example:

• (+ (to-double 1.0) 5i64) - Manually convert a value to double.

The type-of operation can be used to query a value for its type. On the numerical types the type-of operation answers as follows:

• (type-of 1b) -> type-char
• (type-of 1) -> type-i
• (type-of 1u) -> type-u
• (type-of 1i32) -> type-i32
• (type-of 1u32) -> type-u32
• (type-of 1i64) -> type-i64
• (type-of 1u64) -> type-u64
• (type-of 1.0) -> type-float
• (type-of 1.0f64) -> type-double

Overflow behaviour

Operations on fixed bitwidth numerical types can lead to overflow. The ranges representable in 32bit LBMs integer types are the following:

• type-char : 0 - 255
• type-i : -134217728 - 1342177272
• type-u : 0 - 268435455
• type-i32 : -2147483648 - 2147483647
• type-u32 : 0- 4294967295
• type-i64 : -9223372036854775808 - 9223372036854775807
• type-u64 : 0 - 18446744073709551615

(+ 255b 1b)

0b

(- 0b 1b)

255b

(+ 134217727 1)

-134217728

(- -134217728 1)

134217727

(+ 268435455u 1u)

0u

(- 0u 1u)

268435455u

(+ 2147483647i32 1i32)

-2147483648i32

(- -2147483648i32 1i32)

2147483647i32

(+ 4294967295u32 1)

0u32

(- 0u32 1)

4294967295u32

(+ 9223372036854775807i64 1i64)

-9223372036854775808i64

(- -9223372036854775808i64 1i64)

9223372036854775807i64

(+ 18446744073709551615u64 1u64)

0u64

(- 0u64 1u64)

18446744073709551615u64

Cost of numerical operations

All Values in LBM are encoded in one way or another. The encoded value holds additional information about type and garbage collection mark bit. Operations that operate on an LBM value needs to unpack this encoded format and extract the actual numerical information from the representation. This has a cost and operations on numbers are in general a bit slower than what one gets in, for example C.

The chart below shows the time it takes to perform 10 million additions on the x86 architecture (a i7-6820HQ) in 32 and 64 Bit mode.

In 64Bit mode the x86 version of LBM shows negligible differences in cost of additions at different types.

For addition performance on embedded systems, we use the the EDU VESC motorcontroller as the STM32F4 candidate and the VESC EXPRESS for a RISCV data point.

In general, on 32Bit platforms, the cost of operations on numerical types that are 32Bit or less are about equal in cost. The costs presented here was created by timing a large number of 2 argument additions. Do not see these measurements as the "truth carved in stone", LBM performance keeps changing over time as we make improvements, but use them as a rough guiding principle.

Strings

LBM supports string literals, consisting of a pair of double quotes (") with a string of characters in between. These evaluate to a byte array containing the bytes of these characters (in the source code's encoding), followed by a zero byte.

Special characters can be written using escape sequences. They take the form of a backslash character (\) followed by some character from the list below and are replaced with their corresponding character at read time. A backslash followed by any other character is a read error.

Note that unlike other languages, single quotes (') can't be used to form string literals as it's busy being used for quoting! Therefore it doesn't need to be escaped within string literals.

Character literals

Individual characters can be written using character literals. They take the form of \# followed by any ASCII character (e.g. \#a or \#X), and evaluate to their corresponding numerical byte value (note the type!). Like strings, character literals also support escape sequences, in which case they evaluate to its value from the above table, and any invalid characters result in a read error.

\#a

97b

\#A

65b

\# 

32b

\#\n

10b

\#\\

92b

\#\0

0b

Syntax and semantics

Opinions on Lisp syntax varies widely depending on a persons programming experience and preferences. If you look around, or ask around you could find any of the following, and probably more views on lisp syntax:

• Concise and expressive Lisp syntax is quite minimalist, you can do a lot with very little syntax to learn about.
• Uniform and elegant Data and code are represented in the same way. This property is called Homoiconicity.
• Too many parenthesis A common complaint is that it can be easy to get lost in all the parantheses. While it may be easy to write lisp, it can be very hard to read someone elses code.

Lisp programs are written using S-expressions, a notation introduced by McCarthy. An S-expression describes a tree in an unambiguous way. An example of an S-expression is (+ 1 2) and the tree it represents is shown below:

Another example (+ (* a a) (* b b)) which as a lisp program means a² + b²:

In Lisp, which stands for "LISt Processor", a list is a right leaning tree ending in the symbol "nil". By convention these right leaning expressions are easy to write and requires only a few parentheses. The example below shows how the list created by lisp program (list 1 2 3 4) is represented as a tree:

A left leaning structure requires full parenthesization and can be expressed in lisp as (cons (cons (cons (cons nil 4) 3) 2) 1).

The conventions strongly favor the right leaning case.

There are no two different trees that correspond to a given S-expression and thus parsing of S-expressions is unambiguous. The unambiguous nature of S-expressions is useful in areas other than lisp programming as well. KiCad uses S-expressions to represent tree data in some of its file formats. Apparently WebAssembly uses S-expressions as well to describe WebAssembly modules

S-expressions are built from two things, Atoms and Pairs of S-expressions. So an S-expression is either:

• An Atom a
• A Pair a,b of S-expressions (a . b)

In LispBM the set of atoms consist of:

• Numbers: Such as 1, 2, 3.14, 65b, 2u32
• Strings: Such as "hello world", "door" ...
• Byte Arrays: Such as [1 2 3 4 5]
• Symbols: Such as a, lambda, define, kurt-russel ...

In LispBM a pair of S-expressions is created by an application of cons as (cons a b) which creates the pair (a . b). Convention is that (e0 e1 ... eN) = (e0 . ( e1 . ... ( eN . nil))).

A structure such as (e0 e1 ... eN) is called a list.

The meaning (semantics) that LispBM imposes on S-Expressions

The S-expressions discussed in the previous section are merely tree structures. The Lisp evaluator provides a computational interpretation for these trees. However, not all trees are valid Lisp programs. This section focuses on those trees that do make sense as Lisp programs and their meaning to the Lisp evaluator.

Values and expressions

The LispBM evaluator transforms expressions into values. For instance, the expression (+ 1 2) is evaluated to the value 3.

(+ 1 2)

3

In LispBM the distinction between expressions and values is often blurred. For example, it is possible to write a function that returns a result that can itself be interpreted as code

(defun mk-code (x) `(+ ,x 1))

(closure (x) 
  (append '(+) (list x) '(1))
  nil)

(mk-code 10)

(+ 10 1)

The result of evaluating (mk-code 10) is the list containing a +, 10 and 1. This list is the value that (mk-code 10) evaluates to. Now, the result of (mk-code 10), since it is valid lisp, can be evaluated.

(eval (mk-code 10))

11

In most cases this is quite natural and our functions will result in, Strings, lists and numbers that are easily and naturally understood as values.

Still, it is worthwhile to remember that values can be expressions and expressions can be values.

Errors

Some times evaluation is impossible. This could be because the program is malformed, a type mismatch or a division by zero (among many other possibilities). Errors terminate the evaluation of the expression. To recover from an error the programmer needs to explicitly trap it.

(trap (/ 1 0))

(exit-error division_by_zero)

Environments

LispBM expressions are evaluated in relation to a global and a local environment. An environment is a key-value store where the key is a lisp symbol and the value is any lisp value.

The rest of this section will now explain the meaning of LBM programs by informally showing expressions, what values they evaluate into and how they change and depend on the environments

Atoms

Some atoms, such as Numbers, Strings and byte arrays cannot be further evaluated.

10

10

"hello world"

"hello world"

[1 2 3 4]

[1 2 3 4]

Symbols evaluate by a lookup in the environment. First, the local environment is searched for a binding of the symbol. If unable to find a binding in the local environment, the global environment is searched. If unable to find a binding in the global environment as well, the runtime system attempts to dynamically load a binding using a system provided callback function. If all of the above fails to provide a value a variable_not_bound error is produced.

Composite forms

A composite form, such as (e1 ... eN) is evaluated in different ways depending on what e1 is. There are three major categories that e1 can fall into. Either e1 is something that represents a function and (e1 ... eN) is a function application. Or e1 is a so-called special-form that form the core of the LBM language. Or lastly, e1 is anything else and the composite form is malformed and will ultimately result in an error.

The composite form (e1 ... eN) is evaluated by first checking if e1 is a special form or not. if e1 is a special form the composite form is passed to a special-form evaluator. if e1 is not a special form, the composite form is evaluated as a function application. These two major branches of composite form evaluation are described below.

Special form evaluation

Below are a selection of basic special-forms in lispBM together with their evaluation process

• quote: (quote a) evaluates to a for any a
• define: (define s e), e is evaluated into v and the global environment is augmented with the pair (s . v)
• lambda: (lambda params body) is evaluated into '(closure params body env). env` is the local environment there the lambda expression is evaluated.
• if: (if e1 e2 e3) is evaluated by evaluating e1 into v1 if v1 is nil, e3 is evaluated otherwise e2 is evaluated.
• progn: (progn e1 e2 ... eN) is evaluated by evaluating e1 then e2 and so on until eN. The value v that eN evaluats into is the value (progn e1 e2 ... eN) evaluates to.
• and: (and e1 e2 ... eN) evaluates the eI expressions from left to right as long as they result in a non-nil value.
• or: (or e1 e2 ... eN) evaluates the eI expressions from left to right until there is a non-nil result.

and, or, progn and if evaluates expressions in sequence. if evaluates first the condition expression and then either the true or false branch. progn evaluates all of the expressions in sequence. In the case of and, or, progn and if, the constituent expressions are all evaluated in the same local environment. Any extensions to the local environment performed by an expression in the sequence is only visible within that expression itself.

• let: (let ((s1 e1) (s2 e2) ... (sN eN) e) eI are evaluated in order into vI. The local environment is extended with (sI . vI). sI is visible in eJ for J >= I. e is then evaluated in the extended local environment.
• setq: (setq s e) is evaluated by first evaluating e into v. The environments are then scanned for a binding of s. local environment is searched first followed by global. If a binding of s is found it is modified into (s . v).

If no binding of s is found when evaluating (setq s e) a variable_not_bound error is triggered.

Function application evaluation

The evaluation strategies explained here are applied to composite expressions of the (e1 ... eN) form where e1 does not fall into the category of "special forms".

In LispBM an (e1 ... eN) is evaluated by first evaluating e1. This is because depending on what kind of function object e1 evaluates into, the application if evaluated in different ways.

e1 should evaluate into a closure, a "fundamental operation" or an "extension". fundamental operations and extensions take their arguments passed on the stack while a closure is applied in an environment extended with the argument value bindings.

Depending on the value of e1 the arguments are either evaluated left to right and the results are pushed onto the stack, or they are evaluated left to right and used to extend the environment.

The quote and the quasiquote

The LBM parser (Reader) expands usages of the character sequences: ', `, , and ,@. The ' as in 'a is expanded into (quote a) for any a. The remaining `, , and ,@ are expanded into applications of quote, append and cons using the algorithms described by Bawden in quasiquotation in lisp.

Concurrency and Semantics

TODO: Finish section.

Functional and Imperative programming

To differentiate from Imperative and Functional, think of imperative programs as sequences of operations that update a state and functional programs as transformations of values through application of compositions of functions. Functional programming languages often let functions be values, which means that functions can be stored in lists, returned from other functions and so on

LispBM is a multiparadigm programming language. Most languages are a mix of functional and imperative and differ in what style it makes most convenient. At one end of this spectrum we find C which makes imperative easy and functional hard, and in the other end Haskell with the opposite favoritism. In LispBM we try to not unfairly favour any particular style over the other.

Picking a functional or an imperative style does have consequences though. Functional LispBM programs have properties such as persistence of data, that can be broken using the imperative part of the language.

With the imperative features of the language it is also in some places possible to peek under the hood of the runtime system. you can detect when and how environments are shared or copied for example. Please avoid exploiting the power of destructive updates for evil purposes.

The list below shows imperative operations from the core of LispBM. In the extension libraries there are many more of the kind.

• set - Destructively update a binding. Similar to C's =
• setq - Destructively update a binding. Similar to C's =
• setix - Destructive update of element in list.
• setcar - Destructive update of car field in cons cell.
• sercdr - Destructive update of cdr field in cons cell.
• setassoc - Destructive update of field in association list
• bufset - The bufset family of functions destructively updates ByteArrays.
• bufclear - Destructive clear of ByteArray.
• progn - Sequence operations.
• define - In LispBM, variables can be defined more than once. A second define of a variable is a destructive update.

Reference

Arithmetic

+

Adds up an arbitrary number of values. The form of a + expression is (+ expr1 ... exprN).

(+ 1 2)

3

(+ 1 2 3 4)

10

(+ 1 1u)

2u

(+ 2i 3.14)

5.140000f32

-

Subtract an arbitrary number of values from a value. The form of a - expression is (- expr1 ... exprN).

(- 5 3)

2

(- 10 5 5)

0

(- 10 2u)

8u

(- 10 3.14)

6.860000f32

*

Multiplying an arbitrary number of values. The form of a * expression is (* expr1 ... exprN).

(* 2 2)

4

(* 2 3 4 5)

120

(* 10 2u)

20u

(* 4 3.14)

12.560000f32

/

Division. The form of a / expression is (/ expr1 ... exprN). The resulting type is the same as the inputs (after their types have been promoted of course).

(/ 128 2)

64

(/ 6.28 2)

3.140000f32

(/ 256 2 2 2 2 2 2 2)

2

(/ 5 2)

2

mod

Modulo operation. The form of a mod expression is (mod expr1 exp2). The modulo operation is not generalised to n arguments.

(mod 5 3)

2

(mod 1024 100)

24

(mod -7 5)

-2

//

Integer division operation. Like normal division except if the result is a floating point value it is cast to an integer, which floors the result. The form of a // expression is (// expr1 ... exprN). Can be used as a elegant complement to mod, with // returning the quotient and mod returning the remainder of a division.

(// 5.000000f32 2)

2

(progn 
    (var total-seconds 62.500000f32)
    (var minutes (// total-seconds 60))
    (var seconds (mod total-seconds 60))
    (str-join (list (str-from-n minutes) "m " (str-from-n seconds) "s") [0]))

"1m 2.5s"

Comparisons

eq

Compare values for equality. The eq operation implements structural equality. The form of an 'eqexpression is(eq expr1 ... exprN)`. Structural equality means that the values must have the identical in memory representations to be considered equal.

(eq (+ 1 2) 3)

t

(eq 1 1 1 1)

t

(eq 1 1 2 1)

nil

(eq (+ 3 4) (+ 2 5) (+ 1 6))

t

(eq (list 1 2 3 4) (list 1 2 3 4))

t

(eq (list 1 2 4 5) (list 1 2 3 4))

nil

not-eq

not-eq implements the negation of eq. In other words, (not-eq a b c) evaluates to the same result as (not (eq a b c)).

(not-eq (+ 1 2) 3)

nil

(not-eq 1 1 1 1)

nil

(not-eq 1 1 2 1)

t

(not-eq (+ 3 4) (+ 2 5) (+ 1 6))

nil

(not-eq (list 1 2 3 4) (list 1 2 3 4))

nil

(not-eq (list 1 2 4 5) (list 1 2 3 4))

t

=

The = operation can only be used on numerical arguments. If you know you are comparing numbers, it will be more efficient to use =. An important difference between eq and = is that = compare the numerical values of the arguments. A 3 is a 3 independent of them being different types. eq on the other hand compares the representations of the arguments exactly and they must match in structure, type and value to be considered equal.

(= 1 1)

t

(= 1 2)

nil

(= (+ 2 3) (+ 1 4))

t

(= (+ 1 2) (+ 2 3))

nil

>

Greater than comparison. A greater than comparison has the form (> expr1 ... exprN) and evaluates to t if expr1 is greater than all of expr2 ... exprN.

(> 5 2)

t

(> 2 5)

nil

(> 3.140000f32 1)

t

(> 1 3.140000f32)

nil

<

Less than comparison. A less than comparison has the form (> expr1 ... exprN) and evaluates to t if expr1 is less than all of expr2 ... exprN.

(< 5 2)

nil

(< 5 2)

nil

(< 3.14 1)

nil

(< 1 3.14)

t

>=

Greater than or equal comparison. A greater than comparison has the form (>= expr1 ... exprN) and evaluates to t if expr1 is greater than or equal to all of expr2 ... exprN.

(>= 1 1)

t

(>= 5 2)

t

(>= 2 5)

nil

(>= 3.14 1)

t

(>= 1 3.14)

nil

<=

Less than or equal comparison. A less than or equal comparison has the form (<= expr1 ... exprN) and evaluates to t if expr1 is less than or equal to all of expr2 ... exprN.

(<= 1 1)

t

(<= 5 2)

nil

(<= 2 5)

t

(<= 3.14 1)

nil

(<= 1 3.14)

t

Boolean operators

and

Special form

Boolean and operation between n arguments. The form of an and expression is (and expr1 ... exprN). This operation treats all non-nil values as true. Boolean and is "short-circuiting" and only evaluates until a false is encountered.

(and t t)

t

(and t t (+ 1 2))

3

(and t (< 5 3))

nil

or

Special form

Boolean or operation between n arguments. The form of an or expression is (or expr1 ... exprN). This operation treats all non-nil values as true. Boolean or is "short-circuiting" and only evaluates until a true is encountered.

(or nil nil)

nil

(or nil t)

t

(or t nil)

t

(or t t)

t

(or nil (+ 1 2))

3

not

Boolean not takes one argument. The form of a not expression is (not expr). All non-nil values are considered true.

(not t)

nil

(not nil)

t

(not 42)

nil

Predicates

list?

the list? predicate is true for all lists, empty (nil) or not.

(list? nil)

t

(list? 'nil)

t

(list? (list 1 2 3))

t

(list? '(1 2 3))

t

(list? 2)

nil

(list? 'kurt-russel)

nil

number?

the number? predicate is true for all numbers.

(number? nil)

nil

(number? 1)

t

(number? 2u)

t

(number? 3.140000f32)

t

(number? 'michael-shanks)

nil

(number? 'james-spader)

nil

Bit level operations

shl

The shift left operation takes two arguments. The first argument is a value to shift and the second argument is the number of bit positions to shift the value.

(shl 1 2)

4

(shl 1u32 2)

4u32

(shl 1u64 2)

4u64

shr

The shift right operation takes two arguments. The first argument is a value to shift and the second argument in the number of bit positions to shift the value.

(shr 4 2)

1

(shr 4u32 2)

1u32

(shr 4u64 2)

1u64

bitwise-and

Performs the bitwise and operation between two values. The type of the result is the same type as the first of the arguments.

(bitwise-and 1048831u32 65535)

255u32

bitwise-or

Performs the bitwise or operation between two values. The type of the result is the same type as the first of the arguments.

(bitwise-or 1048816 15)

1048831

bitwise-xor

Performs the bitwise exclusive or operation between two values. The type of the result is the same type as the first of the arguments.

(bitwise-xor 1048816 255)

1048591

bitwise-not

Performs the bitwise negation operations on a value. The result is of same type as the argument.

(bitwise-not 4096u32)

4294963199u32

nil and t, true and false

nil

Represents the empty list. The nil value is also considered to be false by conditionals. nil is a symbol but it cannot be redefined and will always evaluate to itself.

(cons 1 nil)

(1)

(if nil 3 100)

100

nil

nil

t

All non nil values are considered true in conditionals. t should be used in cases where an explicit true makes sense. t is a symbol but it cannot be redefined and will always evaluate to itself.

(cons 1 t)

(1 . t)

(if t 3 100)

3

t

t

false

false is an alias for nil.

(cons 1 false)

(1)

(if false 3 100)

100

false

nil

true

true is an alias for t.

(cons 1 true)

(1 . t)

(if true 3 100)

3

true

t

Quotes and Quasiquotation

Code and data share the same representation, it is only a matter of how you look at it. The tools for changing view, or interpretation, are the quotation and quasiquotation operations.

quote

Special form

When the ' quote operator is encountered by the reader it is removed and the code to the right is wrapped in (quote ...). Evaluating a quoted expression (quote a) results in a unevaluated.

'(+ 1 2)

(+ 1 2)

(eval '(+ 1 2))

3

'kurt

kurt

`

The backwards tick operator ` is called the quasiquote. It is similar to ' but allows splicing in results of computations using the , and the ,@ operators.

The result of '(+ 1 2) and `(+ 1 2) are similar in effect. Both result in the result value of (+ 1 2), that is a list containing +, 1 and 2. When `(+ 1 2) is read into the heap it is expanded into the expression (append (quote (+)) (append (quote (1)) (append (quote (2)) (quote nil)))) which evaluates to the list (+ 1 2).

`(+ 1 2)

(+ 1 2)

`(+ 1 ,(+ 1 1))

(+ 1 2)

(append '(+ 1) (list (+ 1 1)))

(+ 1 2)

,

The comma is used to splice the result of a computation into a quasiquotation.

The expression `(+ 1 ,(+ 1 1)) is expanded by the reader into (append (quote (+)) (append (quote (1)) (append (list (+ 1 1)) (quote nil)))). Evaluating the expression above results in the list (+ 1 2).

`(+ 1 ,(+ 1 1))

(+ 1 2)

,@

The comma-at operation is used to splice in the result of a computation (that returns a list) into a list when quasiquoting.

`(1 2 3 ,@(range 4 10))

(1 2 3 4 5 6 7 8 9)

Built-in operations

identity

The identity function takes one argument which it directly returns. The form of an identity expression is (identity expr), where expr is an arbitrary lisp expression. (identity expr) is a function application so all normal function application rules apply. The most important property of function applications in this case is that the argument is evaluated which differentiates identity from quote which returns the argument unevaluated.

(identity 1)

1

(identity (+ 1 2))

3

(identity 'apa)

apa

(identity 'kurt-russel)

kurt-russel

(identity '(+ 1 2))

(+ 1 2)

rest-args

rest-args are related to user defined functions. As such rest-args is also given a brief explanation in the section about the lambda.

rest-args is a mechanism for handling optional arguments in functions. Say you want to define a function with 2 arguments and an optional 3rd argument. You can do this by creating a 3 argument function and check if argument 3 is valid or not in the body of the function

(defun my-fun (x y opt)
  (if opt (+ x y opt) (+ x y)))

(closure (x y opt) 
  (if opt (+ x y opt) (+ x y))
  nil)

(my-fun 1 2 nil)

3

(my-fun 1 2 100)

103

This approach works well if your function has 1,2 or some other small number of optional arguments. However, functions with many optional arguments will look messy at the application site, (my-fun 1 2 nil nil nil nil 32 nil kurt-russel) for examples

Functions you create, using lambda or defun, do actually take an arbitrary number of arguments. In other words, it is no error to pass in 5 arguments to a 2 argument defun or lambda function. The extra arguments will by default just be ignored.

(defun my-fun (x y)
  (+ x y))

(closure (x y) 
  (+ x y)
  nil)

(my-fun 1 2)

3

(my-fun 1 2 100 200 300 400 500)

3

all of those extra arguments, 100 200 300 400 500 passed into my-fun are ignored. But if we want to, we can access these extra arguments through the rest-args operation.

(defun my-fun (x y)
  (apply + (cons x (cons y (rest-args)))))

(closure (x y) 
  (apply + (cons x (cons y (rest-args))))
  nil)

(my-fun 1 2 100)

103

(my-fun 1 2 100 1000 10000)

11103

rest-args gives a clean looking interface to functions taking arbitrary optional arguments. Functions that make use of rest-args must, however, be written specifically to do so and are themself responsible for the figuring out the positional semantics of extra arguments.

One way to explicitly carry the semantics of an optional argument into the function body is to add optional arguments as key-value pairs where the key states the meaning. Then rest-args becomes essentially an association list that you query using assoc. For example:

(defun my-fun (x)
  (assoc (rest-args) x))

(closure (x) 
  (assoc (rest-args) x)
  nil)

(my-fun 'kurt-russel '(apa . 10) '(bepa . 20) '(kurt-russel . is-great))

is-great

(my-fun 'apa '(apa . 10) '(bepa . 20) '(kurt-russel . is-great))

10

(my-fun 'bepa '(apa . 10) '(bepa . 20) '(kurt-russel . is-great))

20

The rest-args operation also, itself, takes an optional numerical argument that acts as an index into the list of rest arguments.

(defun my-fun (i)
  (rest-args i))

(closure (i) 
  (rest-args i)
  nil)

(my-fun 0 1 2 3)

1

(my-fun 1 1 2 3)

2

(my-fun 2 1 2 3)

3

set

The set form is used to change the value of some variable in an environment. You can use set to change the value of a global definition or a local definition. An application of the set form looks like (set var-expr val-expr) where var-expr should evaluate to a symbol. The val-expr is evaluated before rebinding the variable. set returns the value that val-expr evaluates to.

(define a 10)
(set 'a 20)
a

20

set works in local environments too such as in the body of a let or in a progn-local variable created using var.

(progn 
    (var a 10)
    (set 'a 20)
    a)

20

See setq for a version which does't evaluate var-expr, similarly to define.

setvar

setvar is an alias of set.

undefine

A definition in the global environment can be removed using undefine. The form of an undefine expression is (undefine name-expr) where name-expr should evaluate to a symbol (for example 'apa).

(undefine 'apa)

t

It is also possible to undefine several bindings at the same time by providing a list of names.

(undefine '(apa bepa cepa))

t

eval

Evaluate data as an expression. The data must represent a valid expression. The form of an eval expression is (eval expr). An optional environment can be passed in as the first argument: (eval env-expr expr).

(eval (list + 1 2))

3

(eval '(+ 1 2))

3

(eval '((a . 100)) '(+ a 1))

101

(eval `(+ 1 ,@(range 2 5)))

10

eval-program

Evaluate a list of data where each element represents an expression. The form of an eval-program expression is (eval-program program-expr). A program-expr is a list of expressions where each element in the list can be evaluated by eval.

Note that eval-program can not take any extra environment argument.

(eval-program (list (list + 1 2) (list + 3 4)))

7

(eval-program '((+ 1 2) (+ 3 4)))

7

(eval-program (list (list define 'a 10) (list + 'a 1)))

11

(eval-program '( (define a 10) (+ a 1)))

11

apply

An apply expression has the form (apply fun-expr args-expr), and it applies args-expr to fun-expr. It can loosely be emulated by (eval (cons fun-expr args-expr)), except for the property that the elements of args-expr aren't evaluated when you use apply. args-expr itself is of course evaluated, but given the emulated form, the individual elements of the list would be evaluated again. This is a problem when your argument list may include symbols or any other values which change when evaluated.

Note that fun-expr doesn't necessarily have to be a user defined function, but can be any value which can be applied, that is, a value which can be the first item in a list expression: (fun ...). This includes (but is not limited to) user define functions (which end up as closure values), built-in functions, extensions, macros, and even special forms (but see Footgun: Special forms below).

(defun my-fun (arg1 arg2)
  (str-join (list (to-str arg1) (to-str arg2)) " "))

(closure (arg1 arg2) 
  (str-join (list (to-str arg1) (to-str arg2)) " ")
  nil)

(apply my-fun '(a b))

"a b"

(apply + (list 1 2 3 4 5))

15

(apply list '(a b c))

(a b c)

(trap (eval (cons my-fun '(symbol-a symbol-b))))

(exit-error variable_not_bound)

(call-cc (lambda (return)
           (apply return '(return-through-apply))))

return-through-apply

Footgun: Special forms
Special forms are built in functions which control how their arguments are evaluated. This means that their implementations has custom logic for how to evaluate the arguments, which has the unfortunate consequence that to apply a list of arguments to them "without evaluating" said arguments would require specific logic for each special form's implementation. Given LispBM's nature of running in an embedded environment where binary size is a luxury this becomes highly impractical. Therefore the argument list is passed on unmodified to special forms. So (apply def '(a 'symbol)) is precisely equivalent to (eval (cons def '(a 'symbol))), 'symbol will be evaluated!.

This is most noticeable with and and or. They are special forms due to their short-circuiting behavior, where later arguments may not be evaluated depending on the previous arguments. Given that you only given them the symbol t or nil their special form status isn't a problem when it comes to apply since those symbols evaluate to themselves. The problem appears when you give and or or other "unstable" values like arbitrary symbols. Since they're special forms they will evaluate them another time.

This behavior may be changed in the future, so please avoid writing programs which depend on this behavior. For the case of and and or you can define your own function which re-implement their behavior, which would be subject to apply's non-evaluating property (see example below).

(apply or '(nil t))

t

(trap (apply and '(symbol-a symbol-b)))

(exit-error variable_not_bound)

(trap (apply or '(nil symbol-b)))

(exit-error variable_not_bound)

(defun safe-and nil
  (foldl (lambda (acc x)
           (and acc x)) t (rest-args)))
(apply safe-and '(symbol-a symbol-b))

symbol-b

read

Parses a string resulting in either an expression or the read_error in case the string can not be parsed into an expression. The form of a read expression is (read string).

(read "1")

1

(read "(+ 1 2)")

(+ 1 2)

(read "(lambda (x) (+ x 1))")

(lambda (x)
  (+ x 1))

read-program

Parses a string containing multiple sequenced expressions. The resulting list of expressions can be evaluated as a program using eval-program. The form of a read-program expression is (read-program string).

(read-program "(define apa 1) (+ 2 apa)")

((define apa 1) (+ 2 apa))

read-eval-program

Parses and evaluates a program incrementally. read-eval-program reads a top-level expression then evaluates it before reading the next.

(read-eval-program "(define a 10) (+ a 10)")

20

read-eval-program supports the @const-start and @const-end annotations which move all global definitions created in the program to constant memory (flash).

(read-eval-program "@const-start (define a 10) (+ a 10) @const-end")

20

type-of

The type-of function returns a symbol that indicates what type the argument is. The form of a type-of expression is (type-of expr).

(type-of 1)

type-i

(type-of 1u)

type-u

(type-of 1i32)

type-i32

(type-of 1u32)

type-u32

(type-of 1i64)

type-i64

(type-of 1u64)

type-u64

(type-of 3.140000f32)

type-float

(type-of 3.140000f64)

type-double

(type-of 'apa)

type-symbol

(type-of (list 1 2 3))

type-list

sym2str

The sym2str function converts a symbol to its string representation. The resulting string is a copy of the original so you cannot destroy built in symbols using this function.

(sym2str 'lambda)

"lambda"

(sym2str 'lambda)

"lambda"

str2sym

The str2sym function converts a string to a symbol.

(str2sym "hello")

hello

sym2u

The sym2u function returns the numerical value used by the runtime system for a symbol.

(sym2u 'lambda)

259u

(sym2u 'lambda)

259u

u2sym

The u2sym function returns the symbol associated with the numerical value provided. This symbol may be undefined in which case you get as result a unnamed symbol.

(u2sym 259u)

lambda

(u2sym 66334u)

gc

The gc function runs the garbage collector so that it can reclaim values from the heap and LBM memory that are no longer needed.

Note that one should not need to run this function. GC is run automatically when needed.

(gc)

t

Special forms

Special forms are like functions except that they choose what arguments are evaluated. This is in contrast to "normal functions", usually referred to as "forms" in other Lisps, which always evaluate every argument they are given.

Note that some special forms are located in other sections to improve the document flow. These are:

• quote
• and
• or
• match
• recv
• recv-to
• call-cc
• call-cc-unsafe
• atomic
• macro
• move-to-flash

if

Special form

Conditionals are written as (if cond-expr then-expr else-exp). If the cond-expr evaluates to nil the else-expr will be evaluated. For any other value of cond-expr the then-expr will be evaluated.

(if t 1 2)

1

(if nil 1 2)

2

cond

Special form

cond is a generalization of if to discern between n different cases based on boolean expressions. The form of a cond expression is: (cond ( cond-expr1 expr1) (cond-expr2 expr2) ... (cond-exprN exprN)). The conditions are checked from first to last and for the first cond-exprN that evaluates to true, the corresponding exprN is evaluated.

If no cond-exprN evaluates to true, the result of the entire conditional is nil.

(define a 0)
(cond ((< a 0) 'abrakadabra)
      ((> a 0) 'llama)
      ((= a 0) 'hello-world))

hello-world

(define a 5)
(cond ((= a 1) 'doughnut)
      ((= a 7) 'apple-strudel)
      ((= a 10) 'baklava))

nil

lambda

Special form

You create an anonymous function with lambda. The function can be given a name by binding the lambda expression using define or let. A lambda expression has the form (lambda param-list body-expr).

(lambda (x)
  (+ x 1))

(closure (x) 
  (+ x 1)
  nil)

((lambda (x)
   (+ x 1)) 1)

2

You can give more arguments to a function created using lambda. The extra arguments can be accessed in the lambda body by calling the rest-args function which gives back auxiliary arguments as a list.

((lambda (x)
   (cons x (rest-args))) 1 2 3 4 5 6)

(1 2 3 4 5 6)

((lambda (x)
   (cons x (rest-args))) 1)

(1)

rest-args takes an optional numerical argument that is used to index into the list containing the rest of the arguments.

((lambda (x)
   (rest-args 0)) 1 2 3 4 5)

2

((lambda (x)
   (rest-args 1)) 1 2 3 4 5)

3

((lambda (x)
   (rest-args 2)) 1 2 3 4 5)

4

((lambda (x)
   (rest-args 3)) 1 2 3 4 5)

5

closure

Special form

A lambda expression evaluates into a closure which is very similar to a lambda but extended with a captured environment for any names unbound in the param-list appearing in the body-expr. The form of a closure is (closure param-list body-exp environment).

(lambda (x)
  (+ x 1))

(closure (x) 
  (+ x 1)
  nil)

(let ((a 1))
     (lambda (x)
       (+ a x)))

(closure (x) 
  (+ a x)
  ((a . 1)))

(let ((a 1)
      (b 2))
     (lambda (x)
       (+ a b x)))

(closure (x) 
  (+ a b x)
  ((b . 2) (a . 1)))

let

Special form

Local environments are created using let. The let binding in lispbm allows for mutually recursive bindings. The form of a let is (let list-of-bindings body-expr) and evaluating this expression means that body-expr is evaluted in an environment extended with the list-of-bindings.

(let ((a 1)
      (b 2))
     (+ a b))

3

(let ((f (lambda (x)
           (if (= x 0) 0 (g (- x 1)))))
      (g (lambda (x)
           (if (= x 0) 1 (f (- x 1))))))
     (f 11))

1

You can deconstruct composite values while let binding.

(let (((a b) (list 1 2)))
     (+ a b))

3

(let (((a . as) (list 1 2 3 4 5 6)))
     (cons a (reverse as)))

(1 6 5 4 3 2)

loop

Special form

loop allows to repeatedly evaluate an expression for as long as a condition holds. The form of a loop is (loop list-of-local-bindings condition-exp body-exp).

The list-of-local-bindings are very similar to how let works, just that here the body-exp is repeated.

(define sum 0)
(loop ((a 0))
      (<= a 10)
      (progn 
          (setq sum (+ sum a))
          (setq a (+ a 1))))
sum

55

define

Special form

You can give names to values in a global scope by using define. The form of define is (define name expr). The given expression is evaluated and the result is stored in the global environment under name. In lispbm you can redefine already defined values. It is also possible to remove bindings from the global environment, see undefine.

(define apa 10)

10

setq

Special form

The setq special-form is similar to set and to setvar but expects the first argument to be a symbol. The first argument to setq is NOT evaluated.

(define a 10)
(setq a 20)
a

20

Just like set and setvar, setq can be used on variables that are bound locally such as in the body of a let or a progn-local variable created using var.

(progn 
    (var a 10)
    (setq a 20)
    a)

20

progn

Special form

The progn special form allows you to sequence a number of expressions. The form of a progn expression is (progn expr1 ... exprN).

The evaluation result of a progn sequence is the value that the last exprN evaluated to. This is useful for sequencing of side-effecting operations.

(progn 
    1
    2
    3)

3

(progn 
    (define a 10)
    (define b 20)
    (+ a b))

30

{

Special form

The curlybrace { syntax is a short-form (syntactic sugar) for (progn. The reader replaces occurrences of { with (progn. The { should be closed with an }.

These two programs are thus equivalent:

 (progn
   (define a 10)
   (define b 20)
   (+ a b))

And

 {
   (define a 10)
   (define b 20)
   (+ a b)
 }

}

The closing curlybrace } should be used to close an opening { but purely for esthetic reasons. The } is treated identically to a regular closing parenthesis ).

The opening { and closing } curlybraces are used as a short-form for progn-blocks of sequences expressions.

var

Special form

The var special form allows local bindings in a progn expression. A var expression is of the form (var symbol expr) and the symbol symbol is bound to the value that expr evaluates to withing the rest of the progn expression.

(progn 
    (var a 10)
    (var b 20)
    (+ a b))

30

(progn 
    (var a 10)
    (var b (+ a 10))
    (+ a b))

30

You can deconstruct composite value while var binding.

(progn 
    (var (a b) (list 1 2))
    (+ a b))

3

(progn 
    (var (a . as) (list 1 2 3 4 5 6))
    (cons a (reverse as)))

(1 6 5 4 3 2)

trap

Special form

trap lets you catch an error rather than have the evaluation context terminate. The form of a trap expression is (trap expr). If expr crashes with an error e then (trap expr) evaluates to (exit-error e). If expr successfully runs and returns r, then (trap expr) evaluates to (exit-ok r).

(trap (/ 1 0))

(exit-error division_by_zero)

(trap (+ 1 2))

(exit-ok 3)

trap catches any error except for fatal errors. A fatal error will still lead to the context being terminated.

Lists and cons cells

Lists are built using cons cells. A cons cell is represented by the lbm_cons_t struct in the implementation and consists of two fields named the car and the cdr. There is no special meaning associated with the car and the cdr each can hold a lbm_value. See cons and list for two ways to create structures of cons cells on the heap.

A cons cell can be used to store a pair of values. You create a pair by sticking a value in both the car and cdr field of a cons cell using either '(1 . 2) or (cons 1 2).

A list is a number of cons cells linked together where the car fields hold values and the cdr fields hold pointers (the last cdr field is nil). The list below can be created either as '(1 2 3) or as (list 1 2 3).

car

Use car to access the car field of a cons cell. A car expression has the form (car expr).

Taking the car of a number of symbol type is in general a type_error.

(car (cons 1 2))

1

(car (list 9 8 7))

9

first

first is an alternative name for the car operation. Use first to access the first element of a list or pair. A first expression has the form (first expr).

(car (cons 1 2))

1

(car (list 9 8 7))

9

cdr

Use cdr to access the cdr field of a cons cell. A cdr expression has the form (cdr expr).

(cdr (cons 1 2))

2

(cdr (list 9 8 7))

(8 7)

rest

rest is an alternative name for the cdr operation. Use rest to access all elements except the first one of a list, or to access the second element in a pair. A rest expression has the form (rest expr).

(cdr (cons 1 2))

2

(cdr (list 9 8 7))

(8 7)

cons

The cons operation allocates a cons cell from the heap and populates the car and the cdr fields of this cell with its two arguments. The form of a cons expression is (cons expr1 expr2). To build well formed lists the innermost cons cell should have nil in the cdr field.

(cons 1 (cons 2 (cons 3 nil)))

(1 2 3)

(cons 1 2)

(1 . 2)

(cons + 1)

(+ . 1)

(cons (cons 1 2) (cons 3 4))

((1 . 2) 3 . 4)

.

The dot, ., operation creates a pair. The form of a dot expression is (expr1 . expr2). By default the evaluator will attempt to evaluate the result of (expr1 . expr2) unless it is prefixed with '.

'(1 . 2)

(1 . 2)

'((1 . 2) . 3)

((1 . 2) . 3)

list

The list function is used to create proper lists. The function takes n arguments and is of the form (list expr1 ... exprN).

(list 1 2 3 4)

(1 2 3 4)

length

Computes the length of a list. The length function takes one argument and is of the form (length expr).

(length (list 1 2 3 4))

4

range

The range function computes a list with integer values from a range specified by its endpoints. The form of a range expression is (range start-expr end-expr). The end point in the range is excluded.

(range 4 8)

(4 5 6 7)

(range 0 10)

(0 1 2 3 4 5 6 7 8 9)

(range -4 4)

(-4 -3 -2 -1 0 1 2 3)

append

The append function combines two lists into a longer list. An append expression is of the form (append expr1 expr2).

(append (list 1 2 3 4) (list 5 6 7 8))

(1 2 3 4 5 6 7 8)

ix

Index into a list using the ix function. The form of an ix expression is (ix list-expr index-expr). Indexing starts from 0 and if you index out of bounds the result is nil. A negative index accesses values starting from the end of the list.

(ix (list 1 2 3 4) 1)

2

(ix (list 1 2 3 4) -1)

4

setix

Destructively update an element in a list. The form of a setix expression is (setix list-expr index-expr value-expr). Indexing starts from 0 and if you index out of bounds the result is nil. A negative value -n will update the nth value from the end of the list.

(setix (list 1 2 3 4 5) 2 77)

(1 2 77 4 5)

(setix (list 1 2 3 4 5) -2 66)

(1 2 3 66 5)

member

Check if a value is included in list. The form of an member expression is (member value-expr list-expr). Equality is checked structurally, in the same way as eq, meaning if you're checking numbers the types must match (see the following examples).

(member 3 (list 1 2 3))

(1 2 3)

(member 3u (list 1 2 3))

nil

(member '(b c) '((a b) (b c)))

((a b) (b c))

This function can be used as a readable and efficient way of checking if a value is in some constant set of values. This often results in significantly less code than unrolling it as a series of eqs inside an or expression.

(defun is-pet? (thing)
  (member thing '(cat dog)))
(is-pet? 'cat)

(cat dog)

(is-pet? 'car)

nil

(defun is-pet-unrolled? (thing)
  (or (eq thing 'cat) (eq thing 'dog)))
(eq (is-pet? 'cat) (is-pet-unrolled? 'cat))

nil

setcar

The setcar is a destructive update of the car field of a cons-cell.

(define apa '(1 . 2))
(setcar apa 42)
apa

(42 . 2)

(define apa (list 1 2 3 4))
(setcar apa 42)
apa

(42 2 3 4)

setcdr

The setcdr is a destructive update of the cdr field of a cons-cell.

(define apa '(1 . 2))
(setcdr apa 42)
apa

(1 . 42)

(define apa (list 1 2 3 4))
(setcdr apa (list 99 100))
apa

(1 99 100)

take

take creates a list containing the n first elements of another list. The form of a take expression is (take list-exp n-exp).

(define apa (list 1 2 3 4 5 6 7 8 9 10))
(take apa 5)

(1 2 3 4 5)

drop

drop creates a list from another list by dropping the n first elements of that list. The form of a drop expression is (drop list-exp n-exp).

(define apa (list 1 2 3 4 5 6 7 8 9 10))
(drop apa 5)

(6 7 8 9 10)

reverse

reverse creates a list containing the same elements as an existing list but in reverse order. The form of a reverse expression is (reverse list-exp).

(define apa (list 1 2 3 4 5 6 7 8 9 10))
(reverse apa)

(10 9 8 7 6 5 4 3 2 1)

rotate

rotate creates a list containing the same elements as an existing list but rotated some number of step along a direction. The form of a rotate expression is (rotate list-exp dist-expr). The sign of the value dist-expr evaluates to, decides direction of rotation.

(define apa (list 1 2 3 4 5 6 7 8 9 10))

(1 2 3 4 5 6 7 8 9 10)

(rotate apa 1)

(10 1 2 3 4 5 6 7 8 9)

(rotate apa -1)

(2 3 4 5 6 7 8 9 10 1)

(rotate apa 3)

(8 9 10 1 2 3 4 5 6 7)

(rotate apa -3)

(4 5 6 7 8 9 10 1 2 3)

Rotating a list in the negative direction is slightly faster than rotating in the positive direction. The chart below shows the time 1 Million 3 step rotations take in each direction at varying list lengths. The data is collected on x86.

merge

merge merges two lists that are ordered according to a comparator into a single ordered list. The form of a merge expression is (merge comparator-exp list-exp1 list-exp2).

(define a (list 2 4 6 8 10 12))
(define b (list 1 3 5))
(merge < a b)

(1 2 3 4 5 6 8 10 12)

sort

sort orders a list of values according to a comparator. The sorting algorithm used is an in-place merge-sort. A copy of the input list is created at the beginning of the sort to provide a functional interface from the user's point of view. The form of a sort expression is (sort comparator-exp list-exp)

(define a (list 1 9 2 5 1 8 3))
(sort < a)

(1 1 2 3 5 8 9)

association lists (alists)

Association lists (alists) are, just like regular lists, built out of cons-cells. The difference is that an alist is a list of pairs where the first element in each par can be thought of as a key and the second element can be thought of as the value. So alists implement a key-value lookup structure.

(list '(1 . horse) '(2 . donkey) '(3 . shark)) is an example of an alist with integer keys and symbol values.

acons

The acons form is similar to cons, it attaches one more element onto an alist. The element that is added consists of a key and a value so acons takes one more argument than cons. The form of an acons expression is (acons key-expr val-expr alist-expr). The alist-expr should evaluate to an alist but there are no checks to ensure this.

Example that adds the key 4 and associated value lemur to an existing alist.

(acons 4 'lemur (list '(1 . horse) '(2 . donkey) '(3 . shark)))

((4 . lemur) (1 . horse) (2 . donkey) (3 . shark))

assoc

The assoc function looks up the first value in an alist matching a given a key. The form of an assoc expression is (assoc alist-expr key-expr)

(assoc (list '(1 . horse) '(2 . donkey) '(3 . shark)) 2)

donkey

cossa

The cossa function looks up the first key in an alist that matches a given value. The form of an cossa expression is (cossa alist-expr value-expr)

(cossa (list '(1 . horse) '(2 . donkey) '(3 . shark)) 'donkey)

2

setassoc

The setassoc function destructively updates a key-value mapping in an alist. The form of a setassoc expression is (setassoc alist-expr key-expr value-expr). If you assign a key which doesn't exist in the original alist, it is left unchanged, while another association pair is added to the returned list.

(define apa (list '(1 . horse) '(2 . donkey) '(3 . shark)))
(setassoc apa 2 'llama)

((1 . horse) (2 . llama) (3 . shark))

(setassoc apa 4 'mouse)

((4 . mouse) (1 . horse) (2 . llama) (3 . shark))

apa

((1 . horse) (2 . llama) (3 . shark))

Byte buffers

bufcreate

Create an array of bytes. The form of a bufcreate expression is (bufcreate size-expr).

(define data (bufcreate 10))

[0 0 0 0 0 0 0 0 0 0]

(define empty-array (bufcreate 0))

[]

Alternatively a buffer can be allocated from a compactable memory region (defrag mem).

(define dm (dm-create 1000))

DM

(define data-in-dm (bufcreate dm 10))

[0 0 0 0 0 0 0 0 0 0]

For more information about defragmentable memory see Defragmentable memory.

buflen

Returns the size of a buffer in number of bytes. The form of an buflen expression is (buflen buf-expr) where buf-expr has to evaluate into a buffer.

(buflen data)

10

bufget-[X]

Read a value from a buffer. The contents of a buffer can be read as a sized integer or unsigned value using as many bytes from the buffer as the X portion of the function name implies. The form of a bufget expression is (bufget-[X] buf-expr ix-expr) where ix-expr evaluates to a number indicating the byte position to start reading from.

(define data [255 255 255 255 255 255 255 255])

[255 255 255 255 255 255 255 255]

(bufget-i8 data 0)

-1

(bufget-i16 data 0)

-1

(bufget-i32 data 0)

-1

(bufget-u8 data 0)

255

(bufget-u16 data 0)

65535

(bufget-u32 data 0)

4294967295u32

bufset-[X]

The bufset functions performs a destructive updates to a buffer. The form of a bufset expression is (bufset-[X] buf-expr ix-expr val-expr) where ix-expr evaluates to a number indicating where in the buffer to start writing and val-expr is the value to write.

(define data [255 255 255 255 255 255 255 255])

[255 255 255 255 255 255 255 255]

(bufset-i8 data 0 10)

t

data

[10 255 255 255 255 255 255 255]

(bufset-i16 data 0 20)

t

data

[0 20 255 255 255 255 255 255]

(bufset-i32 data 0 -1)

t

data

[255 255 255 255 255 255 255 255]

(bufset-u8 data 0 10)

t

data

[10 255 255 255 255 255 255 255]

(bufset-u16 data 0 20)

t

data

[0 20 255 255 255 255 255 255]

(bufset-u32 data 0 4294967295u32)

t

data

[255 255 255 255 255 255 255 255]

bufclear

To clear a byte array the function bufclear can be used (bufclear arr optByte optStart optLen) Where arr is the byte array to clear, optByte is the optional argument of what to clear with (default 0), optStart is the optional argument of which position to start clearing (default 0) and optLen is the optional argument of how many bytes to clear after start (default the entire array). Example:

(define data [255 255 255 255 255 255 255 255])

[255 255 255 255 255 255 255 255]

(bufclear data)

t

data

[0 0 0 0 0 0 0 0]

(bufclear data 255)

t

data

[255 255 255 255 255 255 255 255]

(bufclear data 1 5)

t

data

[255 255 255 255 255 1 1 1]

(bufclear data 1 5 8)

t

data

[255 255 255 255 255 1 1 1]

(bufclear data 170 1 5)

t

data

[255 170 170 170 170 170 1 1]

Byte buffer literal syntax

Byte buffer literals can be created using the [ and ] syntax to enclose values to initialize the array with. The [ and ] syntax is complete resolved in the reader and thus cannot contain arbitrary lisp terms. the values listed between the [ and the ] must be literals!

The form of the [ and ] syntax is [ val1 ... valN ].

[1 2 3 4 5 6 7 8 9 10]