Relish fits within the LISP family of languages alongside venerable languages like Scheme or Common Lisp.
Lisps are *HOMOICONIC* which means that the code is data, and that there is a direct correlation between the code as written and the program as stored in memory.
This is achieved through *S-EXPRESSIONS*. An S-Expression (or symbolic expression) is a tree of nested lists.
Programs in Relish (and most other lisps) are written with S-Expressions, and are then represented in memory as trees of nested linked lists.
S-Expressions can represent function calls in addition to trees of data. A function call is a list of data starting with a symbol that is defined to be a function:
#+BEGIN_SRC lisp
(dothing arg1 arg2 arg3)
#+END_SRC
Function calls are executed as soon as the tree is evaluated. See the following example:
#+BEGIN_SRC lisp
(add 3 (add 5 2))
#+END_SRC
In this example, ~(add 5 2)~ is evaluated first, its result is then passed to ~(add 3 ...)~. In infix form: ~3 + (5 + 2)~.
*Let* is one of the most powerful forms Relish offers. The first body in a call to let is a list of lists.
Specifically, a list of variable declarations that lookf like this: ~(name value)~.
Each successive variable definition can build off of the last one, like this: ~((step1 "hello") (step2 (concat step1 " ")) (step3 (concat step2 "world")))~.
In said example, the resulting value of step3 is "hello world". After the variable declaration list, the next for is one or more unevaluated trees of code to be evaluated.
Here is an example of a complete let statement using hypothetical data and methods:
#+BEGIN_SRC lisp
;; Example let statement accepts one incoming connection on a socket and sends one response
(let ((conn (accept-conn listen-socket)) ;; start the var decl list, decl first var
(hello-pfx "hello from ") ;; start the var decl list, declare second var
(hello-msg (concat hello-pfx (get-server-name))) ;; declare third var from the second var
(hello-response (make-http-response 200 hello-msg))) ;; declare fourth var from the third, end list
(log (concat "response to " (get-dst conn) ": " hello-msg)) ;; evaluates a function call using data from the first and third vars
(send-response conn hello-response)) ;; evaluates a function call using data from the first and fourth vars
#+END_SRC
Here you can see the usefulness of being able to declare multiple variables in quick succession.
Each variable is in scope for the duration of the let statement and then dropped when the statement has concluded.
Thus, it is little cost to break complex calculations down into reusable parts.
As stated previously: Lisp, and consequently Relish, is homoiconic. This means that code can be passed around (and modified) as data.
This allows us to write self programming programs, or construct entire procedures on the fly. The primary means to do so are with *quote* and *eval*.
The *quote* function allows data (code) to be passed around without evaluating it. It is used to pass unevaluated code around as data that can then be evaluated later.
To be specific, typing ~(a)~ usually results in a symbol lookup for ~a~, and then possibly even a function call. However, if we *quote*~a~, we can pass around the symbol itself:
#+BEGIN_SRC lisp
(quote a) ;; returns the symbol a
(quote (add 1 2)) ;; returns the following tree: (add 1 2)
#+END_SRC
We can use this to build structures that evaluate into new data:
#+BEGIN_SRC lisp
(let ((mylist (quote (add))) ;; store a list starting with the add function
(myiter 0)) ;; store an iterator starting at 0
(while (lt? myiter 4) ;; loop until the iterator >= 4
(inc myiter) ;; increment the iterator
(def mylist '' (cons mylist myiter)) ;; add to the list
(echo mylist)) ;; print the current state of the list
(echo (eval mylist))) ;; print the eval result
#+END_SRC
Notice the final body in the let form: ~(echo (eval mylist))~
In Relish, both variables and functions are stored in a table of symbols.
All Symbols defined with ~def~ are *GLOBAL*. The only cases when symbols are local is when they are defined as part of *let* forms or as arguments to functions.
In order to define a symbol, the following arguments are required:
- A name
- A docstring (absolutely required)
- A list of arguments (only needed to define a function)
- A value
Regarding the *value*: A function may be defined with several trees of code to execute.
In this case, the value derived from the final form in the function will be returned.
#+BEGIN_SRC lisp
(def my-iter 'an iterator to use in my while loop' 0) ;; a variable
(def plus-one 'adds 1 to a number' (x) (add 1 x)) ;; a function
(def multi-func 'example of multi form function'
(x y) ;; args
(inc my-iter) ;; an intermediate calculation
(add x y my-iter)) ;; the final form of the function. X+Y+MYITER is returned
#+END_SRC
Make sure to read the *Configuration* section for information on how symbols are linked to environment variables.
**** Naming conventions
- Symbol names are case sensitive
- Symbols may contain alphanumeric characters
- Symbols may contain one or more of the following: - _ ?
- The idiomatic way to name symbols is ~all-single-case-and-hyphenated~
**** Undefining variables and functions
Removing a symbol consists of a call to ~def~ with no additional arguments:
#+BEGIN_SRC lisp
(def my-iter 'an iterator' 0)
(inc my-iter) ;; my-iter = 1
(def my-iter) ;; removes my-iter
(inc my-iter) ;; UNDEFINED SYMBOL ERROR
#+END_SRC
** Builtin functions
As opposed to listing every builtin function here, it is suggested to the user to do one of two things:
- Call ~env~ from a fresh shell: ~(env)~
This will output all variables and functions defined
- Read the std library declaration code:
file:src/stl.rs
** Documentation
*** Tests
Most of the tests evaluate small scripts (single forms) and check their output.
Perusing them may yield answers on all the cases a given builtin can handle.
file:tests/
*** Help function
Relish is self documenting. The *help* function can be used to inspect any variable or function.
It will show the name, current value, docstring, arguments, and definition of any builtin or user defined function or variable.
#+BEGIN_EXAMPLE
> (help my-adder)
NAME: my-adder
ARGS: 2 args of any type
DOCUMENTATION:
adds two numbers
CURRENT VALUE AND/OR BODY:
args: x y
form: ((add x y))
#+END_EXAMPLE
#+BEGIN_EXAMPLE
> (help CFG_RELISH_ENV) <
NAME: CFG_RELISH_ENV
ARGS: (its a variable)
DOCUMENTATION:
my env settings
CURRENT VALUE AND/OR BODY:
true
#+END_EXAMPLE
Every single symbol in Relish can be inspected in this way, unless some third party developer purposefully left a docstring blank.
*** Snippets directory
The *snippets directory* may also yield some interesting examples.
Within it are several examples that the authors and maintainers wanted to keep around but didnt know where.
It is sort of like a lint roller.
It also contains considerably subpar implementations of Relish's internals that are kept around for historical reasons.
This section can serve as a sort of cookbook for a user who is new to leveraging LISP languages or unsure of where to start with ~relish~.
More ideas may be explored in the file:snippets directory of this project.
The author encourages any users to contribute their own personal favorites not already in this section either by adding them to the file:snippets folder, or to extend the documentation here.
*** while-let combo
#+BEGIN_SRC lisp
;; myiter = (1 (2 3 4 5 6))
(def myiter 'iterator over a list' (head (1 2 3 4 5 6)))
;; iterate over each element in mylist
(while (gt? (len (cdr myiter)) 0) ;; while there are more elements to consume
(let ((elem (car myiter)) ;; elem = consumed element from myiter
(remaining (cdr myiter))) ;; remaining = rest of elements
(echo elem) ;; do a thing with the element, could be any operation
(def myiter (head remaining)))) ;; consume next element, loop
#+END_SRC
The while-let pattern can be used for many purposes. Above it is used to iterate over elements in a list. It can also be used to receive connections to a socket and write data to them.
~let~ is very useful for destructuring complex return types. If you have a function that may return a whole list of values you can then call it from ~let~ to consume the result data.
In this example a let form is used to destructure a call to ~head~. ~head~ returns a list consisting of ~(first-element rest-of-list)~ (for more information see ~(help head)~).
The ~let~ form starts with the output of ~head~ stored in ~head-struct~ (short for head-structured). The next variables defined are ~first~ and ~rest~ which contain individual elements from the return of the call to ~head~.
Finally, the bodies evaluated in the ~let~ form are able to operate on the head and the rest.
#+BEGIN_SRC lisp
;; individually access the top of a list
(let ((head-struct (head (1 2 3))
(first (car head-struct))
(rest (cdr head-struct)))
(echo "this is 1: " first)
(echo "this is 2, 3: " rest))
#+END_SRC
*** if-set?
One common pattern seen in bash scripts and makefiles is the set-variable-if-not-set pattern.
#+BEGIN_SRC shell
MYVAR ?= MY_SPECIAL_VALUE
#+END_SRC
Translated, can be seen below
#+BEGIN_SRC lisp
(if (set? myvar)
() ;; no need to do anything... or add a call here
(def myvar "MY_SPECIAL_VALUE"))
#+END_SRC
Alternatively this combination can be used to process flags in a script or application:
By default Relish will read from ~/.relishrc for configuration, but the default shell will also accept a filename from the RELISH_CFG_FILE environment variable.
On start, any shell which leverages the configuration code in the config module (file:src/config.rs) will create a clean seperate context, including default configuration values, within which the standard library will be initialized.
The configuration file is evaluated and run as a standalone script and may include arbitrary executable code. Afterwards, configuration values found in the variable map will be used to configure the standard library function mappings that the shell will use.
- Variables and functions defined during configuration will carry over to the user/script interpreter, allowing the user to load any number of custom functions and variables.
You may choose to override these functions if you would like to include your own special functions in your own special interpreter, or if you would like to pare down the stdlib to a small minimal subet of what it is.
You can view the code for standard library functions in file:src/stl/.
