mirror of https://github.com/rusefi/bldc.git
1379 lines
32 KiB
Plaintext
1379 lines
32 KiB
Plaintext
/** \page lbmref LispBM language reference
|
|
\tableofcontents
|
|
|
|
\section sec_arith Arithmetic
|
|
|
|
<a name="+"> <h3>+</h3> </a>
|
|
|
|
Adds up an aribtrary number of values. The form of a + expression is
|
|
<code>(+ expr1 ... exprN)</code>.
|
|
|
|
\note
|
|
Example adding up two numbers. The result is 3.
|
|
\code
|
|
(+ 1 2)
|
|
\endcode
|
|
When adding up values of different types values are converted.
|
|
\code
|
|
(+ 1i28 3.14)
|
|
\endcode
|
|
The example above evaluates to float value 4.14.<br>
|
|
You can add up multiple values.
|
|
\code
|
|
(+ 1 2 3 4 5 6 7 8 9 10)
|
|
\endcode
|
|
The example above results in the value 55.
|
|
|
|
|
|
---
|
|
|
|
<a name="-"> <h3>-</h3> </a>
|
|
|
|
Subtract an arbitrary number of values from a value. The form of a - expression is
|
|
<code>(- expr1 ... exprN)</code>
|
|
|
|
\note
|
|
Example subtracting 3 from 5.
|
|
\code
|
|
(- 5 3)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="*"> <h3>*</h3> </a>
|
|
|
|
Multiplying an arbitrary number of values. The form of a * expression is
|
|
<code>(* expr1 ... exprN)</code>
|
|
|
|
\note
|
|
Example 2pi.
|
|
\code
|
|
(* 2 3.14)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="/"> <h3>/</h3> </a>
|
|
|
|
Division. The form of a / expression is <code>(/ expr1 ... exprN)</code>.
|
|
|
|
\note
|
|
Divide 128 by 2
|
|
\code
|
|
(/ 128 2)
|
|
\endcode
|
|
The following example evaluates to 1.
|
|
\code
|
|
(/ 128 2 2 2 2 2 2 2)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="mod"> <h3>mod</h3> </a>
|
|
|
|
Modulo operation. The form of a mod expression is <code>(mod expr1 ... exprN)</code>.
|
|
|
|
\note
|
|
Compute 5 % 3, evaluates to 2.
|
|
\code
|
|
(mod 5 3)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
\section sec_comp Comparisons
|
|
|
|
|
|
<a name="eq"> <h3>eq</h3> </a>
|
|
|
|
Compare expressions for equality. The eq implements structural equality.
|
|
The form of an eq expression is <code>(eq expr1 ... exprN)</code>
|
|
|
|
\note
|
|
Compare the result of <code>(+ 1 2)</code> with 3. The
|
|
result of this comparison is <code>t</code>.
|
|
\code
|
|
(eq (+ 1 2) 3)
|
|
\endcode
|
|
Multiple expressions can be checked at once. The examples below evaluates to
|
|
<code>t</code>
|
|
\code
|
|
(eq 1 1 1 1)
|
|
|
|
(eq (+ 3 4) (+ 2 5) (+ 1 6))
|
|
\endcode
|
|
The following examples evaluate to <code>nil</code> representing false.
|
|
\code
|
|
(eq 1 1 1 1 2)
|
|
|
|
(eq (+ 1 2) (+ 0 2) (+ -1 2))
|
|
\endcode
|
|
The = comparison can be used on tree shaped data. The following expression evaluates to
|
|
<code>t</code>.
|
|
\code
|
|
(eq '(1 (1 2)) '(1 (1 2)))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="#="> <h3>=</h3> </a>
|
|
|
|
The <code>=</code> operation can only be used on numerical arguments.
|
|
If you know you are comparing numbers, it will be more efficient to use
|
|
<code>=</code>.
|
|
|
|
An important difference between <code>eq</code> and <code>=</code> is
|
|
that equals compare the numerical values of the arguments. A 3 is a 3
|
|
independent of them being different types. <code>eq</code> on the other
|
|
hands compares the representations of the arguments exactly and they must
|
|
match in structure, type and value to be considered equal.
|
|
|
|
\note
|
|
Example of <code>=</code> comparison.
|
|
\code
|
|
(num-eq (+ 2 3) (+ 1 4))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name=">"> <h3>></h3> </a>
|
|
|
|
Greater than comparison. A greater than comparison has the form <code>(> expr1 ... exprN)</code>
|
|
and evaluates to <code>t</code> if expr1 is greater than all of expr2 ... exprN.
|
|
|
|
\note
|
|
Example
|
|
\code
|
|
(> 5 2)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="<"> <h3><</h3> </a>
|
|
|
|
Less than comparison. A less than comparison has the form <code>(> expr1 ... exprN)</code>
|
|
and evaluates to <code>t</code> if expr1 is less than all of expr2 ... exprN.
|
|
|
|
\note
|
|
Example
|
|
\code
|
|
(< 5 2)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
\section sec_bool Boolean operators
|
|
|
|
<a name="and"> <h3>and</h3> </a>
|
|
|
|
Boolean <code>and</code> operation between n arguments. The form
|
|
of an <code>and</code> expression is <code>(and expr1 ... exprN)</code>.
|
|
This operation treats all non-nil values as true. Boolean <code>and</code>
|
|
is "shirt-circuiting" and only evaluates until a false is encountered.
|
|
|
|
\note
|
|
The example below evaluates to <code>t</code>
|
|
\code
|
|
(and t t)
|
|
\endcode
|
|
The folowing example evaluates to 3
|
|
\code
|
|
(and t t (+ 1 2))
|
|
\endcode
|
|
And lastly an example that evaluates to nil (for false).
|
|
\code
|
|
(and t (< 5 3))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="or"> <h3>or</h3> </a>
|
|
|
|
Boolean <code>or</code> operation between n arguments. The form
|
|
of an <code>or</code> expression is <code>(or expr1 ... exprN)</code>.
|
|
This operation treats all non-nil values as true. Boolean <code>or</code>
|
|
is "short-circuiting" and only evaluates until a true is encountered.
|
|
|
|
\note
|
|
The example below evaluates to <code>t</code>.
|
|
\code
|
|
(or t nil)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="not"> <h3>not</h3> </a>
|
|
|
|
Boolean <code>not</code> takes one argument. The form of a <code>not</code>
|
|
expression is <code>(not expr)</code>. All non-nil values are considered
|
|
true.
|
|
|
|
\note
|
|
The following example evaluates to <code>t</code>
|
|
\code
|
|
(not nil)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
|
|
\section sec_bitwise Bit level operations
|
|
|
|
<a name="shl"><h3>shl</h3></a>
|
|
|
|
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.
|
|
\note
|
|
The example below evaluates to 4.
|
|
\code
|
|
(shl 1 2)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
|
|
<a name="shr"><h3>shr</h3></a>
|
|
|
|
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.
|
|
\note
|
|
The example below evaluates to 1.
|
|
\code
|
|
(shr 4 2)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
|
|
<a name="bitwise-and"><h3>bitwise-and</h3></a>
|
|
|
|
Performs the bitwise and operation between two values. The type of the result
|
|
is the same type as the first of the arguments.
|
|
|
|
|
|
---
|
|
|
|
|
|
<a name="bitwise-or"><h3>bitwise-or</h3></a>
|
|
|
|
Performs the bitwise or operation between two values. The type of the result
|
|
is the same type as the first of the arguments.
|
|
|
|
|
|
---
|
|
|
|
|
|
<a name="bitwise-xor"><h3>bitwise-xor</h3></a>
|
|
|
|
Performs the bitwise xor operation between two values. The type of the result
|
|
is the same type as the first of the arguments.
|
|
|
|
|
|
---
|
|
|
|
<a name="bitwise-not"><h3>bitwise-not</h3></a>
|
|
|
|
Performs the bitwise not operations on a value. The result is of same type as
|
|
the argument.
|
|
|
|
\section sec_low_level Low level operations
|
|
|
|
<a name="encode-i32"> <h3>encode-i32</h3> </a>
|
|
|
|
The <code>encode-i32</code> function converts a list of four (byte sized) values
|
|
into an i32 value.
|
|
\note
|
|
Example that evaluates to the i32 value 1024.
|
|
\code
|
|
(encode-i32 (list 0 0 4 0))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="encode-u32"> <h3>encode-u32</h3> </a>
|
|
|
|
The <code>encode-u32</code> function converts a list of four (byte sized) values
|
|
into an u32 value.
|
|
\note
|
|
Example that evaluates to the u32 value 1024.
|
|
\code
|
|
(encode-u32 (list 0 0 4 0))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="encode-float"> <h3>encode-float</h3> </a>
|
|
|
|
The <code>encode-float</code> function converts a list four (byte sized) values
|
|
into a float value.
|
|
\note
|
|
Example that evaluates to 3.14.
|
|
\code
|
|
(encode-float (list 64 72 245 195))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="decode"> <h3>decode</h3> </a>
|
|
|
|
The <code>decode</code> function decodes a value into a list of four (byte sized) values.
|
|
\note
|
|
Example that decodes float 3.14 into the list (64 72 245 195).
|
|
\code
|
|
(decode 3.14)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
\section sec_nil nil and t
|
|
|
|
<a name="nil"><h3>nil</h3></a>
|
|
|
|
Represents the empty list. The nil value is also considered to be false by
|
|
conditionals<br>
|
|
|
|
\note
|
|
The example below creates a one element list by allocating a cons cell and putting a value (1) in the <a href="#car"> car </a> field
|
|
and nil in the <a href="#cdr"> cdr </a> field.<br>
|
|
\code{.lisp}
|
|
(cons 1 nil)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="t"><h3>t</h3></a>
|
|
|
|
All non nil values are considered true in conditionals. t should be used in cases where an
|
|
explicit true makes sense.
|
|
|
|
---
|
|
|
|
\section sec_quote 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 how your view are the quotation and
|
|
quasiquotation operations.
|
|
|
|
---
|
|
|
|
<a name="'"><h3>'</h3></a> <a name="quote"></a>
|
|
|
|
Usages of the ' quote symbol in input code is replaced with the symbol quote
|
|
by the reader. <br>
|
|
Evaluating a quoted expression, (quote a), results in a unevaluated.<br>
|
|
\note
|
|
The program string <code>'(+ 1 2) </code> gets read into the heap as the list <code>(quote (+ 1 2))</code>.<br>
|
|
Evaluating the expression <code>(quote (+ 1 2))</code> results in the value <code>(+ 1 2)</code>.
|
|
|
|
|
|
---
|
|
|
|
<a name="`"><h3>`</h3></a>
|
|
|
|
The backwards tick <code>`</code> is called the quasiquote. It is similar to the <code>'</code> but
|
|
allows splicing in results of computations using the <a href="#,">,</a> and the <a href="#commaat">,\@</a>
|
|
operators.
|
|
|
|
\note
|
|
The result of <code>'(+ 1 2)</code> and <code>`(+ 1 2)</code> are similar in
|
|
effect. Both result in the result value of <code>(+ 1 2)</code>, that is a list containing
|
|
+, 1 and 2. <br>
|
|
When <code>`(+ 1 2)</code> is read into the heap it is expanded into the
|
|
expression <code>(append (quote (+)) (append (quote (1)) (append (quote (2)) (quote nil))))</code>
|
|
which evaluates to the list <code>(+ 1 2)</code>.
|
|
|
|
|
|
---
|
|
|
|
<a name=","><h3>,</h3></a>
|
|
|
|
The comma is used to splice the result of a computation into a quasiquotation.
|
|
\note
|
|
The expression <code>`(+ 1 ,(+ 1 1))</code> is expanded by the reader into
|
|
<code>(append (quote (+)) (append (quote (1)) (append (list (+ 1 1)) (quote nil))))</code>.
|
|
Evaluating the expression above results in the list <code>(+ 1 2)</code>.
|
|
|
|
|
|
---
|
|
|
|
<a name="commaat"><h3>,\@</h3></a>
|
|
|
|
The comma-at operation is used to splice in the result of a computation (that
|
|
returns a list) into a list.
|
|
\note
|
|
Example:
|
|
\code
|
|
(define mylist (list 1 2 3 4 5)
|
|
`(9 6 5 ,@mylist)
|
|
\endcode
|
|
Evaluates to the list <code>(9 6 5 1 2 3 4 5)</code>.
|
|
|
|
|
|
\section sec_builtin Built-in operations
|
|
|
|
|
|
<a name="eval"> <h3>eval</h3> </a>
|
|
|
|
Evaluate data as an expression. The data must represent a valid expression.
|
|
\note
|
|
Example that evaluates to 3.
|
|
\code
|
|
(eval (list + 1 2))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="eval-program"> <h3>eval-program</h3> </a>
|
|
|
|
Evaluate a list of data where each element represents an expression.
|
|
\note
|
|
This function is quite awkward as it replaces the program in the running
|
|
context with the program provided in the list. Avoid using this
|
|
function if possible.
|
|
|
|
|
|
---
|
|
|
|
<a name="type-of"> <h3>type-of</h3> </a>
|
|
|
|
The <code>type-of</code> function returns a symbol that indicates what type the
|
|
argument is. The form of a <code>type-of</code> expression is <code>(type-of expr)</code>.
|
|
|
|
\note
|
|
Example that evaluates to <code>type-float</code>.
|
|
\code
|
|
(type-of 3.14)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="sym-to-str"> <h3>sym-to-str</h3> </a>
|
|
|
|
The <code>sym-to-str</code> 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.
|
|
|
|
\note
|
|
Example that returns the string <code>"lambda"</code>.
|
|
\code
|
|
(sym-to-str 'lambda)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="str-to-sym"> <h3>str-to-sym</h3> </a>
|
|
|
|
The <code>str-to-sym</code> function converts a string to a symbol.
|
|
\note
|
|
Example that returns the symbol <code>hello</code>.
|
|
\code
|
|
(str-to-sym "hello")
|
|
\endcode
|
|
|
|
---
|
|
|
|
<a name="sym-to-u"> <h3>sym-to-u</h3> </a>
|
|
|
|
The <code>sym-to-u</code> function returns the numerical value used by the runtime system
|
|
for a symbol.
|
|
|
|
\note
|
|
Example that evaluates to 4.
|
|
\code
|
|
(sym-to-u 'lambda)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="u-to-sym"> <h3>u-to-sym</h3> </a>
|
|
|
|
The <code>u-to-sym</code> 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.
|
|
|
|
---
|
|
|
|
<a name="is-fundamental"> <h3>is-fundamental</h3> </a>
|
|
|
|
The <code>is-funamental</code> function returns true for built-in functions.
|
|
\note
|
|
Example that returns true.
|
|
\code
|
|
(is-fundamental '+)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
|
|
\section sec_forms Special forms
|
|
|
|
|
|
<a name="if"> <h3>if</h3> </a>
|
|
|
|
Conditionals are written as <code>(if cond-expr then-expr else-expr)</code>.
|
|
If the cond-expr evaluates to <a href="#nil"> nil </a> the else-expr will be evaluated.
|
|
for any other value of cond-expr the then-expr will be evalated.
|
|
|
|
\note
|
|
The example below evaluates to 0 if a is less than or equal to 4. Otherwise it evaluates to a + 10.
|
|
\code
|
|
(if (> a 4) (+ a 10) 0)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="lambda"> <h3>lambda</h3> </a>
|
|
|
|
You create an anonymous function with lambda. The function can be given a name by binding the lambda expression using <a href="#define">define</a>
|
|
or <a href="#let">let</a>. A lambda expression has the form <code>(lambda param-list body-expr)</code>.
|
|
\note
|
|
The example shows an anonymous function that adds one.
|
|
\code
|
|
(lambda (x) (+ x 1))
|
|
\endcode
|
|
A lambda can be immediately applied to an argument.
|
|
\code
|
|
((lambda (x) (+ x 1)) 10)
|
|
\endcode
|
|
The application above results in the value 11. <br>
|
|
Using <a href="#define"> define </a> you can give a name to the function.
|
|
\code
|
|
(define inc (lambda (x) (+ x 1)))
|
|
\endcode
|
|
Now the expression <code>(inc 10)</code> computes the result 11.
|
|
|
|
|
|
---
|
|
|
|
<a name="closure"> <h3>closure</h3> </a>
|
|
|
|
A <a href="#lambda"> lambda </a> expression evaluates into a closure which is very similar to a <a href="#lambda">lambda</a>
|
|
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 <code>(closure param-list body-exp environment)</code>.
|
|
|
|
\note
|
|
Evaluation of the expression
|
|
\code
|
|
(lambda (x) (+ x 1))
|
|
\endcode
|
|
results in the value
|
|
\code
|
|
(closure (x) (+ x 1) nil)
|
|
\endcode<br>
|
|
Below is an example of how a value is captured into the closure.
|
|
\code
|
|
(let ((a 1)) (lambda (x) (+ x a)))
|
|
\endcode
|
|
The expression above evaluates to the following. Note that <code>(a . 1)</code> appears in
|
|
the closure.
|
|
\code
|
|
(closure (x) (+ x a) ((a . 1)))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="let"> <h3>let</h3> </a>
|
|
|
|
Local environments are created using let. The let binding in
|
|
lispbm allows for mutually recursive bindings. The form of a let is
|
|
<code>(let list-of-bindings body-expr)</code> and evaluating this expression
|
|
means that body-expr is evaluted in an environment extended with the list-of-bindings.
|
|
|
|
\note
|
|
Example that evaluates to 3.
|
|
\code
|
|
(let ((a 1)
|
|
(b 2))
|
|
(+ a b))
|
|
\endcode
|
|
Below is a more advanced example of two mutually recursive functions created
|
|
in a let binding.
|
|
\code
|
|
(let ((f (lambda (x) (if (= x 0) 0 (g (- x 1)))))
|
|
(g (lambda (x) (if (= x 0) 1 (f (- x 1))))))
|
|
(f 11))
|
|
\endcode
|
|
The mutually recursive program above evaluates to 1.
|
|
|
|
|
|
---
|
|
|
|
<a name="define"> <h3>define</h3> </a>
|
|
|
|
You can give names to values in a global scope by using define.
|
|
The form of define is <code>(define name expr)</code>. The expr is evaluated and it is the
|
|
result of the evaluated expr that is stored in the environment.
|
|
In lispbm you can redefine already defined values.
|
|
|
|
\note
|
|
Example
|
|
\code
|
|
(define apa 10)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="progn"> <h3>progn</h3> </a>
|
|
|
|
The progn special form allows you to sequence a number of expressions.
|
|
The form of a progn expression is:
|
|
\code
|
|
(progn expr1
|
|
expr2
|
|
...
|
|
exprN)
|
|
\endcode
|
|
The evaluation result of a progn sequence is the value that the last <code>exprN</code>
|
|
evaluated to. This is useful for sequencing of side-effecting operations.
|
|
|
|
\note
|
|
Simple example that evaluates to 3.
|
|
\code
|
|
(progn 1
|
|
2
|
|
3)
|
|
\endcode
|
|
An example where side effects are sequenced.
|
|
\code
|
|
(progn (define a 10)
|
|
(define b 20)
|
|
(+ a b))
|
|
\endcode
|
|
This program evaluates 30 but also extends the global environment with the
|
|
2 bindings <code>(a 10)</code> and <code>(b 20)</code> created using <a href="#define">define</a>.
|
|
|
|
|
|
---
|
|
|
|
<a name="read"> <h3>read</h3> </a>
|
|
|
|
Parses a string resulting in either an expression or the <a href="#read_error">read_error</a> in case
|
|
the string can not be parsed into an expression. The form of a read expression is
|
|
<code>(read string)</code>.
|
|
|
|
\note
|
|
The example below evaluates to the value 1.
|
|
\code
|
|
(read "1")
|
|
\endcode
|
|
You can also read code.
|
|
\code
|
|
(read "(lambda (x) (+ x 1))")
|
|
\endcode
|
|
That lambda you just read in from a string can be directly applied to an
|
|
argument.
|
|
\code
|
|
((read "(lambda (x) (+ x 1))") 10)
|
|
\endcode
|
|
The code above evaluates to 11.
|
|
|
|
|
|
---
|
|
|
|
<a name="read-program"> <h3>read-program</h3> </a>
|
|
|
|
Parses a string containing multiple sequenced expressed. The resulting list of
|
|
expressions can be evaluated as a program using <a href="#eval-program">eval-program</a>.
|
|
The form of a read-program expression is <code>(read-program string)</code>.
|
|
|
|
\note
|
|
Evaluate a program you just read from a string with <a href="#eval-program">eval-program</a>.
|
|
\code
|
|
(eval-program (read-program "(define apa 1) (+ 2 apa)"))
|
|
\endcode
|
|
The expression above evaluates to 3 with the side effect that the global environment
|
|
has been extended with the binding <code>(apa 1)</code>.
|
|
|
|
|
|
---
|
|
|
|
\section sec_lists Lists and cons cells
|
|
|
|
Lists are build using cons cells. A cons cell is represented by the \ref lbm_cons_t struct in the
|
|
implementation and consists of two fields named the <code>car</code> and the <code>cdr</code>.
|
|
There is no special meaning associated with the <code>car</code> and the <code>cdr</code> each can hold
|
|
a \ref lbm_value. See <a href="#cons">cons</a> and <a href="#list">list</a> for two ways to create structures of
|
|
cons cells on the heap.
|
|
|
|
<a name="car"> <h3>car</h3> </a>
|
|
|
|
Use <code>car</code> to access the <code>car</code> field of a cons cell. A
|
|
<code>car</code> expression has the form <code>(car expr)</code>.
|
|
|
|
\note
|
|
Taking the <code>car</code> of a number of symbol type is in general a <a href="#type_error">type_error</a>.
|
|
The following program results in <code>type_error</code>.
|
|
\code
|
|
(car 1)
|
|
\endcode
|
|
The next example evaluates to 1.
|
|
\code
|
|
(car (cons 1 2))
|
|
\endcode
|
|
The <code>car</code> operation accesses the head element of a list. The following program evaluates to 9.
|
|
\code
|
|
(car (list 9 8 7))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="cdr"> <h3>cdr</h3> </a>
|
|
|
|
Use <code>cdr</code> to access the <code>cdr</code> field of a cons cell. A
|
|
<code>cdr</code> expression has the form <code>(cdr expr)</code>.
|
|
|
|
\note
|
|
The example below evaluates to 2.
|
|
\code
|
|
(cdr (cons 1 2))
|
|
\endcode
|
|
The <code>cdr</code> operation gives you the rest of a list. The example below evaluates to the list (8 7).
|
|
\code
|
|
(cdr (list 9 8 7))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="cons"> <h3>cons</h3> </a>
|
|
|
|
The <code>cons</code> operation allocates a cons cell from the heap and populates the
|
|
<code>car</code> and the <code>cdr</code> fields of this cell with its two arguments.
|
|
The form of a <code>cons</code> expression is <code>(cons expr1 expr2)</code>.
|
|
|
|
\note
|
|
Build the list <code>(1 2 3)</code> using cons. <a href="#nil">nil</a> terminates a proper list.
|
|
\code
|
|
(cons 1 (cons 2 (cons 3 nil)))
|
|
\endcode
|
|
Construct the pair <code>(+ . 1)</code> using cons.
|
|
\code
|
|
(cons + 1)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="."> <h3>.</h3> </a>
|
|
|
|
The dot, <code>.</code>, operation creates a pair. The form of a dot expression
|
|
is <code>(expr1 . expr2)</code>. By default the evaluator will attempt to evaluate the
|
|
result of <code>(expr1 . expr2)</code> unless it is prefixed with <code>'</code>.
|
|
|
|
\note
|
|
Example that creates the pair (1 . 2)
|
|
\code
|
|
'(1 . 2)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="list"> <h3>list</h3> </a>
|
|
|
|
The <code>list</code> function is used to create proper lists. The function
|
|
takes n arguments and is of the form <code>(list expr1 ... exprN)</code>.
|
|
|
|
\note
|
|
Example that creates the list (1 2 3 4).
|
|
\code
|
|
(list 1 2 3 4)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="append"> <h3>append</h3> </a>
|
|
|
|
The <code>append</code> function combines two lists into a longer list.
|
|
An <code>append</code> expression is of the form <code>(append expr1 expr2)</code>.
|
|
|
|
\note
|
|
Example that combines to lists.
|
|
\code
|
|
(append (list 1 2 3) (list 4 5 6))
|
|
\endcode
|
|
|
|
|
|
|
|
---
|
|
|
|
<a name="ix"> <h3>ix</h3> </a>
|
|
|
|
Index into a list using the <code>ix</code>. the form of an <code>ix</code> expression
|
|
is <code>(ix list-expr index-expr)</code>. Indexing starts from 0 and if you index out of bounds the result is nil.
|
|
|
|
\note
|
|
Example that evaluates to 2.
|
|
\code
|
|
(ix (list 1 2 3) 1)
|
|
\endcode
|
|
|
|
|
|
|
|
---
|
|
|
|
<a name="set-car"> <h3>set-car</h3> </a>
|
|
|
|
The <code>set-car</code> is a destructive update of the car field
|
|
of a cons-cell.
|
|
|
|
\note
|
|
Define <code>apa</code> to be the pair <code>(1 . 2)</code>
|
|
\code
|
|
(define apa '(1 . 2))
|
|
\endcode
|
|
Now change the value in the car field of apa to 42.
|
|
\code
|
|
(set-car apa 42)
|
|
\endcode
|
|
The <code>apa</code> pair is now <code>(42 . 2)</code>.
|
|
|
|
---
|
|
|
|
<a name="set-cdr"> <h3>set-cdr</h3> </a>
|
|
|
|
The <code>set-cdr</code> is a destructive update of the cdr field of a cons-cell.
|
|
|
|
\note
|
|
Define <code>apa</code> to be the pair <code>(1 . 2)</code>
|
|
\code
|
|
(define apa '(1 . 2))
|
|
\endcode
|
|
Now change the value in the cdr field of apa to 42.
|
|
\code
|
|
(set-cdr apa 42)
|
|
\endcode
|
|
The <code>apa</code> pair is now <code>(1 . 42)</code>.
|
|
|
|
|
|
\section sec_arrays Arrays
|
|
|
|
|
|
<a name="array-read"> <h3>array-read</h3> </a>
|
|
|
|
Read one or many elements from an array. The form of
|
|
an <code>array-read</code> expression is either <code>(array-read array-expr index-expr)</code>
|
|
of <code>(array-read array-expr start-index-expr end-index-expr)</code> for reading a range
|
|
of values into a list.
|
|
|
|
\note
|
|
Example that evaluates to the character l.
|
|
\code
|
|
(array-read "hello" 3)
|
|
\endcode
|
|
The next example reads a range values
|
|
\code
|
|
(array-read "hello" 1 3)
|
|
\endcode
|
|
and results in the list <code>(\#e \#l \#l)</code>.
|
|
|
|
|
|
---
|
|
|
|
<a name="array-write"> <h3>array-write</h3> </a>
|
|
|
|
The <code>array-write</code> function performs a destructive update
|
|
of an array.
|
|
|
|
\note
|
|
Example that turns array "hello" into "heflo"
|
|
\code
|
|
(array-write "hello" 2 \#f)
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
\section sec_pattern Pattern-matching
|
|
|
|
<a name="match"> <h3>match</h3> </a>
|
|
|
|
Pattern-matching is expressed using match. The form of a match expression is
|
|
<code>(match expr (pat1 expr1) ... (patN exprN))</code>. Pattern-matching compares
|
|
the shape of an expression to each of the <code>pat1</code> ... <code>patN</code>
|
|
and evaluates the expression <code>exprM</code> of the pattern that matches.
|
|
In a pattern you can use a number of match-binders or wildcards: <a href="#_">_</a>,
|
|
<a href="#?">?</a>, <a href="#?i28">?i28</a>, <a href="#?u28">?u28</a>, <a href="#?float">?float</a>,
|
|
<a href="#?cons">?cons</a>.
|
|
|
|
\note
|
|
For example the match expression below evaluates to 2.
|
|
\code
|
|
(match 'orange
|
|
(green 1)
|
|
(orange 2)
|
|
(blue 3))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="_"> <h3>_</h3> </a>
|
|
|
|
The underscore pattern matches anything.
|
|
|
|
\note
|
|
An example that evaluates to <code>i-dont-know</code>
|
|
\code
|
|
(match 'fish
|
|
(horse 'its-a-horse)
|
|
(pig 'its-a-pig)
|
|
(_ 'i-dont-know))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="?"> <h3>?</h3> </a>
|
|
|
|
The ? pattern matches anything and binds that anything to variable.
|
|
Using the ? pattern is done as <code>(? var)</code> and the part of the expression
|
|
that matches is bound to <code>var</code>.
|
|
|
|
\note
|
|
An example that evaluates to 19.
|
|
\code
|
|
(match '(orange 17)
|
|
((green (? n)) (+ n 1))
|
|
((orange (? n)) (+ n 2))
|
|
((blue (? n)) (+ n 3)))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="?i28"> <h3>?i28</h3> </a>
|
|
|
|
The ?i28 pattern matches any i28 and binds that value to a variable.
|
|
Using the ?i28 pattern is done as <code>(?i28 var)</code> and the part of the expression
|
|
that matches is bound to the <code>var</code>.
|
|
|
|
\note
|
|
The following example evaluates to <code>not-an-i28</code>.
|
|
\code
|
|
(match 3.14
|
|
( (i28 n) (+ n 1))
|
|
( _ 'not-an-i28))
|
|
\endcode
|
|
The example below evaluates to 5.
|
|
\code
|
|
(match 4
|
|
( (i28 n) (+ n 1))
|
|
( _ 'not-an-i28))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
<a name="?u28"> <h3>?u28</h3> </a>
|
|
|
|
The ?u28 pattern matches any u28 and binds that value to a variable.
|
|
Using the ?u28 pattern is done as <code>(?u28 var)</code> and the part of the expression
|
|
that matches is bound to the <code>var</code>.
|
|
|
|
|
|
---
|
|
|
|
<a name="?float"> <h3>?float</h3> </a>
|
|
|
|
The ?float pattern matches any float and binds that value to a variable.
|
|
Using the ?float pattern is done as <code>(?float var)</code> and the part of the expression
|
|
that matches is bound to the <code>var</code>.
|
|
|
|
|
|
---
|
|
|
|
\section sec_concurrency Concurrency
|
|
|
|
<a name="spawn"> <h3>spawn</h3> </a>
|
|
|
|
Use <code>spawn</code> to spawn a concurrent task. The concurrency implemented
|
|
by LispBM is called cooperative concurrency and it means that processes must
|
|
sleep using <a href="#yield">yield</a> or they will starve out other processes.
|
|
The form of a spawn expression is <code>(spawn closure arg1 ... argN)</code>
|
|
The return value is a process ID.
|
|
|
|
|
|
---
|
|
|
|
<a name="wait"> <h3>wait</h3> </a>
|
|
|
|
Use <code>wait</code> to wait for a spawned process to finish.
|
|
The argument to <code>wait</code> should be a process id.
|
|
The <code>wait</code> blocks until the process with the given process id finishes.
|
|
|
|
\note
|
|
Be careful to only wait for processes that actually exist and do finish. Otherwise
|
|
you will wait forever.
|
|
|
|
|
|
---
|
|
|
|
<a name="yield"> <h3>yield</h3> </a>
|
|
|
|
To put a process to sleep, call <code>yield</code>. The argument to <code>yield</code>
|
|
is number indicating at least how many microseconds the process should sleep.
|
|
|
|
---
|
|
|
|
\section sec_messages Message-passing
|
|
|
|
<a name="send"> <h3>send</h3> </a>
|
|
|
|
Messages can be sent to a process by using <code>send</code>. The form
|
|
of a <code>send</code> expression is <code>(send pid msg)</code>. The message, msg,
|
|
can be any LispBM value.
|
|
|
|
|
|
---
|
|
|
|
<a name="recv"> <h3>recv</h3> </a>
|
|
|
|
To receive a message use the <code>recv</code> command. A process
|
|
will block on a <code>recv</code> until there is a matching message in
|
|
the mailbox. <br>
|
|
The <code>recv</code> syntax is very similar to <a href="#match">match</a>.
|
|
|
|
\note
|
|
Example where a process waits for an i28
|
|
\code
|
|
(recv ( (?i28 n) (+ n 1) ))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
\section sec_macros Macros
|
|
|
|
lispBM macros are created using the <code>macro</code> keyword. A macro
|
|
is quite similar to <a href="lambda">lambda</a> in lispBM except that
|
|
arguments are passed in unevaluated. Together with the code-splicing
|
|
capabilities given by <a href="sec_quote">quasiquotation</a>, this
|
|
provides a powerful code-generation tool.
|
|
|
|
A macro application is run through the interpreter two times. Once to
|
|
evaluate the body of the macro on the unevaluated arguments. The result of
|
|
this first application should be a program. The resulting program then goes
|
|
through the interpreter again to compute final values.
|
|
|
|
Given this repeated evaluation, macros are not a performance boost in
|
|
lispbm. Macros are really a feature that should be used to invent new
|
|
programming abstractions in cases where it is ok to pay a little for
|
|
the overhead for benefits in expressivity.
|
|
|
|
<a name="macro"> <h3>macro</h3> </a>
|
|
|
|
The form of a <code>macro</code> expression is: <code>(macro args body)</code>
|
|
|
|
\note
|
|
Some lisps provide a <code>defun</code> operation for defining functions
|
|
with a bit less typing. The example below defines a <code>defun</code> macro.
|
|
\code
|
|
(define defun (macro (name args body)
|
|
`(define ,name (lambda ,args ,body))))
|
|
\endcode
|
|
With this macro the function <code>inc</code> that adds 1 to its argument
|
|
can be defined as:
|
|
\code
|
|
(defun inc (x) (+ x 1))
|
|
\endcode
|
|
|
|
|
|
---
|
|
|
|
\section sec_cc Call With Current Continuation
|
|
|
|
"Call with current continuation" is called <code>call-cc</code> in LBM.
|
|
Call with current continuation saves the "current continuation", which encodes what
|
|
the evaluator will do next, into an object in the language. This encoded
|
|
continuation object behaves as a function taking one argument.
|
|
|
|
|
|
The <code>call-cc</code> should be given a function, <code>f</code>, as the single argument. This
|
|
function, <code>f</code>, should also take a single argument, the continuation.
|
|
At any point in the body of <code>f</code> the continuation can be applied to
|
|
a value, in essense replacing the entire <code>call-cc</code> with that value. All side-effecting operations
|
|
operations up until the application of the continuation will take effect.
|
|
|
|
From within a <code>call-cc</code> application it is possible to bind the continuation to a global variable
|
|
which will allow some pretty arbitrary control flow.
|
|
|
|
|
|
\note
|
|
The example below creates a macro for a <code>progn</code> facility that
|
|
allows returning at an arbitrary point.
|
|
\code
|
|
(define do (macro (body)
|
|
`(call-cc (lambda (return) (progn ,@body)))))
|
|
\endcode
|
|
The example using <code>do</code> below makes use of <code>print</code> which is not a
|
|
built-in feature of lispBM. There are just to many different ways a programmer may
|
|
want to implement <code>print</code> on an microcontroller. Use the lispBM extensions
|
|
framework to implement your own version of <code>print</code>
|
|
\code
|
|
(do ((print 10)
|
|
(return 't)
|
|
(print 20)))
|
|
\endcode
|
|
In the example above only "10" will be printed.
|
|
Below is an example that conditionally returns.
|
|
\code
|
|
(define f (lambda (x)
|
|
(do ((print "hello world" \#newline)
|
|
(if (= x 1)
|
|
(return 't)
|
|
nil)
|
|
(print "Gizmo!" \#newline)))))
|
|
\endcode
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\section sec_unparse Unparsable symbols
|
|
|
|
Unparsable symbols cannot be written into a program. The unparsable symbols
|
|
signals different kinds of error conditions that may point at something
|
|
being wrong in the code (or that it is exhausting all resources).
|
|
|
|
<a name="no_match"> <h3>no_match</h3> </a>
|
|
|
|
The <code>no_match</code> symbol is returned from pattern matching if
|
|
no case matches the expression.
|
|
|
|
|
|
---
|
|
|
|
<a name="read_error"> <h3>read_error</h3> </a>
|
|
|
|
The <code>read_error</code> symbol is returned if the reader cannot
|
|
parse the input code.
|
|
|
|
|
|
---
|
|
|
|
<a name="type_error"> <h3>type_error</h3> </a>
|
|
|
|
The <code>type_error</code> symbol is returned byt built-in functions
|
|
if the values passed in are of incompatible types.
|
|
|
|
---
|
|
|
|
<a name="eval_error"> <h3>eval_error</h3> </a>
|
|
|
|
The <code>eval_error</code> symbol is returned if evaluation could
|
|
not proceed to evaluate the expression. This could be because the
|
|
expression is malformed.
|
|
|
|
---
|
|
|
|
<a name="out_of_memory"> <h3>out_of_memory</h3> </a>
|
|
|
|
The <code>out_of_memory</code> symbol is returned if the heap is full and running
|
|
the garbage collector was not able to free any memory up. The program
|
|
uses more memory than the size of the heap. Make the heap larger.
|
|
|
|
---
|
|
|
|
<a name="fatal_error"> <h3>fatal_error</h3> </a>
|
|
|
|
The <code>fatal_error</code> symbol is returned in cases where the
|
|
LispBM runtime system cannot proceed. Something is corrupt and it is
|
|
not safe to continue.
|
|
|
|
---
|
|
|
|
<a name="out_of_stack"> <h3>out_of_stack</h3> </a>
|
|
|
|
The <code>out_of_stack</code> symbol is returned if the evaluator
|
|
runs out of continuation stack (this is its runtime-stack). You are
|
|
most likely writing a non-tail-recursive function that is exhausting all
|
|
the resources.
|
|
|
|
--
|
|
|
|
<a name="division_by_zero"> <h3>division_by_zero</h3> </a>
|
|
|
|
The <code>division_by_zero</code> symbol is returned when dividing by zero.
|
|
|
|
---
|
|
|
|
<a name="variable_not_bound"> <h3>variable_not_bound</h3> </a>
|
|
|
|
The <code>variable_not_bound</code> symbol is returned when evaluating a
|
|
variable (symbol) that is neighter bound nor special (built-in function).
|
|
|
|
|
|
|
|
\section sec_types Types
|
|
|
|
<a name="type-list"> <h3>type-list</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-i28"> <h3>type-i28</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-u28"> <h3>type-u28</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-float"> <h3>type-float</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-i32"> <h3>type-i32</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-u32"> <h3>type-u32</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-array"> <h3>type-array</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-symbol"> <h3>type-symbol</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-char"> <h3>type-char</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-ref"> <h3>type-ref</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="type-stream"> <h3>type-stream</h3> </a>
|
|
|
|
---
|
|
|
|
|
|
|
|
*/
|
|
|
|
|
|
\section sec_internal Internal symbols
|
|
|
|
<a name="sym_openpar"> <h3>sym_openpar</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_closepar"> <h3>sym_closepar</h3> </a>
|
|
|
|
---
|
|
<a name="sym_backquote"> <h3>sym_backquote</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_comma"> <h3>sym_comma</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_commaat"> <h3>sym_commaat</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_dot"> <h3>sym_dot</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_tok_done"> <h3>sym_tok_done</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_array"> <h3>sym_array</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_boxed_i"> <h3>sym_boxed_i</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_boxed_u"> <h3>sym_boxed_u</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_boxed_f"> <h3>sym_boxed_f</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_ref"> <h3>sym_ref</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_recovered"> <h3>sym_recovered</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="sym_nonsense"> <h3>sym_nonsense</h3> </a>
|
|
|
|
---
|
|
|
|
|
|
|
|
<a name="array-create"> <h3>array-create</h3> </a>
|
|
|
|
---
|
|
|
|
|
|
\section sec_streams Streams
|
|
|
|
<a name="stream-get"> <h3>stream-get</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="stream-more"> <h3>stream-more</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="stream-peek"> <h3>stream-peek</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="stream-drop"> <h3>stream-drop</h3> </a>
|
|
|
|
---
|
|
|
|
<a name="stream-put"> <h3>stream-put</h3> </a>
|
|
|
|
---
|