help function displays values not

Signed-off-by: Ava Hahn <ava@aidanis.online>

src/stl/append.rs

@@ -17,6 +17,9 @@
 use crate::segment::{Ctr, Seg};
 use crate::sym::SymTable;
 
+pub const APPEND_DOCSTRING: &str = "traverses any number of arguments collecting them into a list.
+If the first argument is a list, all other arguments are added sequentially to the end of the list contained in the first argument.";
+
 pub fn append_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
     if let Ctr::Seg(ref s) = *ast.car {
         let mut temp = s.clone();

src/stl/boolean.rs

@@ -17,7 +17,11 @@
 use crate::segment::{Ctr, Seg};
 use crate::sym::{SymTable, ValueType};
 
-pub fn bool_and_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
+pub const AND_DOCSTRING: &str = "traverses a list of N arguments, all of which are expected to be boolean.
+starts with arg1 AND arg2, and then calculates prev_result AND next_arg.
+returns final result.";
+
+pub fn and_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
     let mut type_error = false;
     let result = ast.circuit(&mut |arg: &Ctr| -> bool {
         if let Ctr::Bool(b) = *arg {
@@ -36,7 +40,11 @@ pub fn bool_and_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String>
     }
 }
 
-pub fn bool_or_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
+pub const OR_DOCSTRING: &str = "traverses a list of N arguments, all of which are expected to be boolean.
+starts with arg1 OR arg2, and then calculates prev_result OR next_arg.
+returns final result.";
+
+pub fn or_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
     let mut result = false;
     let correct_types = ast.circuit(&mut |arg: &Ctr| -> bool {
         if let Ctr::Bool(b) = *arg {
@@ -55,7 +63,10 @@ pub fn bool_or_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String>
     }
 }
 
-pub fn bool_not_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
+pub const NOT_DOCSTRING: &str = "takes a single argument (expects a boolean).
+returns false if arg is true or true if arg is false.";
+
+pub fn not_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
     if let Ctr::Bool(b) = *ast.car {
         Ok(Ctr::Bool(!b))
     } else {
@@ -63,14 +74,23 @@ pub fn bool_not_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String>
     }
 }
 
-pub fn bool_iseq_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
+pub const ISEQ_DOCSTRING: &str = "traverses a list of N arguments.
+returns true if all arguments hold the same value.
+NOTE: 1 and 1.0 are the same, but '1' 'one' or one (symbol) aren't";
+
+pub fn iseq_callback(ast: &Seg, _syms: &mut SymTable) -> Result<Ctr, String> {
     let head_ctr_ref = &*ast.car;
     Ok(Ctr::Bool(
         ast.circuit(&mut |arg: &Ctr| -> bool { arg == head_ctr_ref }),
     ))
 }
 
-pub fn bool_toggle_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
+pub const TOGGLE_DOCSTRING: &str = "switches a boolean symbol between true or false.
+Takes a single argument (a symbol). Looks it up in the variable table.
+Either sets the symbol to true if it is currently false, or vice versa.";
+
+
+pub fn toggle_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     let var_name: String;
     if let Ctr::Symbol(ref s) = *ast.car {
         var_name = s.clone();

src/stl/control.rs

@@ -19,6 +19,15 @@ use crate::eval::eval;
 use crate::segment::{Ctr, Seg};
 use crate::sym::{Args, SymTable, Symbol, ValueType};
 
+pub const IF_DOCSTRING: &str = "accepts three bodies, a condition, an unevaluated consequence, and an alternative consequence.
+If the condition is evaluated to true, the first consequence is evaluated.
+If the condition is evaluated to false, the second consequence is evaluated.
+Otherwise, an error is thrown.
+
+example: (if my-state-switch
+           (do-my-thing)
+           (else-an-other-thing))";
+
 pub fn if_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     let cond: bool;
     println!("Y: {}", *ast.car);
@@ -85,6 +94,20 @@ pub fn if_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     }
 }
 
+pub const LET_DOCSTRING: &str =  "creates a stack of local variables for a sequence of operations.
+returns the result of the final operation.
+
+example: (let ((step1 'hello')
+               (step2 (concat step1 '-'))
+               (step3 (concat step2 'world')))
+              (echo step3)
+              (some-func some-args))
+
+In this example step1, step2, and step3 are created sequentially.
+Then, the echo form is evaluated, printing 'hello-world'.
+Finally, the some-func form is evaluated.
+Since the call to some-func is the final form, its value is returned.";
+
 pub fn let_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     let mut localsyms = syms.clone();
     let locals_form: &Seg;
@@ -180,9 +203,14 @@ pub fn let_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     Ok((*result).clone())
 }
 
-/*
-(while (cond) evalme evalme evalme evalme ... )
- */
+pub const WHILE_DOCSTRING: &str = "traverses a list of N un-evaluated forms.
+the first form is expected to evaluate to a boolean. if it evaluates to false, while will stop and return. Otherwise, while will evaluate each form in a loop.
+
+example: (while (check-my-state)
+                (do-thing-1 args)
+                (do-thing-2 args)
+                (edit-state my-state))";
+
 pub fn while_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     let eval_cond: &Seg;
     let outer_maybe: Seg;
@@ -244,9 +272,17 @@ pub fn while_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     Ok(*(result.unwrap()).clone())
 }
 
-/*
-(circuit makes_a_bool makes_a_bool makes_a_bool makes_a_bool ... )
-*/
+pub const CIRCUIT_DOCSTRING: &str = "traverses a list of N un-evaluated forms.
+evaluates each one until it stops. Circuit will stop when a form errors during evaluation.
+Circuit will also stop when a form does not evaluate to a boolean, or evaluates to false.
+
+example: (circuit (eq? (do-operation) myresult)
+                  (and state1 state2 (boolean-operation3))
+                  false
+                  (do-another-operation))
+
+in this example, do-another-operation will not be called";
+
 pub fn circuit_callback(ast: &Seg, syms: &mut SymTable) -> Result<Ctr, String> {
     let mut cursor = 0;
     let mut error: String = String::new();