Add Home

Home.md

@@ -0,0 +1,76 @@
+# Welcome!
+
+This wiki page describes the current state of the language interpreted by this program. Some things on this page are still subject to change, beware.
+
+Note: in the implementation, I differentiate between built-in _functions_, built-in _operators_, and _the standard library_.
+This is, as it stands currently, mostly meaningless from the perspective of user code, and is purely an implementation detail. 
+In practice you may treat the language as if all of the following are true:
+
+- Your code is executed in a freshly constructed "default" global environment containing all of the definitions on this page.
+- You may redefine, set, or otherwise modify your global environment as you see fit. The language currently
+has no protection or namespace mechanism.
+
+## Math
+
+Generally, numbers can be treated as uniform.
+
+Numbers written as integers (e.g. `1`, `-3`) are assumed to be integers, and they will be held in an integer value.
+Numbers written as floating point numbers (e.g. `1.0`, `-2.3`) are assumed to be doubles, and they will be held in a double value.
+Arithmetic between integers (except for division) always produces an integer value. 
+Arithmetic involving a double always produces a double.
+Division always produces a double.
+
+There is currently no way to differentiate between doubles and integers. This functionality may be added later,
+possibly when a more thought-out type system is added to the language.
+
+- [x] addition (+), subtraction (-)
+- [ ] multiplication (*), division (/), dividend (dividend), remainder (remainder)
+
+## List utilities
+
+- (cons 1 (cons 2 ())) -> (1 2) 
+
+cons produces a new cons cell (essentially a pair of two values). Cons cells (or pairs) form the basis of linked lists,
+and therefore all source code.
+
+- (car '(1 2 3 4)) -> 1
+
+car returns the first item of a cons cell.
+
+- (cdr '(1 2 3 4)) -> (2 3 4)
+
+cdr returns the second item of a cons cell.
+
+- (list 1 2 3 4) -> (1 2 3 4)
+
+list is a function takes any number of parameters, and produces a list containing only those elements in the order passed to it. 
+
+## Definition
+
+- set
+
+sets a symbol's bound value. 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.
+