From acb1e1c1265add52ada2eaf6167ef71143a28b0a Mon Sep 17 00:00:00 2001
From: Ava Hahn <ava@aidanis.online>
Date: Wed, 8 Mar 2023 11:41:00 -0800
Subject: [PATCH] flesh out readme documentation

---
 Readme.org | 79 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 64 insertions(+), 15 deletions(-)

diff --git a/Readme.org b/Readme.org
index 6e1f587..539241a 100644
--- a/Readme.org
+++ b/Readme.org
@@ -24,19 +24,62 @@ https://gitlab.com/whom/shs
 https://matrix.to/#/#vomitorium:matrix.sunnypup.io
 
 * How to use
-** TODO Syntax
-*** TODO Basic data types
-*** TODO S-Expressions
-**** TODO calling a function
+** Syntax
+*** S-Expressions
+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.
+
+An example:
+#+BEGIN_SRC lisp
+  (top-level element1 "element2" 3 (nested 2 5 2) (peer-nested))
+#+END_SRC
+
+As in memory
+#+BEGIN_SRC
+top-level -> element1 -> "element2" -> 3 -> [] -> [] ->
+                                            |     ^-> peer-nested ->
+                                            \-> nested -> 2 -> 5 -> 2 ->
+#+END_SRC
+
+Each node in memory has type information and potentially a cooresponding entry in a global symbol table.
+
+**** data types
+Relish leverages the following data types:
+- Strings: delimited by ~'~, ~"~, or ~`~
+- Integers: up to 128 bit signed integers
+- Floats: all floats are stored as 64 bit floats
+- Booleans: ~true~ or ~false~
+- Symbols: an un-delimited chunk of text containing alphanumerics, ~-~, ~_~, or ~?~
+
+Symbols and Functions are untyped. there is no restriction on what can be set/passed to what.....
+However, internally Relish is statically typed, and many builtin functions will get very picky about what types are passed to them.
+
+**** calling a function
+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)~.
+
 *** TODO Control flow
 **** TODO if
 **** TODO while
 **** TODO let
 **** TODO circuit
+*** TODO quote and eval
 *** TODO Defining variables and functions
 **** TODO Anatomy
 **** TODO Naming conventions
 **** TODO Undefining variables and functions
+
 ** Easy patterns
 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.
@@ -58,6 +101,8 @@ The while-let pattern can be used for many purposes. Above it is used to iterate
 *** TODO main loop application
 - state switch (while-toggle)
 - state calculation
+*** TODO callback model via eval and passed-in functions
+*** TODO quote/eval for pseudo-anonymous pseudo-functions
 *** TODO short-circuit guard
 - circuit example
 - while-not-circuit-do-more-work
@@ -193,7 +238,9 @@ This contains any executable target of this project. Notably the main shell file
 Note: this section will not show the status of each item unless you are viewing it with a proper orgmode viewer.
 Note: this section only tracks the state of incomplete TODO items. Having everything on here would be cluttered.
 
+*** TODO Quote function
 *** TODO Eval function
+*** TODO Lex function
 *** TODO Input function
 *** TODO Load (load a script) function
 Pull/Refactor the logic out of the configure functions.
@@ -201,11 +248,12 @@ Optionally return a list of new variables and/or functions?
 Will need a concatenate function for tables
 *** TODO Main shell calls Load function on arg and exits
 *** TODO Can enter multiple lines of text, with formatting in repl
+*** TODO append -> cons
 *** TODO string operations
-**** TODO typecast (string)
-**** TODO contains
-**** TODO len
-**** TODO concat
+**** DONE typecast (string)
+**** DONE contains
+**** DONE strlen
+**** DONE concat
 **** TODO substr by index
 **** TODO split (on delimiter)
 **** TODO strcons (sprintf but its all string tokens under the hood)
@@ -226,13 +274,14 @@ Will need a concatenate function for tables
 **** TODO queue (append to front)
 **** TODO snippet for dequeue
 **** TODO snippet for pop
-**** TODO front (returns copy of first elem)
-***** TODO normal positive test
-***** TODO test for err case on empty list
-**** TODO back (returns copy of last elem)
-***** TODO normal positive test
-***** TODO test for err case on empty list
-**** TODO list len
+**** TODO sublist by delimiter
+**** DONE front (returns copy of first elem)
+***** DONE normal positive test
+***** DONE test for err case on empty list
+**** DONE back (returns copy of last elem)
+***** DONE normal positive test
+***** DONE test for errcase on empty list
+**** DONE list len
 *** TODO lambda
 *** TODO bool cast
 *** TODO file operations