From 896ed567fd0e72036059d332de01520679b8fc51 Mon Sep 17 00:00:00 2001
From: Ava Hahn <ava@aidanis.online>
Date: Wed, 8 Mar 2023 12:02:20 -0800
Subject: [PATCH] add documentation for let and while forms

---
 Readme.org     | 43 +++++++++++++++++++++++++++++++++----
 src/stl/str.rs | 57 --------------------------------------------------
 2 files changed, 39 insertions(+), 61 deletions(-)
 delete mode 100644 src/stl/str.rs

diff --git a/Readme.org b/Readme.org
index 539241a..b394019 100644
--- a/Readme.org
+++ b/Readme.org
@@ -69,9 +69,38 @@ Function calls are executed as soon as the tree is evaluated. See the following
 
 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
+*** Control flow
+**** if
+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.
+If the condition evaluates to neither true nor false (a non-boolean value) a type error is returned.
+
+#+BEGIN_SRC lisp
+  ;; simple condition
+  (if true
+      (echo "its true!")
+      (echo "its false!"))
+
+  ;; more advanced condition, with hypothetical data
+  (if (get-my-flag global-state)
+      (echo "my flag is already on!")
+      (turn-on-my-flag global-state))
+#+END_SRC
+
+**** while
+Another popular control flow structure is the *while loop*.
+This is implemented as a condition followed by one or more bodies that are lazily evaluated only if the condition is true.
+Like the *if form*, if the conditional returns a non-boolean value the *while loop* will return an error.
+
+#+BEGIN_SRC lisp
+  (while (get-my-flag global-state) ;; if false, returns (nothing) immediately
+    (dothing) ;; this is evaluated
+    "simple token" ;; this is also evaluated
+    (toggle-my-flag global-state)) ;; this is also evaluated
+#+END_SRC
+
 **** TODO let
 **** TODO circuit
 *** TODO quote and eval
@@ -166,7 +195,13 @@ Errors during configuration are non-terminal. In such a case any defaults which
 - CFG_RELISH_PROMPT (default (echo "λ ")): A *function* definition which is called in order to output the prompt for each loop of the REPL.
   This function will be reloaded each REPL loop and will be called by the interpreter with no arguments.
 
-** TODO Further configuration
+*** Further configuration
+Further configuration can be done by loading scripts that contain more functions and data to evaluate.
+Variables and functions defined in an external script loaded by your interpreter will persist in the symbol table.
+
+#+BEGIN_SRC lisp
+  (load "my-extra-library-functions.rls")
+#+END_SRC
 
 ** Compilation 
 #+BEGIN_SRC sh
diff --git a/src/stl/str.rs b/src/stl/str.rs
deleted file mode 100644
index ac926b0..0000000
--- a/src/stl/str.rs
+++ /dev/null
@@ -1,57 +0,0 @@
-/* relish: versatile lisp shell
- * Copyright (C) 2021 Aidan Hahn
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
-use crate::sym::SymTable;
-use crate::segment::{Seg, Ctr};
-
-
-pub const ECHO_DOCSTRING: &str =
-    "traverses any number of arguments. Prints their evaluated values on a new line for each.";
-
-pub fn echo_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
-    if ast.len() == 1 {
-        println!("{}", ast.car);
-    } else {
-        ast.circuit(&mut |arg: &Ctr| print!("{}", arg) == ());
-    }
-
-    Ok(Ctr::None)
-}
-
-pub const CONCAT_DOCSTRING: &str = "Iterates over N args of any type other than SYMBOL.
-converts each argument to a string. Combines all strings.
-Returns final (combined) string.";
-
-pub fn concat_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
-    let mut string = String::from("");
-    if !ast.circuit(&mut |arg: &Ctr| {
-        match arg {
-            // should be a thing here
-            Ctr::Symbol(_) => return false,
-            Ctr::String(s) => string.push_str(&s),
-            Ctr::Integer(i) => string.push_str(&i.to_string()),
-            Ctr::Float(f) => string.push_str(&f.to_string()),
-            Ctr::Bool(b) => string.push_str(&b.to_string()),
-            Ctr::Seg(c) => string.push_str(ast_as_string(c.clone(), true).as_str()),
-            Ctr::None => (),
-        }
-        return true;
-    }) {
-        eprintln!("dont know what to do witha symbol here")
-    }
-    return Ctr::String(string);
-}