add doc.txt

1 files changed, 47 insertions, 0 deletions

diff --git a/doc.txt b/doc.txt
new file mode 100644
index 0000000..a653e5f
--- /dev/null
+++ b/doc.txt
@@ -0,0 +1,47 @@
+# types
+	nil: nil. it's always nil
+	bool: true, false. 
+	num: 1234. -123.56. 64bit floating point number
+	cfunc: pointer to native c function
+	func: badthing function
+	arr: [ 10 20 30 ] array of badthing values
+		array indexing is the same as function calling: (a 1) -> 20
+	string: "hii". 
+		strings are interned: two strings are the same object in memory
+		iff their contents are the same
+
+# variables
+	let, def, fn introduce new locals
+	locals are lexically scoped, and scopes can be nested
+	closures and upvalues will work soon
+	if a local is not found with a given name, the name is instead
+	resolved as a global. this behaviour might change because it's not very good.
+	
+# builtin forms
+	arithmetic: + - * / %     (+ 1 2)
+	equality: (= (+ 2 2) 4)
+	comparison: (< 0 1).  ">" omitted deliberately.
+	let: unremarkable. (let (a 100  b 200) (+ a b))
+	set: mutates values. (set x 10)
+		arrays: (set (a 1) 20) sets index 1 of a
+		setting 1 past the end of an array will append
+	if: (if cond true-expr false-expr)
+	while: (while cond body...)  returns nil
+	do: (do body...)  returns value of last expr in body
+	def: (def foo 123)  creates new local. only allowed at top level of a body
+	fn: (fn (arg0 arg1 arg2) body...)  anonymous. for now.
+	
+# builtin functions
+	(clock): clock(3)
+	(say x): print representation of x, followed by newline
+	(write x): print representation of x, with no newline
+	(arr): create new empty array
+	(append a x): appends to array a
+	(len a): get length of array a
+
+# cmdline args
+	bth [-Dl] [-Dt] filenames...
+		-Dl: print bytecode listing before execution
+		-Dt: trace each executed bytecode instruction
+		filename "-" can be provided to mean stdin.
+