Re-work program structure, MAIN entrypoint + only PROC definitions

1 files changed, 56 insertions, 42 deletions

diff --git a/README.md b/README.md
index 261168a..e47e1b7 100644
--- a/README.md
+++ b/README.md
@@ -13,14 +13,15 @@ God help you if you want to use this for anything.
 
 ### Procedures
 
-Custom procedures can be created before the main body of the program:
+Code is separated into procedures. A program must define a procedure named `MAIN` to serve as the entrypoint.
 
 ```
 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 '''
+PROC MAIN
+  4 is-even? . '''true'''
+  5 is-even? . '''false'''
+END
 ```
 
 ### Postfix/Reverse Polish notation
@@ -28,24 +29,25 @@ PROC illegal "this is an error" . END ''' not allowed, defined after body progra
 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" ++ .
-
+PROC
+  ''' 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" ++ .
+END
 ```
 
 ### Comments
@@ -53,14 +55,16 @@ Procedures are invoked by pushing its arguments to the stack in reverse order an
 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 .
+PROC MAIN
+  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 .
+END
 ```
 
 ### Control-flow
@@ -68,14 +72,16 @@ END .
 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" .
+PROC MAIN
+  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
 END
 ```
 
@@ -83,15 +89,23 @@ END
 
 Most characters typically thought-of as 'special' have no special syntactic meaning in DSL. Some exceptions include:
 
+* Sequences of characters that would be parsed as data literals
 * 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 '''
+''' these are okay '''
+PROC foo "this proc has a valid name" . END
+PROC +foo- "this proc has a valid name" . END
+PROC +fo8o- "this proc has a valid name" . END
+PROC $(*^$%*&#$%#]} "this proc has a valid name" . END
+
+''' these aren't '''
+PROC true "this is a parser error" . END
+PROC 123 "this is a parser error" . END
+PROC "foo" "this is a parser error" . END
 PROC "foo "this is a parser error" . END
+PROC '''foo''' "this is a parser error" . END
 ```