Some documentation

1 files changed, 92 insertions, 0 deletions

diff --git a/README.md b/README.md
index 10f5ee9..261168a 100644
--- a/README.md
+++ b/README.md
@@ -3,3 +3,95 @@
 This is a tinkering repo for an interpreted stack-based language implemented in Haskell.
 God help you if you want to use this for anything.
 
+## Current features
+
+### Datatypes
+
+* Booleans
+* Arbitrary-prescision integers
+* Strings
+
+### Procedures
+
+Custom procedures can be created before the main body of the program:
+
+```
+PROC is-even? 2 OVER % 0 == END
+
+4 is-even? . '''true'''
+5 is-even? . '''false'''
+PROC illegal "this is an error" . END ''' not allowed, defined after body program body '''
+```
+
+### Postfix/Reverse Polish notation
+
+Procedures are invoked by pushing its arguments to the stack in reverse order and then calling the procedure:
+
+```
+''' compute 2+1 and print the result (3) '''
+1 2 + .
+
+''' compute 2-1 and print the result (1) '''
+1 2 - .
+
+''' compute 1-2 and print the result (-1) '''
+2 1 - .
+
+''' test if 5 is greater than 6 and print the result (false) '''
+6 5 > .
+
+''' compute 2+3, test if 3 is less than the sum, and print the result '''
+3 2 + 3 < .
+
+''' concatenate two strings and print the result '''
+" but backwards" "it's like LISP" ++ .
+
+```
+
+### Comments
+
+Comments are multi-line only and are opened and closed with three single-quotes:
+
+```
+IF 2 9 % 0 == DO
+  ''' TODO: come up with a better message to print
+  maybe something to do with the mod result being 0? '''
+  "true branch"
+ELSE
+  ''' i feel like we could mention that the number is odd? or something? '''
+  "false branch"
+END .
+```
+
+### Control-flow
+
+DSL currently has IF/ELIF/ELSE blocks and WHILE loops:
+
+```
+IF get-some-number 0 == DO
+  "the number is zero" .
+ELIF get-some-number 1 == DO
+  "the number is one" .
+ELIF get-some-number 2 == DO
+  "the number is two" .
+ELSE
+  "this number has yet to be discovered by science" .
+END
+```
+
+### Special characters
+
+Most characters typically thought-of as 'special' have no special syntactic meaning in DSL. Some exceptions include:
+
+* Double-quotes, which start and end string literals
+* Three single-quotes in a row, which start and end comment blocks
+* Other special character sequences already reserved as intrinsic / proc names
+
+```
+''' this is okay '''
+PROC $(*^$%*&#$%# "this is a string that was just printed" . END
+
+''' this isn't '''
+PROC "foo "this is a parser error" . END
+```
+