Add README

1 files changed, 70 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..4a5004f
--- /dev/null
+++ b/README.org
@@ -0,0 +1,70 @@
+* Flatbind
+
+The =flatbind= system exports a single symbol called =do>=, which is a
+DSL that is a kind of gross mutant of =let*= and
+=alexandria:when-let*=, with some =multiple-value-bind= and
+=with-slots= and =destructuring-bind= mixed in.
+
+
+** Example
+
+#+begin_src lisp
+
+(do>
+  object :when= (get-some-oject)
+  (x y) :slots= object
+  :when (evenp (+ x y))
+  :when (plusp y)
+  (quotient remainder) := (floor (+ x y) y)
+  (newx newy &key message) :match= (calculate-new-x-y quotient remainder)
+  (setf x newx ;; X and Y were bound above like WITH-SLOTS
+        y newy)
+  (print message))
+
+#+end_src
+
+
+
+** Grammar
+#+begin_verse
+FLATBIND:DO>
+  [symbol]
+
+DO> names a macro:
+  Lambda-list: (&BODY TOKENS)
+  Documentation:
+    
+    
+    start           ::= clause* eof
+    clause          ::= (binding-clause | destructuring-clause | with-slots-clause | predicate-binding-clause | predicate-clause | simple-clause)
+    binding-clause  ::= values-bind ':=' token
+    values-bind     ::= token
+    destructuring-clause ::= destructuring-list ':MATCH=' token
+    destructuring-list ::= token
+    with-slots-clause ::= slot-value-list ':SLOTS=' token
+    slot-value-list ::= token
+    predicate-binding-clause ::= token ':WHEN=' token
+    predicate-clause ::= ':WHEN' token
+    simple-clause   ::= token
+    ------------------------------------------
+    ADDITIONAL NOTES:
+    values-bind       Either a symbol or a list suitable for passing to MULTIPLE-VALUE-BIND
+    destructuring-list   An list that might be passed as the first argument to DESTRUCTURING-BIND.
+    slot-value-list   A list that is suitable for passing to with-slots.
+    predicate-binding-clause   Bind variable to form, exit early if form evaluated to nil.
+    ------------------------------------------
+    KEY: 
+    token      Any ole token
+    eof        Explicitly match the end of the input
+    {LANGUAGE} Parse a sublist of tokens with LANGUAGE
+    (A|B|...)  One of the alternavites a b ...
+    PATTERN+   One or more PATTERN
+    PATTERN*   Zero or more PATTERN
+    OPT?       Zero or one of OPT
+  Source file: /home/colin/projects/flatbind/flatbind.lisp
+
+Symbol-plist:
+  ARGOT::GRAMMAR-PROPERTY -> #<ARGOT::GRAMMAR {100B8F0433}>
+#+end_verse
+
+