diff --git a/Readme.org b/Readme.org index 71d24ba..4472a00 100644 --- a/Readme.org +++ b/Readme.org @@ -71,7 +71,7 @@ In this example, ~(add 5 2)~ is evaluated first, its result is then passed to ~( *** Control flow **** if -An if form is the most basic form of conditional evaluation offered by Relish. +An *if form* is the most basic form of conditional evaluation offered by Relish. It is a function that takes lazily evaluated arguments: a condition, a then clause, and an else clause. If the condition evaluates to true, the then clause is evaluated and the result returned. Otherwise the else clause is evaluated and the result is returned. @@ -101,7 +101,27 @@ Like the *if form*, if the conditional returns a non-boolean value the *while lo (toggle-my-flag global-state)) ;; this is also evaluated #+END_SRC -**** TODO let +**** let +*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. + **** TODO circuit **** not quite control flow Several other functions use lazy evaluation of their arguments. The below list is non-exhaustive: