5.2 Functions

Functions

Here is an exhaustive description of the functions provided by LispE.

@: (@ container k1 k2 k3...kn)

Returns the value corresponding to a sequence of keys. The container can be a list, a matrix, a tensor or a dictionary.

(setq r (rho 2 2 (iota 5))) ; r = ((1 2) (3 4))
(println (@ r 0 1)) ; is 2

@@: (@@ container b e)

This operator is a synonym of extract

@@@: (@@@ container shape k1 k2...)

This operator is a synonym of atshape

and: (and cond1 cond2 cond3)

Boolean AND

(and (< 10 100) (>= 10 10)) ; gives true

andvalue: (andvalue cond1 cond2 value)

Boolean AND that returns a value

(andvalue (< 10 100) (>= 10 10) 21) ; returns 21

apply: (apply fonc list)

applies a function to the following arguments

(apply '+ '(1 2 3 4)) ; gives 10

(setq f '*)
(apply f '(2 3 4)) ; gives 24

at: (at container k1 k2 k3...kn)

Returns the value corresponding to a sequence of keys. The container can be a list, a matrix, a tensor or a dictionary.

at is the official name for the operator @

(setq r (rho 2 2 (iota 5))) ; r = ((1 2) (3 4))
(println (at r 0 1)) ; is 2

atshape: (atshape container shape k1 k2 k3...kn)

Returns the value corresponding to a sequence of keys, according to a shape. The container should be a flat list of values. shape should be a list of values that provides the virtual dimensions that are projected onto the flat list of values.

When keys are negative then LispE iterates on all lines or columns.

if key is -1 then it iterates on lines.
if key is -2 then it iterates on columns.

Important: If you interpolate negative and positive dimensions, the result is unpredictable. Negative dimensions should always be together. The line or column extraction is defined by the last negative key.

atshape is the official name for the operator @@@

(setq fv (range 0 60 1))

(setq sh (integers 3 4 5))

(@@@ fv sh  1 2 3) ;33
(@@@ fv sh 1 2) ;(30,31,32,33,34)
(@@@ fv sh -1 -1 1) ;(1,6,11,16,21,26,31,36,41,46,51,56)
(@@@ fv sh -1 -2 1) ;(1 21 41 6 26 46 11 31 51 16 36 56)
(@@@ fv sh -1 -1) ;(0..59)
(@@@ fv sh -1 -2) ;(0,1,2,3,4,20,21,22,23,24,40,41,42,43,44,5,6,7,8,9,25,26,27,28,29,45,46,47,48,49...)

atomp: (atomp e)

returns true if the argument is an atom

(atomp 'e) ; returns true

atoms: (atoms)

returns the list of atoms stored at the top of the execution stack

(atoms) ; at the root returns:

(fpiecewise_linear_distribution piecewise_constant_distribution discrete_distribution log cosh cos cbrt asin alphap second hour etc.).

block

allows the evaluation of a list of lists

(if (eq x 10)
     (block 
           (print x)
            1
      )
      (+ x 1) 
)

`root`

__root__ is a specific kind of block, which is used to enclose the initial code before evaluation. Basically, we use this instruction to push the whole code within a single block.

This instruction is usually hidden within LispE's compiler, however it can be used in some cases when evaluating a block of instructions.

bodies: (bodies name)

Returns the list of bodies for defpat function definitions

break

Allows you to exit a "loop".

car, cdr, cadr, caadr

car returns the first element of a list
cdr returns the list following the first item.

Variations can also be made by mixing the a and r. For example caadr corresponds to (car (car (cdr l))).

(car '(1 2 3)) ; gives 1
(cdr '(1 2 3)) ; gives '(2 3))
(cdar '((1 5) 2 3)) ; gives (5) equivalent to (cdr (car '((1 5) 2 3)))

bappend

Appends a list of shorts to a file, byte by byte.

bread

reads a text file (UTF8) and returns the content as a list of shorts.

bwrite

Writes a list of shorts to a file, byte by byte.

bytes

This method returns the content of a string as a list of shorts, corresponding to the internal encoding of the string.

(setq s b"This is a string")
(bytes s) ; (84 104 105 115 32 105 115 32 97 32 115 116 114 105 110 103)

catch

catch is used to capture errors as a way to prevent programs from stopping.

catch acts as a block. It takes a list of instructions and stops at the first error. It then returns a maybe object that contains the error message. You can then use the instruction maybe to check if an error occurred while running the code.

(setq c
    (catch
        (setq e 10)
        (setq v 0)
        (cons ' a)
    )
)

(if
    (maybe c)
    (print Error: c)
    (print No error)
)

check: (check CONDITION I1...In)

If CONDITION is true, execute the list of instructions: I1,I2... to In.

(setq k 10)

; if k < 100, we increment it
(check (< k 100)
       (println k)
       (+= k 1)
)

(clone struct)

Clones a container or a string.

complex

This instruction is used to create complex numbers. It takes two arguments of type number to create a complex number.

A complex number can also be created with the following pattern: r,ni, where is r and n are actual values.

Complex numbers can be used in any types of numerical expressions.

It is possible to extract the real and the imaginary part with the function: real and imaginary.

;These two instructions are equivalent
(setq c (complex 10 -3))
(setq cc 10,-3i)

cond: (cond (cond1 action1) (cond2 action2)...(true final_action))

Allows to chain multiple conditions

(cond
    (
        (< x 10)
        (print x is smaller than 10)
    )
    (
        (< x 100)
        (print x is smaller than 100)
    )
    (true
        (print x is greater than 100)
    )
)

cons: (cons e l)

It creates a new list by merging the first item into the next one.

(cons 'a ()) ; gives (a)

consb: (consb l e)

consb works as a reverse cons.

(consb means cons_back)

It creates a new list with the first element as the initial list.

; Compares cons to consb on a simple example

(cons '(a b) '(c d)); is ((a b) c d)
(consb '(a b) '(c d)); is (a b (c d))

consp: (consp e)

returns true if the argument is a list

(consp '(1 2 3)) ; returns true

containerkeys: (containerkeys dict)

Returns the keys of a container. Same as keys@

(print (containerkeys d))

containervalues: (containervalues dict)

Returns values from a dictionary (see containerkeys)

Same as values@

count: (count o u pos)

Counts the number of times u is in o

(count "abcdefabdefabghabtr" "ab") ; yields 4

cutlist: (cutlist lst size)

This instruction slices a list or a string into a list of slices of same size.

(see slice for the original name)

(cutlist '(a b c d e f g h i j k l) 3) ; ((a b c) (d e f) (g h i) (j k l))

cyclicp: (cyclicp e)

returns true if the argument is a linked list that contains cycles

(setq l (llist 10 20 30))
(extend l l)
(cyclicp l) ; yields true

data: Define data structures

data is used to defined data structures, which can be used to organise data and types.

see: Data Structures for more information.

defmacro

defmacro helps define your own macros. A macro is a piece of code that is replaced on the fly within your functions. When you use a macro, there is no call to a function, since the code has been replaced with the macro instructions.

Note: You can use any variable names in the macros. Actually, when the macro is compiled, its variable names are replaced with specific macro names that cannot be confused with LispE declarable names.

; this macro returns true if a value is in a list
(defmacro in (x l) (not (nullp (find l x))))

; You simply use the name as if it was a function name.
(println (in 1 '(1 2 3 4)))

; whose underlying structure is now:
(println (not (nullp (find '(1 2 3 4) 1))))

deflib: Internal interpreter use:

see Enrich LispE

defun: (defun label (param1 param2...) code)

allows you to define a function. defun consists of a name followed by a list of arguments and the body of the function.

(defun add (x y) (+ x y))

defpat: (defpat label (param1 param2...) code)

allows you to define pattern matching functions. Note that the function name can be defined more than once, each with a different pattern.

see: Pattern Functions for more information.

dethread: (dethread label (param1 param2...) code)

dethread allows you to declare a thread. The main thread can then wait for all these threads to end their execution.

; we define a thread
(dethread call(s i)
   (loop e (range 0 i 1)
      (+= s (string e))
   )
   (println s)
)

; We call 3 threads with different arguments
(call "l:" 10)
(call "x:" 20)
(call "y:" 30)

; we wait for these threads to end
(wait)

defspace: (defspace namespace ...)

defspace defines a namespace, in which every function defined in the body is stored.

These functions can only be accessed with the space operator.

Note: namespace is always an atom.

A namespace is a way to ensure that different function implementation sharing the same name can coexist in the same program.

A namespace can be created with defspace but also load or use. Thanks to namespace, function name collisions can then be avoided.

(defspace truc

   (defun calculus (x y)
      (+ x y)
   )

   (defun toto (u v)
      (* u v)
   )
)

(println (space truc (calculus 10 20)))

dictionary: Dictionary indexed on strings

(dictionary k v k' v' k" v"...): Creates a dictionary with key/value couples

; We create a dictionary
(setq d (dictionary "a" "e" "b" "c" "d" "e"))

; We display the value for the key "a". 
(println (@ d "a"))

dictionaryi: Dictionary indexed on integers

(dictionaryi k v k' v' k" v"...): Creates a dictionary with key/value couples

; We create a dictionary
(setq d (dictionaryi 12 "e" 17 "b" 15 "hh"))

; We display the value for the key 12. 
(println (@ d 12))

dictionaryn: Dictionary indexed on numbers

(dictionaryn k v k' v' k" v"...): Creates a dictionary with key/value couples

; We create a dictionary
(setq d (dictionaryn 12 "e" 17 "b" 15 "hh"))

; We display the value for the key 12. 
(println (@ d 12))

droplist: (droplist condition list)

This function is very similar to dropwhile however, it cannot compose with other high level functions such as map, takewhile or drop.
Second, the value from the list is always appended at the end of the condition, unless you use _ as a slot filler.

As such, it is not expanded into a loop instruction as dropwhile and is much faster.

droplist drops elements from a list until the condition complies with a value. It then returns the remainder of the list.

(droplist '(< 10) '(1 4 5 11 9 11 20)) returns (11 9 11 20) ; it applies (< 10 x)
(droplist '(< _ 10) '(1 4 5 11 9 11 20)) returns (1 4 5 11 9 11 20) ; it applies (< x 10)


(droplist (lambda (x) (> x 10)) '(1 4 5 10 11 9 20)) returns (11 9 20)

eq/neq: (eq e1 e2)

comparison between two elements to verify equality neqcorresponds to (not (eq ..))

(setq x 100)
(eq x 100) ; returns true

emptyp: checks if a list is empty

(emptyp '()) ; true

eval

Allows to evaluate a string as a Lisp expression or to evaluate a list.

(eval (list 'cons ''a '''(1 2 3))) ; gives (a 1 2 3)

(eval "(cons 'a '(1 2 3))") ; also gives

explode: (explode string)

allows to transform a string into a list of atoms.

(explode "abcd") ; yields (a b c d)

extract: (extract e i1 (i2)), i2 is optional

Makes it possible to extract a sub-list between two indexes or a sub-string between numerical indexes or sub-strings. It is possible to give negative indexes which are then calculated from the end of the list or the string.

In the case of a string if the first index is also a string and the second index a number, then this number defines the number of characters to be extracted.

If only one argument is given, the function is equivalent to "@".

The operator "@@" is equivalent.

operators: +, -

These two operators must be placed just before the double-quotes.

The + indicates that the searched string must be part of the final string.
The - indicates that the search must be done reverse from the end of the string.
The -+ combines the two operators. The search is done reverse with it being part of the final string.

(extract '(1 2 3 4 5) 1 3) ; gives (2 3)
(extract "12345" 1 3) ; gives "23". 
(extract "abcdefghij" "b" "e") ; gives "cd".
(extract "abcdefghij" +"b" +"e") ; gives "bcde".
(extract "abcdefghij" "b" 3) ; gives "cde".
(extract "abcdefghij" +"b" 3) ; gives "bcde".
(extract "12345" -2) ; gives "4".
(extract "12345" 1 -1) ; gives "234". 
(extract "/home/test/titi/toto/name.txt" -"/" 0) ; yields "name.txt"
(extract "/home/test/titi/toto/name.txt" -+"/" 0) ; yields "/name.txt"

; We can also use @@ in lieue of extract
(@@ "/home/test/titi/toto/name.txt" -"/" 0) ; yields "name.txt"
(@@ "/home/test/titi/toto/name.txt" -+"/" 0) ; yields "/name.txt"

fappend: (fappend pathname data)

writes a string at the end of a file

filterlist: (filterlist condition list)

This function is very similar to filter however, it cannot compose with other high level functions such as map, takewhile or drop.
Second, the value from the list is always appended at the end of the condition, unless you use _ as a slot filler.

As such, it is not expanded into a loop instruction as filter and is much faster.

(filterlist '(< 10) '(1 4 5 10 11 20)) returns (11 20), we test (< 10 list_value)
(filterlist '(< _ 10) '(1 4 5 10 11 20)) returns (1 4 5), we test (< list_value 10)

; Note that (filter '(< 10) '(1 4 5 10 11 20)) returns (1 4 5)

(filterlist (lambda (x) (< x 10)) '(1 4 5 10 11 20)) returns (1 4 5)

Note that: (filterlist '(< 10) '(1 4 5 10 11 20)) is equivalent to (filterlist '(< 10 _) '(1 4 5 10 11 20)).

find: (find e o pos)

returns the position of e in o or nil. o is either a list or a string.

(find "abcdef" "bc") ; gives 1
(find "abcdef" "bd") ; gives nil

findall: (findall string string pos)

returns a list of all positions of the sub-string in the string.

(findall "abcdefabdefabghabtr" "ab") ; gives (0 6 11 15)

flatten: (flatten l)

Flatten a list or a dictionary.

(flatten '( ( (1 2) (3 4)) (5 6))) ; yields (1 2 3 4 5 6)

float: (float e)

converts a string into a float (32 bits)

(float "12.3") ; gives 12.3

floats: (floats e)

Converts a list into a list of floats. e can also be more than one elements.

(floats '(1.2 3.3 4 5))
(floats 1.2 3.3 4 5) ; is also acceptable

flip: (flip (f x y))

flips the two first arguments of a function.

Note: If you use flip on a dictionary, it will reverse keys and values.

(flip (- 10 2)) ; yields: -8

fread: (fread pathname)

reads a text file (UTF8) and returns the content as a string of bytes: (fread "file")

fwrite: (fwrite pathname data)

writes a string to a file

heap: (heap comparison v1 v2 ...)

A heap is a structure in which element are automatically sorted out according to the comparison provided. The heap is implemented with a binary tree, where elements are compared through the comparison operator or lambda.

A heap can be created with a first list of values.
An element is inserted in a heap with: insert.
An element is removed from a heap with: pop, popfirst, poplast.
car returns the first element of the structure
cdr does not apply in this context.
@ works, the index is used to traverse the structure in a prefix way (top-down).
If comparison is nil or (), then the default comparator is: >=<. Note that (>=< x y) returns:

-1 if x is lower than y

0 if x is equal to y

1 if x is greater than y

If comparison is a lambda expression, then it must return

-1 if x is lower than y

0 if x is equal to y

1 if x is greater than y

(setq h (heap '>=< 10 30 20 19 12)) ; h is (10 12 19 20 30)
(insert h 2) ; h is (2 10 12 19 20 30)
(pop h 19) ; h is (2 10 12 20 30)

; We sort out elements according to their first element
(setq comparison (\(x y) (>=< (car x) (car y))))
(setq h (heap comparison '(16 (0 3)) '(11 (0 2)) '(11 (1 1)) '(18 (2 0))))

; h is now ((11 (0 2)) (11 (1 1)) (16 (0 3)) (18 (2 0)))

(car h) ; is (11 (0 2))

(@ h 0) ; is (16 (0 3)), which is the root of the tree
(@ h 1) ; is ((11 (0 2)) (11 (1 1))) since they share the same first element
(@ h 2) ; is (18 (2 0))
(@ h -1) ; is (18 (2 0)), the last node of the tree

; You can loop on values
(loop c h
   (print c)
)

(to_list h) ; is ((11 (0 2)) (11 (1 1)) (16 (0 3)) (18 (2 0)))
; Note that the node that contains two values has been reverted compared to to_list
(to_llist h) ; is ((11 (1 1)) (11 (0 2)) (16 (0 3)) (18 (2 0)))

if: (if (predicate) THEN ELSE)

test the predicate, if it's true execute THEN if not ELSE. ELSE is optional.

(if (eq x 10) (println true) (println false))

ife: (ife (predicate) THEN ELSE_BLOCK)

test the predicate, if it's true execute THEN if not ELSE. The ELSE is actually a block of instructions.

; if x ≠ 10 then (setq x 20) and (println false) will be executed
; otherwise only (println true)

(ife (eq x 10) (println true) (setq x 20) (println false))

imaginary

This method returns the imaginary part of a complex number.

(setq c 12,-3i)
(set r (imaginary c)) ; r is -3

in: (in e o pos)

returns true or nil if e in o. o is either a list or a string.

(in "abcdef" "bc") ; gives true
(in "abcdef" "bd") ; gives nil

input

Allows to read an input from keyboard. You can also provide a string that can be modified in input

; keyboard reading of a string
(setq v (input))

; We can also modify the content of v again
(setq v (input v))

integer: (integer e)

converts a string into an integer value

(integer "12") ; gives 12

integers: (integers e)

converts a list into a list of integers. e can also be more than one elements.

(integers '(1 3 4 5))
(integers 1 3 4 5) ; is also acceptable

insert: (insert l e idx)

Inserts the e element in l at the idx position.

l can be a list or a string

(insert '(1 2 3) 4 1) ; gives (1 4 2 3)

(insert l e function)

There is a second use of insert with a function. In this case, the function is used to determine where to add the element.

IMPORTANT: insert uses a dichotomy algorithm to store elements in a list. However, if you have a large number of elements, it is much more efficient to use a heap

(setq r '(10 20 30 40 50))
(insert r 15 '<) ; yields (10 15 20 30 40 50)
(insert r 35 '<) ; yields (10 15 20 30 35 40 50)

join: (join l sep)

transforms a list of atoms into a string

(join '(a b c) '/) ; gives "a/b/c".

key: Dictionary indexed on strings of characters

Four actions:

(key): creates a dictionary
(key k v k' v' k" v"...): Creates a dictionary with key/value couples
(key d k v k' v' k" v"...): sets key/value couples in dictionary d
(key d k): returns the value in the dictionary d for key k

Note: However, key can create a dictionary indexed on strings, it is better to use dictionary for this purpose.

; We create a dictionary
(setq d (key))

; Values are added to the dictionary
(key d "a" "e" "b" "c" "d" "e")

; We display the value for the key "a". 
(println (key d "a"))

keyi: Dictionary indexed on integers

(keyi): creates a dictionary
(keyi k v k' v' k" v"...): Creates a dictionary with key/value couples
(keyi d k v k' v' k" v"...): sets key/value couples in dictionary d
(keyi d k): returns the value in the dictionary d for key k

Note: However, keyi can create a dictionary indexed on integers, it is better to use dictionaryi for this purpose.

; We create a dictionary
(setq d (keyi))
; We add a value in the dictionary
(keyi d 12 "e" 17 "b" 15 "hh")

; The value for key 12 is displayed.
(println (keyi d 12))

keyn: Dictionary indexed on numbers

(keyn): creates a dictionary
(keyn k v k' v' k" v"...): Creates a dictionary with key/value couples
(keyn d k v k' v' k" v"...): sets key/value couples in dictionary d
(keyn d k): returns the value in the dictionary d for key k

Note: However, keyn can create a dictionary indexed on numbers, it is better to use dictionaryn for this purpose.

; We create a dictionary
(setq d (keyn))
; We add a value in the dictionary
(keyn d 12 "e" 17 "b" 15 "hh")

; The value for key 12 is displayed.
(println (keyn d 12))

keys@: (keys@ dict)

Returns the keys of a container

(print (keys@ d))

label: (label lab exp)

Saves the argument under the provided label

(label myLabel (lambda (x) (eq x 10))

lambda: definition of a lambda function

Note that we accept \ and λ (Unicode 955) as substitute characters for the keyword lambda

( (lambda (x y) (+ x y)) 10 20)
( (\ (x y) (+ x y)) 10 20)
( (λ (x y) (+ x y)) 10 20)

last: (last e)

returns the last element of a list or the last character of a string.

(last '(1 2 3)) ; returns 3

link: (link str atom)

Create a string that shares the same id as a given atom. This is especially useful to modify the behaviour of the tokeniser in LispE.

(see cosine for an example)

; "BEGIN" and "END" have now the same ids as '( and ')
(link "BEGIN" (atom "("))
(link "END" (atom ")"))

; It is now possible to evaluate as if it was: (+ 10 20)
BEGIN + 10 20 END

; we replace the + sign with the *
(link "+" '*)
(+ 10 20) ; is now 200

list: (list e1 e2 ..)

creates a list from the arguments

(list 'a 12 34) ; gives (a 12 34)

llist: (llist e1 e2 ..)

Creates a linked list from the arguments.

A linked list is a list where each element is linked to the next through a pointer.

A linked list can contain cycles.

push and pop push and remove an element at the beginning of a linked list by default.
cdr can indefinitely loop if the list contains a cycle.
loop will detect any cycle and will stop once all elements have been visited.

; or a list of elements as for a regular list operation
(setq ll (llist 10 20 30))
(push ll 100) ; yields (100 10 20 30)
(extend ll ll) ; connects then end of the list with its beginning creating a cycle

; The following code will loop 6 times in this 4 elements cyclic list
(loopcount 6
   (setq ll (cdr ll))
   (println ll)
)

; To create a linked list out of a list
(setq lbis (to_llist (list 20 30 40 50)))


; the ... indicates that the list contains a cycle

(10 20 30 100 ...)
(20 30 100 10 ...)
(30 100 10 20 ...)
(100 10 20 30 ...)
(10 20 30 100 ...)
(20 30 100 10 ...)

load: (load filename)

loads and runs a LispE program provided as a file.

(setq tst (load "file.lisp"))

load: (load filename namespace)

To avoid some name conflicts, it is possible to load a file within a namespace. Functions then will be accessed with the space operator.

Note: namespace in this case is an atom.

(load "file.lisp" truc)

loadcode: (loadcode str (namespace))

Same as load, but takes a string as input.

lock: (lock key instructions)

This instruction protects a block of instructions in a thread. key is a string that is used to identify the lock. It is implemented as a recursive mutex.

loop: (loop var list instruction1 instruction2...)

allows to iterate on a list or a string: (loop var list instruction). The last element of the iteration returns the final result.

(loop i '(1 2 3) 
        (print i)
        (+ i 2)
)

(lloop (x1 x2 x3...) l1 l2 l3... instructions)

lloop is used to iterate in parallel among different lists.

To iterate on different types, such as dictionaries, use: mloop.

In that case, you need to provide as first argument, a list of variables and next to it a succession of lists, whose number must match the number of variables.

; x will loop on (1 3 4)
; y will loop on (5 6 7)
; z will loop on (9 10 13)
(lloop (x y z) '(1 3 4) '(5 6 7) '(9 10 13) (println (+ x y z)))

; 15
; 19
; 24

loopcount: (loopcount nb instruction1 instruction2...)

allows to iterate nb times. The last element of the iteration returns the final result.

(setq i 0)
(loopcount 10 
        (print i)
        (+= i 2)
)

maplist

This instruction is similar to map. It offers a much faster implementation. However, it cannot compose with other high level functions such as filter or takewhile. Furthermore, it can only apply functions of arity 1.

(maplist (lambda(x) (+ x x)) (iota 10)) ; (2 4 6 8 10 12 14 16 18 20)

By default, maplist utilises the first element produced by the lambda to define the type of list that will be built. For instance, if this element is a string, maplist will create a strings object.

maplist can take a fourth parameter, which when false forces the output to be a regular list.

(type (maplist (lambda(x) (+ x x)) (iota 10))) ; yields integers_
(type (maplist (lambda(x) (+ x x)) (iota 10) false)) ; yields list_

Furthermore, you can use maplist with a simple list containing an operator with values. You use then _ as a slot filler.

(maplist (- 10 _) (iota 10)) ; (9 8 7 6 5 4 3 2 1 0) 
(maplist (- _ 10) (iota 10)) ; (-9 -8 -7 -6 -5 -4 -3 -2 -1 0)

Note that: (maplist (- 10 _) (iota 10)) is equivalent to (maplist (- 10) (iota 10)).

mapcar

mapcar shares the same implementation as maplist, however it systematically returns a regular list.

This function has been implemented to keep some consistency with other Lisp implementations.

(mapcar (\(x) (+ x 1)) (integers 1 2 3)) ; is equivalent to 
(maplist (\(x) (+ x 1)) (integers 1 2 3) false)

mark

This instruction is used with lists to handle potential list infinite loops. It has two different utilisations:

(mark l B): marks the list with the Boolean value: B
(mark l): returns the Boolean value attached to this list...

Note that in the case of an infinite loop, the list is displayed with: '...' instead of the element that is infinitely repeated:

(setq a '(1 2 3))
(setq b '(10 20 30))
; we create an infinite loop
(push a b)
(push b a)

(println a) ; display: (1 2 3 (10 20 30 ...))
(println b) ; display: (10 20 30 (1 2 3 ...))

; Looping in the structure
; when mark is true, we stop ans display a warning message
(defun traverse (l)
   (check (consp l)
      (ife (mark l)
         (println "Warning: infinite loop")
         (println (at l 0))
         (mark l true)
         (traverse (car l))
         (traverse (cdr l))
         (mark l false)
      )
   )
)

(traverse a)

maybe

This instruction checks whether a value returned by catch was an error or detects errors in a sequence of instructions.

maybe exposes two different modes:

It has one single argument, then it returns true if the value is a maybe object returned by a catch.
It has at least two arguments. Each instruction is executed in sequence except for the last one. If one instruction fails, then the last one is executed.

(setq c
    (catch
        (cons ' a)
    )
)

; With one parameter, we can then use the caught value to display an error message
(if
    (maybe c)
    (print Error: c)
    (print No error)
)

; with more than one parameters
; if an error occurs in one of the instructions, then the last instruction is executed...
(maybe (cons 'a ())
       (cons 'b ())
       (cons 'c)
       (println "An error occurred")
)

max: (max a1 a2 a3) / (max '(e1 e2 e3))

Returns the largest element in a string of arguments or the largest element in a list.

(max 1 4 5 10 8) ; returns 10
(max '(1 4 5 10 8)) ; returns 10

min: (min a1 a2 a3) / (min '(e1 e2 e3))

Returns the smallest element in a string of arguments or the smallest element in a list

(min 1 4 5 10 8) ; returns 1
(min '(1 4 5 10 8)) ; returns 1

minmax: (min a1 a2 a3) / (minmax '(e1 e2 e3))

Returns a list containing the largest and the smallest element in a list

(minmax 1 4 5 10 8) ; returns (1 10)

mloop : (mloop (x1 x2 x3...) c1 c2 c3... instructions)

mloop is used to iterate in parallel among different containers that are not all lists.

In that case, you need to provide as first argument, a list of variables and next to it a succession of lists, whose number must match the number of variables.

; x will loop on (1 3 4)
; y will loop on {"a":10 "b":20 "c":4} (actually on the values not the keys)
; z will loop on (9 10 13)
(mloop (x y z) '(1 3 4) {"a":10 "b":20 "c":4} '(9 10 13) (print (+ x y z)))

; 14
; 33
; 27

ncheck: (ncheck CONDITION ELSE_I I1...In)

If CONDITION is true, execute the list of instructions: I1,I2... to In.

If CONDITION is nil, execute ELSE_I.

(setq k 10)

; if k < 100, we increment it
(ncheck (< k 100)
       (println 'end) ; if k == 100, we stop and display a message
       (println k)
       (+= k 1)
)

nconc: (nconc l1 l2 l3...x)

List concatenation. All arguments should be a list except for the last one. The concatenation is made into the first argument...

 
 (nconc) is  nil
 (setq x '(a b c)) =>  (a b c)
 (setq y '(d e f)) =>  (d e f)
 (nconc x y) =>  (a b c d e f)

; x is now  (A B C D E F)

nconcn: (nconcn l1 l2 l3...x)

List concatenation. All arguments should be a list except for the last one. The concatenation creates a new list... nconcn is identical to nconc except for the fact that it creates a new list.

 
 (nconcn) is  nil
 (setq x '(a b c)) =>  (a b c)
 (setq y '(d e f)) =>  (d e f)
 (nconcn x y) =>  (a b c d e f)

; x is not modified

not: (not e)

Boolean Negation: (not true) gives false

nullp: test if the argument is nil

number: (number e)

converts a string into a number

(number "12") ; gives 12

nth:

Returns the value corresponding to a sequence of keys. The container can be a list, a matrix, a tensor or a dictionary. Other name to at.

(setq r (rho 2 2 (iota 5))) ; r = ((1 2) (3 4))
(println (nth r 0 1)) ; is 2

numberp: check if the argument is a number

numbers: (numbers e)

converts a list into a list of numbers. e can also be more than one elements.

(numbers '(1.2 3.3 4 5))
(numbers 1.2 3.3 4 5) ; is also acceptable

or: or Boolean

(or (eq 10 20) (eq 20 20)) ; returns true

over: (over 'function list)

over applies a function or a lambda to list, and replaces the value of list with the new values.

(setq l '(1 2 3))
(over 'rotate l) ; l is now (3 1 2)

pipe: (pipe)

Read the pipe on the command line... Return nil when the pipe is empty...

; As long as there is data in the pipe, we read it...
(setq p (pipe))
(while p (setq p (pipe))

pop: (pop e cle)

Removes a value from a list, a dictionary or a string.

(pop '(A b c) 1) ; gives (A c)
(pop {12:34} 12) ; gives {}.
(pop "abc" 2) ; gives "ab".

popfirst: (popfirst e)

Removes the first value from a list or a string.

(popfirst '(A b c)) ; gives (b c)
(popfirst "abc") ; gives "ab".

poplast: (poplast e)

Removes the last value from a list or a string.

(poplast '(A b c) 1) ; gives (A b)
(poplast "abc" 2) ; gives "ab".

prettify: (prettify l mx)

Displays in a more readable form a parenthesized structure. The last parameter mx is optional. It defines the longest string that can be produced on a line by concatenating different sub-lists.

print: (print e1 e2 .. en)

Displays the values on the screen

println: (println e1 e2 .. en)

Displays the values on the screen by separating them with a space and placing a carriage return at the end.

printerr: (printerr e1 e2 .. en)

Displays the values on the screen on stderr.

printerrln: (printerrln e1 e2 .. en)

Displays the values on the screen by separating them with a space and placing a carriage return at the end, on stderr.

push: (push l a)

adds an item to the l list. Be careful, if the list is a constant element, this operation returns a copy.

(push '(1 2 3) 4) ; returns (1 2 3 4) which is a copy of the initial list.

; So, pay attention to the following code:
(push '(1 2 3) 12) ; returns a copy of the list

pushfirst: (pushfirst l a)

adds an item at the beginning of the l list. Be careful, if the list is a constant element, this operation returns a copy.

(pushfirst '(1 2 3) 4) ; returns (4 1 2 3) which is a copy of the initial list.

; So, pay attention to the following code:
(pushfirst '(1 2 3) 12) ; returns a copy of the list

pushlast: (pushlast l a)

adds an item at the end of the l list. Be careful, if the list is a constant element, this operation returns a copy.

(pushlast '(1 2 3) 4) ; returns (1 2 3 4) which is a copy of the initial list.

; So, pay attention to the following code:
(pushlast '(1 2 3) 12) ; returns a copy of the list

pushtrue: (pushtrue l a)

adds an item to the l list, if this value is not nil. Be careful, if the list is a constant element, this operation returns a copy.

(pushtrue r 4 (<1 9) (< 3 1)) ; returns (4 true) (< 3 1) is skipped

; pushtrue can be combined with andvalue

(setq l ())
(loop r (irange 0 10 1)
   (pushtrue l 
       (andvalue
          (eq (% r 2) 0)
          (* 2 r)
       )
    )
)

; The result is then: (0 4 8 12 16)

This is equivalent to:
(loop r (irange 0 10 1)
   (if (eq (% r 2) 0)
       (push l (* 2 r)
    )
)

quote: (quote arg)

The operator associated with '. Returns without evaluating its argument.

range: (range initial limit step)

Returns a list of values starting at initial, ending at limit in steps.

These lists are either a numbers type or an integers type according to the different values given as arguments

(range 1 10 1) ; yieds (1 2 3 4 5 6 7 8 9), which is an 'integers' type

rangein: (rangein initial limit step)

Returns a list of values starting at initial, ending at limit in steps.

The difference with range is that the limit is part of the values.

These lists are either a numbers type or an integers type according to the different values given as arguments

(rangein 1 10 1) ; yieds (1 2 3 4 5 6 7 8 9 10), which is an 'integers' type

Exits a loop or a function and returns its argument.

replaceall: (replaceall object search replace)

Replaces all the occurrences of search in object with replace. Returns the number of replacements.

object can be any container or a string.

(setq l (integers 10 20 10 40))
(setq nb (replaceall l 10 100)) ; nb is 2 and l is now: (100 20 100 40)

real

This method returns the real part of a complex number.

(setq c 12,3i)
(set r (real c)) ; r is 12

resetmark

Resets the marks on lists for control over infinite loops.

⌽: rotate: (rotate l nb (line))

l is a list, a matrix or a tensor
nb:
1. nb < 0: the container is rotated to the right of nb increments
2. nb > 0: the container is rotated to the left of nb increments
3. false or absent: the container is rotated to the right of 1 increment
4. true: the container is rotated to the left of 1 increment
line:
1. false or absent: if the container is a matrix or a tensor, the matrix is rotated along the columns
2. true: if the container is a matrix or a tensor, the matrix is rotated along the lines

(rotate "abcde") ; yields "eabcd"
(rotate "abcde" true) ; yields "bcdea"
(⌽ (iota 10)) ; yields (2 3 4 5 6 7 8 9 10 1)
(⌽ (iota 10) true) ; yields (10 1 2 3 4 5 6 7 8 9)

(iota 10) ; (1 2 3 4 5 6 7 8 9 10)
(rotate (iota 10) -2) ; (9 10 1 2 3 4 5 6 7 8)
(rotate (iota 10) 2) ; (3 4 5 6 7 8 9 10 1 2)

return: (return a)

Exit a function and return a value

(function call(i)
   (while (< i 10)
      (if (eq i 5)
          (return i)
          (-= i 1)
      )
   )
)

reverse: (reverse l local)

Reverse a string or a list.

local can be either:

false: in this case the list is reversed locally (the default value).
true: in this case, a duplicate of the list is returned

(reverse '(a b c)) ; gives (c b a)

(reverse "abc") ; gives "cba". 

(setq l (iota 10)) ; l is (1 2 3 4 5 6 7 8 9 10) 

(reverse l true) ; l is now (10 9 8 7 6 5 4 3 2 1)

rfind: (find string subch)

Search for a sub-string of characters from the end.

select: (select c1 c2 c3...)

Returns the first non nil value.

; returns either a value in the dico if the key is present of the key itself
(select (key dico k) k)

self: (self e1 e2...)

Allows to make a recursive call in a function or lambda.

( lambda (x) (if (eq x 1) 1 (+ x (self (- x 1))))) 12))

set: set, sets, setn, seti

Creates sets of elements.

sets, setn, seti create respectivement:

sets: set of strings
seti: set of integers
setn: set of numbers

set is used to create sets of objects.

An element is pushed into a set with either insert or push.

An element is removed from a set with pop.

You can check if an element belong to a set with in.
You can access an element in a set with @.
You can loop on all values in a set.

(setq strset (sets "ab" "cd" "ef"))
(push strset "ok")
(if (in s "ok") 'ok 'no)

(setq o_set (set '(1 2 3) '(1 2) '(8 9))
(println (type (@ o_set '(1 2))) ; list_

set@: (set@ container k1 k2 k3...kn value)

Set a value at the position corresponding to the sequence of keys

(setq r (rho 2 2 (iota 5))) ; r = ((1 2) (3 4))
(set@ r 0 1 100)) ; r is now ((1 100) (3 4))

set@@: (set@@ container beg end value)

Replaces a range of values between beg and end with value.

set@@ is a synonym to setrange.

(setq r '(1 2 3 4 5 6))
(set@@ r 0 3 100) ; r is now (100 4 5 6)

set@@@: (set@@@ container shape k1 k2 k3...kn value)

Replace a value or a sequence of values corresponding to a sequence of keys, according to a shape. The container should be a flat list of values. shape should be a list of values that provides the virtual dimensions that are projected onto the flat list of values. This is the pendant of atshape.

set@@@ is a synonym to setshape.

setg: (setg label value)

Initialization of a global variable with a value. If label is a function, then it replaces the function body with value.

setq: (setq label value)

Initialization of a variable with a value

setshape: (setshape container shape k1 k2 k3...kn value)

Replace a value or a sequence of values corresponding to a sequence of keys, according to a shape. The container should be a flat list of values. shape should be a list of values that provides the virtual dimensions that are projected onto the flat list of values. This is the pendant of atshape.

keys cannot be negative.

setshape is the official name for the operator set@@@

(setq fv (range 0 60 1))

(setq sh (integers 3 4 5))

; changing one value
(set@@@ fv sh 1 2 3 100)

;changing a sequence of values
(set@@@ fv sh 1 2  '(-1 -2 -3 -4 -5))

seth: (set a value in the common thread space)

seth can only be used in conjunction with threadspace. It creates a variable in the common thread space.

The access to this variable is automatically protected with an internal lock. Note that this lock is the same as in threadstore, threadretrieve and threadclear. Once a variable has been created with seth, it can only been accessed within threadspace. However, it is then treated as a regular variable as shown below.

; We create in the main section two specific thread safe variables titi and toto
(threadspace
   (seth titi 10)
   (seth toto (rho 4 4 '(0)))
)

; titi and toto are accessed via threadspace in this thread
(dethread tst(x y)
   (threadspace
      (+= titi x)
      (set@ toto 0 y titi)
   )
)

; We call our threads
(tst 10 0)
(tst 20 1)
(tst 30 2)
(tst 40 3)

; we wait for their completion
(wait)

; again titi and toto are only available in threadspace
; Note that threadspace is equivalent to space thread...
(space thread
   (println titi)
   (println toto)
)

setrange: (setrange container beg end value)

Replaces a range of values between beg and end with value.

This method utilizes the same interval description as extract.

setrange can also be written: set@@

(setq r '(1 2 3 4 5 6))
(setrange r 0 3 100) ; r is now (100 4 5 6)

short: (short e)

converts a string into a short (16 bits)

(short "12") ; gives 123

shorts: (shorts e)

Converts a list into a list of shorts. e can also be more than one elements.

(shorts '(12 33 4 5))
(shorts 12 33 4 5) ; is also acceptable

sign: (sign e)

Changes the sign of e.

(sign 10) ; -10
(sign -10) ; 10

signp: (signp e)

If e is negative: returns -1
If e is 0: returns 0
If e is positive: returns 1

size: (size e)

Returns the size of a list or a string

sleep: (sleep tm)

Put a thread in sleep mode for tm milliseconds.

slice: (slice lst size)

This instruction slices a list or a string into a list of slices of same size.

(slice '(a b c d e f g h i j k l) 3) ; ((a b c) (d e f) (g h i) (j k l))

sort: (sort comparator list)

Sort a list. Important, the comparator must not return true in case of a tie. Thus <= is a bad comparison operator.

(sort '< '(1 7 9 4 3)) (1 3 4 7 9)
(sort '> '(1 7 9 4 3)) (9 7 4 3 1)

space: (space namespace ...)

The space operator makes it possible to execute functions that were defined in a namespace with defspace or load or use.

This operator works as a block.

The main namespace is called: mainspace_.

It is possible to embed different space calls within a space.

Note: space thread is actually equivalent to threadspace.

; We define some functions in a space named truc
(defspace truc

   (defun calculus (x y)
      (+ x y)
   )

   (defun toto (u v)
      (* u v)
   )
)

(defun calculus (x y)
   (+ x (* x y))
)

(space truc 
   (setq r (calculus 10 20))
   (setq v (toto 100 200))
 ; here we force the call to the global implementation of calculus within another space definition
   (setq x (space mainspace_ (calculus 10 5)))
)

(setq o (calculus 10 20)) ; Note that in this case we call the local version of calculus

string: (string e)

Converts its argument into a string

stringbyte: (stringbyte e)

Converts its argument into a string of bytes. A string byte can also be created with the b"" notation:

(setq s b"This is a string byte")

stringf: (stringf n format)

Converts its argument (a number) into a string with a format based on C function printf.

(stringf 123 "0x%X") ; is 0x7B

stringp: (stringp e)

Check if e is a string

strings: (strings e)

converts a list into a list of strings. e can also be more than one elements.

(strings '("a" "b" "c" "d"))
(strings "a" "b" "c" "d") ; is also acceptable

stringbytes: (stringbytes e)

converts a list into a list of byte strings. e can also be more than one elements.

(stringbytes '("a" "b" "c" "d"))
(stringbytes "a" "b" "c" "d") ; is also acceptable

switch: (switch v (c0 codes) (c1 codes).. (true final_action))

c0...cn are either strings or numbers.
codes is a block of code

This method works as a switch in C++ or Java. It checks v against the different case values in the structure.

However, switch uses an internal dictionary, which makes this comparison straightforward.

The default value is implemented as in cond, with true.

(setq c 10)

(switch c 
   (0 1) 
   (10 'yes) 
   (true 'unknown)
) ; yields yes

takelist: (takelist condition list)

This function is very similar to takewhile however, it cannot compose with other high level functions such as map, takewhile or drop.
Second, the value from the list is always appended at the end of the condition, unless you use _ as a slot filler..

As such, it is not expanded into a loop instruction as takewhile and is much faster. takelist extracts elements from a list that comply with the condition. It stops when an element does not comply anymore.

(takelist '(> 10) '(1 4 5 10 9 11 20)) returns (1 4 5) ; it applies (> 10 x)
(takelist '(> _ 1) '(4 5 1 10 9 11 20)) returns (4 5) ; it applies (> x 1)

(takelist (lambda (x) (< x 10)) '(1 4 5 10 11 20)) returns (1 4 5)

takenb: (takenb nb lst (beginning true))

Extracts nb elements from the beginning of lst. If beginning is false, then extracts the last nb values from lst.

Note that if nb is negative and beginning is true, then the elements are also extracted at the end.

(takenb 3 '(1 2 3 4 5)) ; (1 2 3)

(takenb 3 '(1 2 3 4 5) false) ; (3 4 5)

(takenb -3 '(1 2 3 4 5)) ; (3 4 5)

tally

tally returns the number of elements of a matrix or a tensor. Applied to a list, it simply returns its size.

(setq r (rho 3 4 5 (iota 60)))

(tally r) ; 60

to_list: (to_list object)

This instruction transforms any kind of container into a list.

(to_list (numbers 10 20 30)) ; is now a list

to_list: (to_list value nb)

These is a second implementation of this method with three parameters.

In this case, LispE creates a list of nb values.

(to_list "a" 10) ; ("a" "a" "a" "a" "a" "a" "a" "a" "a" "a")

to_llist: (to_llist object)

This instruction transforms any kind of container into a llist (linked list).

(to_llist (list 10 20 30)) ; is now a llist

to_tensor

This function transforms a list of values into value lists, matrices or tensors.

A list can be transformed into these elements only they present a regularity in types and sizes.

(setq l '((1 2 3) (4 5 6)))
(to_tensor l) ; a matrix_integer

(setq l '((1 2 3) (4 5 6 8)))
(to_tensor l) ; returns a list, the sublists have different sizes

threadretrieve: (threadretrieve namespace)

This instruction returns the data that were stored in the protected list with threadstore, within a thread. namespace is a string that defines a namespace in which your data is stored. You can implement as many namespaces as you want.

If you use threadretrieve without any namespace, it returns a dictionary containing all the namespaces and their values.

(dethread call(i)
   (setq l (range 1 i 1))
   ; our namespace is "here":
   (threadstore "here" l)
)

(call 10)
(call 100)
(call 20)

(wait)

(println (threadretrieve "here"))

threadstore: (threadstore namespace e)

This instruction should be used in a thread to store elements that should survive the thread itself. This instruction stores the information in a protected list that can be accessed through retrieve. namespace is a string that defines a namespace in which your data is stored. You can implement as many namespaces as you want.

(dethread call(i)
   (setq l (range 1 i 1))
   (threadstore "other" l)
)

threadclear: (threadclear namespace)

Clear the protected list used in threads to keep data alive. namespace is a string that defines a namespace in which your data is stored. You can implement as many namespaces as you want.

If you do not provide any namespace, then all spaces will be deleted.

(dethread call(i)
   (setq l (range 1 i 1))
   (threadstore "tobecleared" l)
)

(call 10)
(call 100)
(call 20)

(wait)

(println (threadretrieve "tobecleared"))

; we clear the namespace: "tobecleared"
(threadclear "tobecleared")

threadspace

threadspace works as a block in which thread safe variables can be created and manipulated. Variables in threadspace are created with seth. However their access is similar to any variables henceforth.

Note: threadspace is actually equivalent to space thread.

; We create in the main section two specific thread safe variables titi and toto
(threadspace
   (seth titi 10)
   (seth toto (rho 4 4 '(0)))
)

; titi and toto are accessed via threadspace in this thread
(dethread tst(x y)
   (threadspace
      (+= titi x)
      (set@ toto 0 y titi)
   )
)

; We call our threads
(tst 10 0)
(tst 20 1)
(tst 30 2)
(tst 40 3)

; we wait for their completion
(wait)

; again titi and toto are only available in threadspace
; Note that threadspace is equivalent to space thread...
(space thread
   (println titi)
   (println toto)
)

trace: (bool trace)

Activates the trace during execution: (trace true)

type: (type e)

Returns the type of its argument

unique: (unique lst)

Remove the duplicates in lst. The comparison is done with: ==

use: (use bib)

Loads a dynamic library whose path is given by the environment variable: LISPEPATH.

use: (use bib namespace)

It is also possible to load this library within a namespace.

Use space to access the different functions.

uuid: Universally Unique Identifier

This function returns an UUID in agreement with UUID RFC 4122, version 4 (fully random). It returns a string value containing hexadecimal values of the form: XXXXXXXX- 4XXX- 1XXX- XXXX- XXXX

(setq u (uuid)) ; u is 80c67c4d-4c4d-14cd-e58d-eb3364cd

trigger: (trigger key)

Wake up all threads waiting on key.

values@: (values@ dict)

Returns values from a dictionary (see keys@)

wait: wait for threads to end

This instruction allows you to wait for all threads to finish. See dethread for an example.

waiton: (waiton key)

Put a thread on hold until it is woken up with trigger on that key.

while: (while (condition) instruction1 instruction2 ...)

Allows looping as long as a condition is true.

(setq v 10)
(while (> v 0) (setq v (- v 1))