Squashed 'lispBM/lispBM/' changes from d2f9c684..4a176b04

4a176b04 update lbmref
5590c91b update doc
feda99fe resolve mistake
36c79cc6 resolve mistake
2145c388 expanding explanation of symbols in manual
a3140ff1 small tweak to doc removing mention of #var, maybe a section about valid symbol names should be added

git-subtree-dir: lispBM/lispBM
git-subtree-split: 4a176b04c18f183d19b1bb044a9cba9b7b8c419a

doc/lbmref.md

@@ -28,15 +28,14 @@ all integer comparisons.
 
 You associate values with symbols using, <a href="#define">define</a>,
 <a href="#let">let</a> and you can change the value bound to a "variable"
-using <a href="#setvar">setvar</a>
+using <a href="#set">set</a>, <a href="#setvar">setq</a> or <a href="#setvar">setvar</a>.
 
 Not all symbols are treated the same in LBM. Some symbols are treated as
 special because of their very fundamental nature. Among these special symbols
 you find `define`, `let` and `lambda` for example. These are things that you
 should not be able to redefine and trying to redefine them leads to an error.
-There are two classes of symbols that are special by naming convention and
-these either start with a `#`, for fast-lookup variables, and `ext-` for
-extensions that will be bound at runtime.
+Symbols that start with `ext-` are special and reserved for use together
+with extensions that are loaded and bound at runtime.
 
 Examples of symbols used as data are `nil` and `t`. `nil` is used the
 represent nothing, the empty list or other similar things and `t`
@@ -44,6 +43,25 @@ represents true.  But any symbol can be used as data by quoting it
 `'`, see <a href="#quotes-and-quasiquotation"> Quotes and
 Quasiquotation </a>.
 
+### Valid symbol names
+
+A symbol is string of characters following the rules:
+1. The first character is a one of 'a' - 'z' or 'A' - 'Z' or '+-*/=<>#!'.
+2. The rest of the characters are in 'a' - 'z' or 'A' - 'Z' or '0' - '9' or '+-*/=<>!?_'.
+3. At most 256 characters long.
+
+Note that lower-case and upper-case alphabetical letters are considers identical
+so the symbol `apa` is the same symbol as `APA`.
+
+examples of valid symbols
+```
+apa
+apa?
+!apa
+kurt_russel_is_great
+```
+
+
 
 ## Arithmetic
 
@@ -400,7 +418,7 @@ explicit true makes sense.
 ## Quotes and Quasiquotation
 
 Code and data share the same representation, it is only a matter of how
-you look at it. The tools for changing how your view are the quotation and
+you look at it. The tools for changing view, or interpretation,  are the quotation and
 quasiquotation operations.
 
 ---
@@ -738,9 +756,9 @@ Example
 ### setvar
 
 The `setvar` form is used to change the value of some variable in an environment.
-You can use `setvar` to change the value of a global definition, a local definition
-or a variable defintion (`#var`). An application of the `setvar` form looks like
-`(setvar var-expr val-expr)` where `var-expr` should evaluate to a symbol. The `val-expr` is evaluated before
+You can use `setvar` to change the value of a global definition or a local definition.
+An application of the `setvar` form looks like `(setvar var-expr val-expr)` where
+`var-expr` should evaluate to a symbol. The `val-expr` is evaluated before
 rebinding the variable. `setvar` returns the value that `val-expr` evaluates to.
 
 Examples:
@@ -761,15 +779,6 @@ You can also set the value of a let bound variable.
 (let ((a 10)) (setvar 'a 20))
 ```
 
-And you can change the value of a `#var`.
-
-```clj
-(define #a 10)
-
-(setvar '#a 20)
-```
-`#a` is now 20.
-
 ---
 
 ### set

src/eval_cps.c

@@ -2055,7 +2055,6 @@ static void cont_wait(eval_context_t *ctx) {
 static lbm_value perform_setvar(lbm_value key, lbm_value val, lbm_value env) {
 
   lbm_uint s = lbm_dec_sym(key);
-  lbm_value res = val;
   if (s >= RUNTIME_SYMBOLS_START) {
     lbm_value new_env = lbm_env_modify_binding(env, key, val);
     if (lbm_is_symbol(new_env) && new_env == ENC_SYM_NOT_FOUND) {
@@ -2068,8 +2067,10 @@ static lbm_value perform_setvar(lbm_value key, lbm_value val, lbm_value env) {
       lbm_set_error_reason((char*)lbm_error_str_variable_not_bound);
       error_at_ctx(ENC_SYM_NOT_FOUND, key);
     }
+    return val;
   }
-  return res;
+  error_at_ctx(ENC_SYM_EERROR, ENC_SYM_SETVAR);
+  return ENC_SYM_NIL; // unreachable
 }
 
 static void apply_setvar(lbm_value *args, lbm_uint nargs, eval_context_t *ctx) {