250 lines
5.0 KiB
ReStructuredText
250 lines
5.0 KiB
ReStructuredText
================
|
|
Anaphoric Macros
|
|
================
|
|
|
|
.. versionadded:: 0.9.12
|
|
|
|
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)
|
|
|
|
To use these macros you need to require the hy.contrib.anaphoric module like so:
|
|
|
|
``(require hy.contrib.anaphoric)``
|
|
|
|
.. _ap-if:
|
|
|
|
ap-if
|
|
=====
|
|
|
|
Usage: ``(ap-if (foo) (print it))``
|
|
|
|
Evaluates the first form for truthiness, and bind it to ``it`` in both the
|
|
true and false branches.
|
|
|
|
|
|
.. _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:: hy
|
|
|
|
=> (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:: hy
|
|
|
|
=> (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:: hy
|
|
|
|
=> (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:: hy
|
|
|
|
=> (list (ap-filter (> (* it 2) 6) [1 2 3 4 5]))
|
|
[4, 5]
|
|
|
|
|
|
.. _ap-reject:
|
|
|
|
ap-reject
|
|
=========
|
|
|
|
Usage: ``(ap-reject form list)``
|
|
|
|
This function does the opposite of ``ap-filter``, it rejects the
|
|
elements passing the predicate . The special name ``it`` is bound to
|
|
the current element in the iteration.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (ap-reject (> (* it 2) 6) [1 2 3 4 5]))
|
|
[1, 2, 3]
|
|
|
|
|
|
.. _ap-dotimes:
|
|
|
|
ap-dotimes
|
|
==========
|
|
|
|
Usage ``(ap-dotimes n body)``
|
|
|
|
This function evaluates the body *n* times, with the special
|
|
variable ``it`` bound from *0* to *1-n*. It is useful for side-effects.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (setv n [])
|
|
=> (ap-dotimes 3 (.append n it))
|
|
=> n
|
|
[0, 1, 2]
|
|
|
|
|
|
.. _ap-first:
|
|
|
|
ap-first
|
|
========
|
|
|
|
Usage ``(ap-first predfn list)``
|
|
|
|
This function returns the first element that passes the predicate or
|
|
``None``, with the special variable ``it`` bound to the current element in
|
|
iteration.
|
|
|
|
.. code-block:: hy
|
|
|
|
=>(ap-first (> it 5) (range 10))
|
|
6
|
|
|
|
|
|
.. _ap-last:
|
|
|
|
ap-last
|
|
========
|
|
|
|
Usage ``(ap-last predfn list)``
|
|
|
|
This function returns the last element that passes the predicate or
|
|
``None``, with the special variable ``it`` bound to the current element in
|
|
iteration.
|
|
|
|
.. code-block:: hy
|
|
|
|
=>(ap-last (> it 5) (range 10))
|
|
9
|
|
|
|
|
|
.. _ap-reduce:
|
|
|
|
ap-reduce
|
|
=========
|
|
|
|
Usage ``(ap-reduce form list &optional initial-value)``
|
|
|
|
This function returns the result of applying form to the first 2
|
|
elements in the body and applying the result and the 3rd element
|
|
etc. until the list is exhausted. Optionally an initial value can be
|
|
supplied so the function will be applied to initial value and the
|
|
first element instead. This exposes the element being iterated as
|
|
``it`` and the current accumulated value as ``acc``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=>(ap-reduce (+ it acc) (range 10))
|
|
45
|
|
|
|
|
|
.. _ap-pipe:
|
|
|
|
ap-pipe
|
|
=========
|
|
|
|
Usage ``(ap-pipe value form1 form2 ...)``
|
|
|
|
Applies several forms in series to a value from left to right. The special variable ``ìt`` in each form is replaced by the result of the previous form.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (ap-pipe 3 (+ it 1) (/ 5 it))
|
|
1.25
|
|
=> (ap-pipe [4 5 6 7] (list (rest it)) (len it))
|
|
3
|
|
|
|
|
|
.. _ap-compose:
|
|
|
|
ap-compose
|
|
=========
|
|
|
|
Usage ``(ap-compose form1 form2 ...)``
|
|
|
|
Returns a function which applies several forms in series from left to right. The special variable ``ìt`` in each form is replaced by the result of the previous form.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (def op (ap-compose (+ it 1) (* it 3)))
|
|
=> (op 2)
|
|
9
|
|
|
|
.. _xi
|
|
|
|
xi
|
|
==
|
|
|
|
Usage ``(xi body ...)``
|
|
|
|
Returns a function with parameters implicitly determined by the presence in the body of xi parameters. An xi symbol designates the ith parameter (1-based, e.g. x1, x2, x3, etc.), or all remaining parameters for xi itself. This is not a replacement for lambda. The xi forms cannot be nested.
|
|
|
|
This is similar to Clojure's anonymous function literals (``#()``).
|
|
|
|
.. code-block:: hy
|
|
|
|
=> ((xi identity [x1 x5 [x2 x3] xi x4]) 1 2 3 4 5 6 7 8)
|
|
[1, 5, [2, 3,] (6, 7, 8), 4]
|
|
=> (def add-10 (xi + 10 x1))
|
|
=> (add-10 6)
|
|
16
|