language.md

Forms

• 1, -1 - integer number value
• 1.0, -1.0, 1., .0 - fractional number value
• "something" - string literal value
• something - symbol value
• #n, #nil, #null - nil value
• #t, #true true value
• #f, #false - false value
• (a . b) - pair of a and b
• (a b) - list of a, b and nil
• (a b . c) - list of a, b and c
• '(a b . c) - evaluates to whatever comes after '

Functions

Functions can be:

• builtin - built into language functions, all arguments evaluated
• special form - built into language construction that do not evaluate arguments at call, but follow inner conditions

evaluation

• (fn a b) calls function fn with params eval a and eval b

Special forms

quote

Returns first argument unevaluated. (quote <form>) => <form>

begin

Evaluates forms in order and returns last result. (begin ...<form>) => eval last <form>

lambda

Creates a closure that captures current environment. Forms evaluated in order and last result is returned. (lambda <name>? <arguments-names-list> ...<form>) = eval last <form> Name is for debug purposes only

define

Binds value to a name in the current environment. (define <name> <form>) >= #nil

Can contain shorthand version of lambda definition: (define (<name> <arguments-names-list>) ...<form>) >= #nil

set

Mutate an existing binding or creates new one in current environment. (set <name> <form>) >= #nil

is-set?

Checks if environment has binding. (is-set? <name>) >= #t|#f

get

Get an existing binding or return nil. (get <name>) >= #nil

let

Create new variable bindings in parallel on new environment and execute a series of forms in that environment. (let (...(<name> <form>)) ...<fors>) >= #nil

and

Evaluates left to right, returns first falsy or last value. Short-circuits. (and ...<form>) => first falsy | last value

or

Evaluates left to right, returns first truthy or last value. Short-circuits. (or ...<form>) => first truthy | last value

if

(if <condition> <then> <else>) => eval(<then>) | eval(<else>) | #nil

cond

(cond ...(<condition> ...<form>) (else ...<form>)) => first matching result | #nil

throw

Create value of type throw that is should trigger early return of said value after any evaluation. It carries first argument (as reason) and evaluation stack reference. (throw <form>)

try/catch/finally

Special form for intercepting throw values and ensuring cleanup logic is executed. (try <body> ...[(catch (<symbol>)? ...<forms>)|(finally ...<forms>)])

return

Special form to trigger an immediate exit from the current function, carrying a value. (return <form>)

forms in environment

Execute a series of forms in specified environment. ($<environment> ...<forms>)

object

Creates object with of named fields. (object ...:<symbol>,<form>)

Builtins List

cons

Takes exactly 2 arguments and returns a pair (left . right). (cons <left> <right>) => (<left> . <right>)

list

Evaluates each argument and constructs a new list containing the results. (list ...<form>) => (...<eval<form>>)

car / cdr

Returns the left / right element of a pair. (car <pair>) => <left> (cdr <pair>) => <right>

apply

Calls a function with supplied arguments, all arguments are concatinated into one list. (apply <fn> ...<arguments>) => result

map

Applies a function to each element of a list and returns a new list of results. (map <fn> <list>) => <list>

Builtins Arithmetics

+, -, *, /

Sequentially applies all arguments. Integers promoted to fractional if any argument is fractional. (+) => 0 (+ ...<number>) => sum (- <number> ...<number>) => difference (*) => 1 (* ...<number>) => product (/ <number> ...<number>) => quotient

Builtins Boolean

=

Applies structural check between each consequence pairs. (= <value> ...<value>) => true if all equal

<value> can be any of this:

• bool
• number
• string
• pair - compares both sides recursively
• fn - compared by reference
• symbol - compared by reference

Examples: (= #t #t) => true (= 1 1) => true (= 1 1.0) => true (= "a" "a") => true (= '(1 2) '(1 2)) => true (= ''1 ''1) => true (= if if) => true (= (lambda (a) a) (lambda (a) a)) => false (= 'a 'a) => true (define a 1) (define b 1) (= a b) => false

Comparison <, >, <=, >=

Applies operators between each consequence pairs. (< <value> ...<value>) => true if strictly increasing (> <value> ...<value>) => true if strictly decreasing (<= <value> ...<value>) => true if non-decreasing (>= <value> ...<value>) => true if non-increasing

<value> can be any of this:

• number
• string
• pair - compares both sides recursively

eq?

Applies identity check between each consequence pairs. (eq? <form> ...<form>) => true if all equal

Examples: (eq? #t #t) => true (eq? #t #f) => false (eq? 1 1) => true (eq? 1 1.0) => false (eq? "a" "a") => false (eq? '(1 2) '(1 2)) => false (define a '(1 2)) (eq? a a) => true (eq? ''1 ''1) => false (define a ''1) (eq? a a) => true (eq? if if) => true (eq? (lambda (a) a) (lambda (a) a)) => false (define b (lambda (a) a)) (eq? b b) => true (eq? 'a 'a) => true (define a 1) (define b 1) (eq? a b) => false

nil?, symbol?, pair?, list?, bool?, number?, integer?, fractional?, boxed?, string?, procedure?, special-form?, builtin?, closure?

Type checks first argument. (<type>? <form>) => bool

boxed? check can also test if value instance of some known type (boxed? <typename> <form>)

not

Returns false if argument is truthy, true if falsy. (not <form>) => true | false

Boxed memory mapped values

Boxed values provide a mechanism for custom data types with dedicated constructors, accessors, and memory management: (new <constructor> ...<form>) => <boxed> - will instantiate boxed value using constructor with arguments #.<constructor>(...<form>) => <boxed> - will instantiate boxed value using constructor with arguments (<boxed> ...<field-identifier>) - create nested boxed value by traversing a series of field identifiers on an object (set <boxed> <form>) - set value to boxed value (set ,(<boxed> ...<field-identifier>) <form>) - set value to nested boxed value ((<boxed> ...<field-identifier>) ...<form>) - call boxed value with arguments

Where field-identifier can be number or symbol: (<boxed> 1 symbol 2)

field-identifier is not evaluated by default, but it creates quasiquoted environment and evaluates ,<value>. (<boxed> unref) - try to unref referrence boxed value (<boxed> unbox) - try to unbox boxed value to native data type

vector

Shortcut to create vector instance is #(...<form>) => <vector>

Vector implements indexed access with signed index overflow and boundaries check (<vector> 0) => <first form> (<vector> -1) => <last form> (#(1 2 3) 4) => <throw: out of bound>

Fields and methods:

• (<vector> count) => <number of elements>

Miscellaneous Builtins

FD

:stdout | :stderr | :stdin | <fd-id>

print

Print arguments to file. (print '<FD>? ...<argument>) => #nil

print-flash

Flash file descriptor. (print-flash '<FD>?) => #nil

println

Print arguments to file and newline. (println '<FD>? ...<argument>) => #nil

printf

Print arguments to file. (print '<FD>? <format-string> ...<argument>) => #nil