Add documentation and doc strings

docs/contrib/anaphoirc.rst

@@ -0,0 +1,96 @@
+====================
+Anaphoric Macros
+====================
+
+The anaphoric macros module makes functional programming in Hy very
+concise and easy to read.
+
+    An anaphoric macro is a type of programming macro that
+    deliberately captures some form supplied to the macro which may be
+    referred to by an anaphor (an expression referring to another).
+
+    -- Wikipedia (http://en.wikipedia.org/wiki/Anaphoric_macro)
+
+Macros
+======
+
+.. _ap-each:
+
+ap-each
+-------
+
+Usage: ``(ap-each [1 2 3 4 5] (print it))``
+
+Evaluate the form for each element in the list for side-effects.
+
+
+.. _ap-each-while:
+
+ap-each-while
+=============
+
+Usage: ``(ap-each-while list pred body)``
+
+Evaluate the form for each element where the predicate form returns
+True.
+
+.. code-block:: clojure
+
+   => (ap-each-while [1 2 3 4 5 6] (< it 4) (print it))
+   1
+   2
+   3
+
+.. _ap-map:
+
+ap-map
+======
+
+Usage: ``(ap-map form list)``
+
+The anaphoric form of map works just like regular map except that
+instead of a function object it takes a Hy form. The special name,
+``it`` is bound to the current object from the list in the iteration.
+
+.. code-block:: clojure
+
+    => (list (ap-map (* it 2) [1 2 3]))
+    [2, 4, 6]
+
+
+.. _ap-map-when:
+
+ap-map-when
+===========
+
+Usage: ``(ap-map-when predfn rep list)``
+
+Evaluate a mapping over the list using a predicate function to
+determin when to apply the form.
+
+.. code-block:: clojure
+
+    => (list (ap-map-when odd? (* it 2) [1 2 3 4]))
+    [2, 2, 6, 4]
+
+    => (list (ap-map-when even? (* it 2) [1 2 3 4]))
+    [1, 4, 3, 8]
+
+
+.. _ap-filter:
+
+ap-filter
+=========
+
+Usage: ``(ap-filter form list)``
+
+As with ``ap-map`` we take a special form instead of a function to
+filter the elements of the list. The special name ``it`` is bound to
+the current element in the iteration.
+
+.. code-block:: clojure
+
+    => (list (ap-filter (> (* it 2) 6) [1 2 3 4 5]))
+    [4, 5]
+
+

docs/contrib/index.rst

@@ -0,0 +1,10 @@
+
+Contrib Modules Index
+=====================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   anaphoric

docs/index.rst

@@ -49,3 +49,4 @@ Contents:
    tutorial
    hacking
    language/index
+   contrib/index

hy/contrib/anaphoric.hy

@@ -24,11 +24,14 @@
 
 
 (defmacro ap-each [lst &rest body]
+  "Evaluate the body form for each element in the list."
   `(foreach [it ~list] ~@body))
 
 
-(defmacro ap-each-while [lst pred &rest body]
+(defmacro ap-each-while [lst form &rest body]
-  `(let [[p (lambda [it] ~pred)]]
+  "Evalutate the body form for each element in the list while the
+  predicate form evaluates to True."
+  `(let [[p (lambda [it] ~form)]]
      (foreach [it ~lst]
        (if (p it)
          ~@body
@@ -36,12 +39,15 @@
 
 
 (defmacro ap-map [form lst]
+  "Yield elements evaluated in the form for each element in the list."
   `(let [[f (lambda [it] ~form)]]
      (foreach [v ~lst]
        (yield (f v)))))
 
 
 (defmacro ap-map-when [predfn rep lst]
+  "Yield elements evaluated for each element in the list when the
+  predicate function returns True."
   `(let [[f (lambda [it] ~rep)]]
      (foreach [it ~lst]
        (if (~pred it)
@@ -50,6 +56,7 @@
 
 
 (defmacro ap-filter [form lst]
+  "Yield elements returned when the predicate form evaluates to True."
   `(let [[pred (lambda [it] ~form)]]
      (foreach [val ~lst]
        (if (pred val)