corelib.md

Ablisp Corelib

Generated by examples/gen-corelib-doc.lisp.

Declaration: def

Defines a variable.

> (def x (+ 1 2))
> x
;=> 3

Declaration: defun

Defines a function.

> (defun incr (x) (+ x 1))
> (incr 3)
;=> 4
> (defun sum (xs) (if xs (+ (car xs) (sum (cdr xs)) 0)))
> (sum '(1 2 3))
;=> 6

Special form: let

Binds values to local variables.

> (let ((a 1)
        (b 2))
      (+ a b))
;=> 3

Special form: letrec

Similar to let, but when binding values to variables, their expressions can access the local variables that are being defined.

> (letrec ((f (lambda (n) (if (eqv? n 0) 0 (+ n (g (- n 1))))))
           (g (lambda (n) (if (eqv? n 0) 0 (+ n (f (- n 1)))))))
      (f 3))
;=> 6

Special form: if

Branches the execution of a code based on a given condition.

> (if t 1 2)
;=> 1
> (if nil 1 2)
;=> 2
> (if (eqv? 1 2)
      (error "unreachable"))
;=> nil

Special form: cond

Similar to if, but takes multiple clauses.

> (let ((a 3))
    (cond
      ((eqv? a 2) (echo "foo") "a is 2")
      ((eqv? a 3) (echo "bar") "a is 3")
      (else "not sure")))
bar
;=> "a is 3"

Special form: begin

Evaluates a sequence of expressions.

> (begin
    (echo "Hello")
    123)
Hello
;=> 123

Special form: set!

Updates the value of a variable.

> (let ((a 1)
        (b 2))
      (set! a 999)
      (cons a b))
;=> (999 . 2)

Special form: lambda

Makes an anonymous function.

> ((lambda (a b)
       (echo "Calculating...")
       (+ a b))
   1 2)
Calculating...
;=> 3

Special form: quote

Returns an unevaluated argument.

> (quote 3)
;=> 3
> (quote foo)
;=> foo
> (quote (a b c))
;=> (a b c)
> '(a b c)   ; shorthand for quote
;=> (a b c)

Function: cons

Makes a cons-cell.

> (cons 1 2)
;=> (1 . 2)
> (cons 'a (cons 'b (cons 'c nil)))
;=> (a b c)

Function: car

Returns the first element of a cons-cell.

> (car (cons 1 2))
;=> 1

Function: cdr

Returns the second element of a cons-cell.

> (cdr (cons 1 2))
;=> 2

Function: set-car!

Updates the first element of a cons-cell.

> (let ((pair (cons 1 2)))
      (set-car! pair 999)
      pair)
;=> (999 . 2)

Function: set-cdr!

Updates the second element of a cons-cell.

> (let ((pair (cons 1 2)))
      (set-cdr! pair 999)
      pair)
;=> (1 . 999)

Function: equal?

Returns t if the arguments are structually equal; otherwise returns nil.

> (equal? 1 1)
;=> t
> (equal? 1 2)
;=> nil
> (equal? "foo" 'foo)
;=> nil
> (equal? (cons 1 2) (cons 1 2))
;=> t
> (let ((pair (cons 1 2)))
    (equal? pair pair))
;=> t

Function: eqv?

Returns t if the arguments are the same; otherwise returns nil.

> (eqv? 1 1)
;=> t
> (eqv? 1 2)
;=> nil
> (eqv? "foo" 'foo)
;=> nil
> (eqv? (cons 1 2) (cons 1 2))
;=> nil
> (let ((pair (cons 1 2)))
    (eqv? pair pair))
;=> t

Function: num?

Returns t if an argument is a num; otherwise returns nil.

> (num? 3)
;=> t
> (num? "foo")
;=> nil

Function: text?

Returns t if an argument is a text; otherwise returns nil.

> (text? "foo")
;=> t
> (text? 'bar)
;=> nil

Function: symbol?

Returns t if an argument is a symbol; otherwise returns nil.

> (symbol? 'bar)
;=> t
> (symbol? t)
;=> nil

Function: t?

Returns t if an argument is t; otherwise returns nil.

> (t? t)
;=> t
> (t? nil)
;=> nil

Function: nil?

Returns t if an argument is nil; otherwise returns nil.

> (nil? nil)
;=> t
> (nil? (cons 1 2))
;=> nil

Function: cons?

Returns t if an argument is a cons-cell; otherwise returns nil.

> (cons? (cons 1 2))
;=> t
> (cons? 3)
;=> nil

Function: +

Adds arguments.

> (+)
;=> 0
> (+ 1)
;=> 1
> (+ 1 2 3)
;=> 6

Function: -

Subtracts arguments.

> (- 3)
;=> -3
> (- 3 2)
;=> 1
> (- 3 2 1)
;=> 0

Function: *

Multiplies arguments.

> (*)
;=> 1
> (* 3)
;=> 3
> (* 3 4 -5)
;=> -64

Function: /

Divides arguments.

> (/ 3)
;=> .33333333333333333333
> (/ 9 3)
;=> 3
> (/ 9 3 3)
;=> 1
> (/ 9 0)
Error: zero_division: division by zero
at native function <div_impl__959_v0>

Function: %

Returns the remainder of a division.

> (% 7 3)
1
> (% -7 3)
-2
> (% 7 0)
Error: zero_division: division by zero
at native function <mod_impl__959_v0>

Function: list

Makes a list.

> (list)
;=> nil
> (list 1 2 3)
;=> (1 2 3)

Function: map

Applies a function to each element of a list.

> (defun double (x) (* x 2))
> (map double nil)
;=> nil
> (map double (list 1 2 3))
;=> (2 4 6)

Function: iota

Returns a sequence of numbers.

> (iota 3)
;=> (0 1 2)
> (iota 1 5)
;=> (1 2 3 4)
> (iota 0)
;=> nil

Function: error

Raises a user error.

> (error "wrong argument!")
Error: user_error: wrong argument!
at native function <error_impl__677_v0>
> (error "my_error" "something is wrong") ; custom error code
Error: my_error: something is wrong
at native function <error_impl__677_v0>

Special form: catch

Catches an error.

> (catch ("zero_division"
           (echo "Do not divide by zero!")
           'fail)
    (echo (object->text (/ 10 0)))
    'ok)
Do not divide by zero!
;=> fail
> (catch ("some_error" 'handled)
    (error "another_error" "This error will not be caught"))
Error: another_error: This error will not be caught
at native function <error_impl__677_v0>

Function: echo

Prints arguments.

> (echo "Hello")
Hello
;=> nil
> (echo "Hello" "world")
Hello
world
;=> nil

Function: object->text

Converts an object into a text.

> (object->text 123)
;=> "123"
> (object->text '(1 a t nil))
;=> "(1 a t nil)"

Special form: eval

Evaluates an expression.

> (eval '(+ 1 2))
;=> 3
> (let ((a 1) (b 2)) (eval '(cons a b)))
;=> (1 . 2)

Function: exit

Exits the interpreter.

> (exit)
;=> interpreter exits

Special form: help

Shows this help.

> (help)
## Function: `+`
Adds arguments.
...
## Function: `-`
Subtracts arguments.
...
;=> nil