From f0bfecad710e7f846ad07583b17b0e72e01cd133 Mon Sep 17 00:00:00 2001
From: redxef <redxef@redxef.at>
Date: Tue, 17 Dec 2024 23:06:43 +0100
Subject: [PATCH] docs: document builtin functions available in lisp.

---
 README.md |   2 +
 lisp.md   | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 lisp.md

diff --git a/README.md b/README.md
index 97f722a..950c707 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,8 @@ The configuration page defines some useful functions to make it easier
 to create filters. The above filter for liked items could be simplified
 to: `(is-favourite)`.
 
+*Go [here](lisp.md) to get a overview of the built-in functions.*
+
 ### SortProgram
 
 This works exactly like [Program](#program), but the input is the
diff --git a/lisp.md b/lisp.md
new file mode 100644
index 0000000..30e91a9
--- /dev/null
+++ b/lisp.md
@@ -0,0 +1,114 @@
+# The lisp interpreter
+
+The interpreter is a lisp-like language used to build the filter
+expressions.
+
+## Builtins
+
+**atom**: check if a receive value is a atom. `(atom 1)`
+
+**eq**: check if two values are equal. `(eq (quote a) (quote a))`
+
+**car**: get the first item of the cons.
+
+**cdr**: get the remainder of the list.
+
+**cons**: create a new cons. `(cons 1 2)`
+
+**begin**: evaluate a series of statements, returning the result of the
+last one. `(begin t nil)`
+
+**+-\*/%**: arithmetic operations for integers. `(+ 1 2)`
+
+**=**, **!=**, **<**, **<=**, **>**, **>=**: compare two integers. `(> 1 2)`
+
+**not**: negate the given value. `nil -> t`, everything else will be `nil`. `(not (quote a))`
+
+**string=**, **string!=**, **string<**, **string<=**, **string>**, **string>=**: compare two strings. `(> "1" "2")`
+
+**haskeys**: takes any object and a variadic number of arguments (strings) and
+returns a list with either `t` or `nil` describing if a corresponding property/field/method
+with that name exists on the object. `(haskeys mystring "Length")`
+
+**getitems**: takes any object and a variadic number of arguments
+(strings) and returns the values of the fields/properties. `(getitems mystring "Length" "Chars")`
+
+**invoke**: takes 3 arguments and invokes the method defined on the
+object.
+
+The first argument is the object on which to invoke the method, the
+second one is the name of the method and the third one is a list of
+arguments to pass to the method. `(invoke mystring "Lower" nil)`
+
+**invoke-generic**: the same as **invoke**, but takes a fourth
+argument, a list of string describing the types for the generic method.
+`(invoke-generic mybaseitem "FindParent" nil (list "MediaBrowser.Controller.Entities.Audio.MusicArtist, MediaBrowser.Controller"))`
+
+**random**: gives a random integer. `(random)`
+
+**shuffle**: shuffles a list. `(shuffle (list 1 2 3 4))`
+
+**quote**: quotes a value. `(quote a)`
+
+**eval**: evaluates a expression. `(eval (quote a))`
+
+**cond**: checks conditions and evaluates the corresponding expression.
+```
+(cond
+  (> 1 2) t
+  (t) f)
+```
+
+**if**: a conditional. `(if t 1 2)`
+
+**define**: defines a new symbol. `(define foo 1)`, `(define add (lambda (a b) (+ a b)))`
+
+**let**: define variables in the let context and evaluate the last
+expression. `(let (a 1) (b 2) (+ a b))`
+
+**let\***: the same as **let**, but allows to reference variables
+defined earlier in the let statement. `(let* (a 1) (b (+ 2 a)) (+ a b))`
+
+**apply**: call a function with the specified arguments. `(apply + (list 1 2))`
+
+**and**: evaluate the given expressions in order, if any one of them
+evaluates to `nil` return early with that value, otherwise return the
+last value. `(and 1 2 nil 3)`
+
+**or**: return `nil` if all arguments evaluate to `nil` otherwise the
+first non-nil value.
+
+## Derived builtins
+
+**null**: the same as **not**. Can be useful to indicate semantics of a
+program.
+
+**list**: create a list from the given arguments. `(list 1 2 3)`
+
+**find**: find if an item is in the given list and return it, otherwise
+return `nil`. `(find 4 (list 1 2 3 4 5 6 7))`
+
+**map**: apply a function to every item in the list. `(map (lambda (x) (* 2 x)) (list 1 2 3))`
+
+**fold**: also known as reduce. Apply the function to a sequence of
+values, reducing the sequence to a single item. It takes a initial value
+which is returned for empty lists. `(fold (lambda (a b) (+ a b)) 0 (list 1 2 3 4))`
+
+**any**: equivalent to `(apply or (map function list))`.
+`(any (lambda (a) (% a 2)) (list 2 4 6 7 8))`
+
+**all**: equivalent to `(apply and (map function list))`.
+`(all (lambda (a) (% a 2)) (list 2 4 6 7 8))`
+
+**append**: append an item to the given list. `(append (list 1 2 3) 4)`
+
+**qsort**: quicksort, takes a comparison function and the list.
+`(qsort (lambda (a b) (> a b)) (list 1 2 6 4 9 1 19 0))`
+
+**rand**: get a random integer. Takes either zero, one or two arguments.
+If zero arguments are given it gives a random integer from all possibly
+representable integers. If one argument is given it gives a integer
+between `0` (inclusive) and `n` (exclusive). If two arguments are given
+it gives a integer between `a` (inclusive) and `b` (exclusive).
+
+**shuf**: same as **shuffle**.