Add Definition

Definition.md

@@ -0,0 +1,57 @@
+# Definition
+
+Operators and functions that add, remove or modify definitions. Other utilities for modifying environments may be included.
+
+- set
+
+builtin: (set _symbol_ _value_)
+
+sets a symbol's bound value.  set, being a built-in function, takes a symbol value as its first parameter,
+meaning that in practice you will need to quote the symbol first. See setq.
+set always finds the most local definition. For example, the following evaluates to 5:
+
+```
+(def myvar 4)
+(defn myfunction (myvar)
+  (set 'myvar 5)
+  myvar)
+(myfunction 4)
+```
+
+And the global `myvar` will still equal 4 after this. However, set _can_ potentially modify global definitions when
+the "most local" definition for the given symbol belongs to the global environment. `myvar` would actually
+be modified in the following example:
+
+```
+(def myvar 4)
+(defn myfunction ()
+  (set 'myvar 5)
+  myvar)
+(myfunction)
+```
+
+This returns 5, and `myvar` will evaluate to 5 afterwards.
+Using set for a symbol that doesn't have a binding in the current environment is an error.
+
+- setq
+
+macro: (setq _symbol_ _value_)
+
+Same as set, except setq automatically quotes its first parameter.
+
+`(setq x 5)` is equivalent to `(set 'x 5)`.
+
+- def
+
+builtin: (def _sym_ _val_)
+
+def creates a new global definition. No quoting is necessary. If the definition already exists in the global environment, it is replaced with the new one -
+the old one is no longer accessible.
+
+The following evaluates to 5:
+
+```
+(def x 5)
+x
+```
+