1 files changed, 109 insertions, 0 deletions
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..14e3086
--- /dev/null
+++ b/README.org
@@ -0,0 +1,109 @@
+* lambda-riffs 
+
+ALPHA QUALITY -- USE AT YOUR OWN RISK 
+
+A simple "one file" system that adds a reader macro for quick lambda
+riffing.
+
+** Examples and Use
+
+To use the system, simply load it. It adds a single reader macro to
+you lisp system.
+
+If this system has any actual users, and if those users are
+dissatisfied with the alteration of the global readtable, let me know
+and I can try adapting this for use with named-readtables. 
+
+*** Normal  Use
+
+As normally used, lambda-riffs lets you make quick anonymous
+functions.  There is a special syntax for making variables that start
+with $, for example `$x` or `$my-var` 
+
+Here is a basic example
+
+ #+begin_src lisp :results verbatim
+
+ (let ((xs (list 1 2 3 4 5 6))) 
+   (remove-if-not #$(member $x xs)
+                  (loop repeat 20 collect (random 10))))
+
+ #+end_src
+
+ #+RESULTS:
+ : (3 1 6 1 4 2 4 6 4 3 5 1 5 3)
+
+the =#$= syntax is a reader macro dispatch sequence. An symbol that
+begins with =$= inside a form that begins with =#$= will be treated as
+a parameter of the function being defined.
+
+#+begin_src lisp :results verbatim
+
+(list  (funcall #$(list $x $y) 1 2)
+       (funcall #$(list $x $x $x) 10))
+ 
+#+end_src
+
+#+RESULTS:
+: ((1 2) (10 10 10))
+
+
+*** Numbered Arguments 
+
+Examples of numbered arguments:
+
+- =$1= , =$2= 
+- =$1-with-a-name= , =$2another-name= 
+
+I.e. numbered arguments begin $ and are followed by an integer, and
+then any normal variable name characters.
+
+Their effect is to explicitly specify the order of the parameters
+being defined.  Here is ane example:
+
+#+begin_src lisp :results verbatim
+
+(funcall #$(list $2-symb $1-symb) 'second 'first)
+
+#+end_src
+
+#+RESULTS:
+: (FIRST SECOND)
+
+In the above ='second= is passed in as the first argument, and
+='first= is passed as the second argument.  
+
+Interestingly the numbers do not have to be sequentail, they are
+merely sorted in ascending order:
+
+#+begin_src lisp :results verbatim 
+
+(funcall #$(list $10 $2 $4) :two :four :ten)
+
+#+end_src
+
+#+RESULTS:
+: (:TEN :TWO :FOUR)
+
+*** Nested Forms
+
+You can nest forms by adding an additional $ to the
+dispatch. Variables of nested forms must include the same number of $
+characters as there are in the dispatch form.
+
+This is easer to understand through example:
+
+#+begin_src lisp :results verbatim
+
+;; map over a list of lists, subtracting 9 from any member of a list
+;; that is greater than 9
+
+(mapcar #$(mapcar
+           #$$(if (> $$x 9) (- $$x 9) $$x)  ; our nested form
+           $digit-list)                     
+        '((1 2 3 4 5 6 7 8 9)
+          (10 11 12 12 14 15 16 17 18)))
+#+end_src
+
+#+RESULTS:
+: ((1 2 3 4 5 6 7 8 9) (1 2 3 3 5 6 7 8 9))