update top level readme

Readme.md

@@ -4,6 +4,51 @@ Syntactically Homogeneous Shell
 ## Overview
 This shell was created to have extremely simple syntax. S-Expressions were chosen to represent statements and the scope of language features were constrained to what could be considered practical for daily shell use. This program is meant to be practical for administrators and daily power users.
 
+## Basic Syntax
+When in doubt the `print_ast` utility can be used to examine the output of the Lex+Parse process. Here you can spot any bugs regarding syntax.
+
+### Lists
+Any sequence of items within a set of parenthesis is a list
+`(1 "two" three 4)`
+
+Lists can be infinitely nested
+`("one" (2 3 4 (5)))`
+
+### Data types
+We use the following data types
+* Number: 1, 2.0, etc
+* String: "this is a string" (string delimiters: ' " \`)
+* Bool: T or F
+* Symbol: a string with no delimiters
+* List: a sequence of elements within parenthesis
+
+### Function calls
+Any list beginning in a symbol will be considered a function call.
+From within the `shs_repl` utility, unknown symbols will be assumed to be system binaries.
+
+`(append () 1 2 3)`
+`(vim Readme.md)`
+`(if (eq "example" (fread 'test_file')) (print "test worked) (rm -rf /))`
+
+### Variable declaration
+There are a few ways to export variables
+* export: `(export NAME (value))`
+* let: `(let ((var1 val1) (var2 val2)) (form_to_be_evaluated))`
+
+Currently, let has yet to be implemented
+
+### Function declaration
+Use the `func` function from the stdlib:
+`(func name (var1, var2, var3) (form_to_be_evaluated))` 
+In this case, `(form_to_be_evaluated)` will not be evaluated until the function is called.
+
+### Control flow
+See `stdlib/control_flow.go`. We have if and while forms:
+`(if (cond) (then) (else))`
+`(when (cond) (form1)....... (formN))`
+
+We also have functioning implementations of map and reduce in the stdlib
+
 ## How to build
 ### Compiling/Installation
 - For now simply run `go install cmd/...` for each utility you wish to use. If you have GOPATH and GOBIN set it should be usable from PATH
@@ -13,6 +58,14 @@ This shell was created to have extremely simple syntax. S-Expressions were chose
 - Make sure the GPLv3 is adhered to
 - *OVERRIDE THE STDLIB GenFuncTable FUNCTION.* You very likely do NOT want an available function to call system binaries in your embedded shell. Make sure the stdlib Call function is not included.
 
+## Configuration
+* one can write arbitrary shs script into `.shsrc` including function and variable declarations
+* of note are the following variables
+    - `SH_LOGGING` Sets the log level (from 0 to 3)
+    - `SHS_SH_PROMPT` Sets the prompt
+    - `SH_HIST_FILE` Sets the history file
+    - `SH_DEBUG_MODE` Adds additional debug output for the lexer
+
 ## Contributing
 - Any contribution to this software is welcome as long as it adheres to the conduct guidelines specified in the `Contributing.md` file in this repository.
 - Consider reading the [STDLIB Readme](https://git.callpipe.com/aidan/shs/-/blob/master/stdlib/Readme.md) for more information on how to extend this project.