=> (render-html-tag "img" :empty True)
'![]()
'
=> (render-html-tag "img" :id "china" :class "big-image" :empty True)
'![]()
'
=> (render-html-tag "p" " --- " (render-html-tag "span" "" :class "fancy" "I'm fancy!") "I'm to the right of fancy" "I'm alone :(")
' at 0x7f76d0271158>
=> #♣ 5
[5, 5]
=> (setv x 0)
=> #♣(+= x 1)
[None, None]
=> x
2
In this example, if you used ``(defmacro ♣ ...)`` instead of ``(deftag
♣ ...)``, you would call the macro as ``(♣ 5)`` or ``(♣ (+= x 1))``.
The syntax for calling tag macros is similar to that of reader macros a la
Common Lisp's ``SET-MACRO-CHARACTER``. In fact, before Hy 0.13.0, tag macros
were called "reader macros", and defined with ``defreader`` rather than
``deftag``. True reader macros are not (yet) implemented in Hy.
del
---
.. versionadded:: 0.9.12
``del`` removes an object from the current namespace.
.. code-block:: clj
=> (setv foo 42)
=> (del foo)
=> foo
Traceback (most recent call last):
File "", line 1, in
NameError: name 'foo' is not defined
``del`` can also remove objects from mappings, lists, and more.
.. code-block:: clj
=> (setv test (list (range 10)))
=> test
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
=> (del (cut test 2 4)) ;; remove items from 2 to 4 excluded
=> test
[0, 1, 4, 5, 6, 7, 8, 9]
=> (setv dic {"foo" "bar"})
=> dic
{"foo": "bar"}
=> (del (get dic "foo"))
=> dic
{}
doto
----
.. versionadded:: 0.10.1
``doto`` is used to simplify a sequence of method calls to an object.
.. code-block:: clj
=> (doto [] (.append 1) (.append 2) .reverse)
[2, 1]
.. code-block:: clj
=> (setv collection [])
=> (.append collection 1)
=> (.append collection 2)
=> (.reverse collection)
=> collection
[2, 1]
eval-and-compile
----------------
``eval-and-compile`` is a special form that takes any number of forms. The input forms are evaluated as soon as the ``eval-and-compile`` form is compiled, instead of being deferred until run-time. The input forms are also left in the program so they can be executed at run-time as usual. So, if you compile and immediately execute a program (as calling ``hy foo.hy`` does when ``foo.hy`` doesn't have an up-to-date byte-compiled version), ``eval-and-compile`` forms will be evaluated twice.
One possible use of ``eval-and-compile`` is to make a function available both at compile-time (so a macro can call it while expanding) and run-time (so it can be called like any other function)::
(eval-and-compile
(defn add [x y]
(+ x y)))
(defmacro m [x]
(add x 2))
(print (m 3)) ; prints 5
(print (add 3 6)) ; prints 9
Had the ``defn`` not been wrapped in ``eval-and-compile``, ``m`` wouldn't be able to call ``add``, because when the compiler was expanding ``(m 3)``, ``add`` wouldn't exist yet.
eval-when-compile
-----------------
``eval-when-compile`` is like ``eval-and-compile``, but the code isn't executed at run-time. Hence, ``eval-when-compile`` doesn't directly contribute any code to the final program, although it can still change Hy's state while compiling (e.g., by defining a function).
.. code-block:: clj
(eval-when-compile
(defn add [x y]
(+ x y)))
(defmacro m [x]
(add x 2))
(print (m 3)) ; prints 5
(print (add 3 6)) ; raises NameError: name 'add' is not defined
first
-----
``first`` is a function for accessing the first element of a collection.
.. code-block:: clj
=> (first (range 10))
0
It is implemented as ``(next (iter coll) None)``, so it works with any
iterable, and if given an empty iterable, it will return ``None`` instead of
raising an exception.
.. code-block:: clj
=> (first (repeat 10))
10
=> (first [])
None
for
---
``for`` is used to evaluate some forms for each element in an iterable
object, such as a list. The return values of the forms are discarded and
the ``for`` form returns ``None``.
::
=> (for [x [1 2 3]]
... (print "iterating")
... (print x))
iterating
1
iterating
2
iterating
3
In its square-bracketed first argument, ``for`` allows the same types of
clauses as lfor_.
::
=> (for [x [1 2 3] :if (!= x 2) y [7 8]]
... (print x y))
1 7
1 8
3 7
3 8
Furthermore, the last argument of ``for`` can be an ``(else …)`` form.
This form is executed after the last iteration of the ``for``\'s
outermost iteration clause, but only if that outermost loop terminates
normally. If it's jumped out of with e.g. ``break``, the ``else`` is
ignored.
.. code-block:: clj
=> (for [element [1 2 3]] (if (< element 3)
... (print element)
... (break))
... (else (print "loop finished")))
1
2
=> (for [element [1 2 3]] (if (< element 4)
... (print element)
... (break))
... (else (print "loop finished")))
1
2
3
loop finished
.. _gensym:
gensym
------
.. versionadded:: 0.9.12
``gensym`` is used to generate a unique symbol that allows macros to be
written without accidental variable name clashes.
.. code-block:: clj
=> (gensym)
HySymbol('_G\uffff1')
=> (gensym "x")
HySymbol('_x\uffff2')
.. seealso::
Section :ref:`using-gensym`
get
---
``get`` is used to access single elements in collections. ``get`` takes at
least two parameters: the *data structure* and the *index* or *key* of the
item. It will then return the corresponding value from the collection. If
multiple *index* or *key* values are provided, they are used to access
successive elements in a nested structure. Example usage:
.. code-block:: clj
=> (do
... (setv animals {"dog" "bark" "cat" "meow"}
... numbers (, "zero" "one" "two" "three")
... nested [0 1 ["a" "b" "c"] 3 4])
... (print (get animals "dog"))
... (print (get numbers 2))
... (print (get nested 2 1)))
bark
two
b
.. note:: ``get`` raises a KeyError if a dictionary is queried for a
non-existing key.
.. note:: ``get`` raises an IndexError if a list or a tuple is queried for an
index that is out of bounds.
gfor
----
``gfor`` creates a :ref:`generator expression `. Its syntax
is the same as that of `lfor`_. The difference is that ``gfor`` returns
an iterator, which evaluates and yields values one at a time.
::
=> (setv accum [])
=> (list (take-while
... (fn [x] (< x 5))
... (gfor x (count) :do (.append accum x) x)))
[0, 1, 2, 3, 4]
=> accum
[0, 1, 2, 3, 4, 5]
global
------
``global`` can be used to mark a symbol as global. This allows the programmer to
assign a value to a global symbol. Reading a global symbol does not require the
``global`` keyword -- only assigning it does.
The following example shows how the global symbol ``a`` is assigned a value in a
function and is later on printed in another function. Without the ``global``
keyword, the second function would have raised a ``NameError``.
.. code-block:: clj
(defn set-a [value]
(global a)
(setv a value))
(defn print-a []
(print a))
(set-a 5)
(print-a)
if / if* / if-not
-----------------
.. versionadded:: 0.10.0
if-not
``if / if* / if-not`` respect Python *truthiness*, that is, a *test* fails if it
evaluates to a "zero" (including values of ``len`` zero, ``None``, and
``False``), and passes otherwise, but values with a ``__bool__`` method
(``__nonzero__`` in Python 2) can overrides this.
The ``if`` macro is for conditionally selecting an expression for evaluation.
The result of the selected expression becomes the result of the entire ``if``
form. ``if`` can select a group of expressions with the help of a ``do`` block.
``if`` takes any number of alternating *test* and *then* expressions, plus an
optional *else* expression at the end, which defaults to ``None``. ``if`` checks
each *test* in turn, and selects the *then* corresponding to the first passed
test. ``if`` does not evaluate any expressions following its selection, similar
to the ``if/elif/else`` control structure from Python. If no tests pass, ``if``
selects *else*.
The ``if*`` special form is restricted to 2 or 3 arguments, but otherwise works
exactly like ``if`` (which expands to nested ``if*`` forms), so there is
generally no reason to use it directly.
``if-not`` is similar to ``if*`` but the second expression will be executed
when the condition fails while the third and final expression is executed when
the test succeeds -- the opposite order of ``if*``. The final expression is
again optional and defaults to ``None``.
Example usage:
.. code-block:: clj
(print (if (< n 0.0) "negative"
(= n 0.0) "zero"
(> n 0.0) "positive"
"not a number"))
(if* (money-left? account)
(print "let's go shopping")
(print "let's go and work"))
(if-not (money-left? account)
(print "let's go and work")
(print "let's go shopping"))
lif and lif-not
---------------------------------------
.. versionadded:: 0.10.0
.. versionadded:: 0.11.0
lif-not
For those that prefer a more Lispy ``if`` clause, we have
``lif``. This *only* considers ``None`` to be false! All other
"false-ish" Python values are considered true. Conversely, we have
``lif-not`` in parallel to ``if`` and ``if-not`` which
reverses the comparison.
.. code-block:: clj
=> (lif True "true" "false")
"true"
=> (lif False "true" "false")
"true"
=> (lif 0 "true" "false")
"true"
=> (lif None "true" "false")
"false"
=> (lif-not None "true" "false")
"true"
=> (lif-not False "true" "false")
"false"
.. _import:
import
------
``import`` is used to import modules, like in Python. There are several ways
that ``import`` can be used.
.. code-block:: clj
;; Imports each of these modules
;;
;; Python:
;; import sys
;; import os.path
(import sys os.path)
;; Import from a module
;;
;; Python: from os.path import exists, isdir, isfile
(import [os.path [exists isdir isfile]])
;; Import with an alias
;;
;; Python: import sys as systest
(import [sys :as systest])
;; You can list as many imports as you like of different types.
;;
;; Python:
;; from tests.resources import kwtest, function_with_a_dash
;; from os.path import exists, isdir as is_dir, isfile as is_file
;; import sys as systest
(import [tests.resources [kwtest function-with-a-dash]]
[os.path [exists
isdir :as dir?
isfile :as file?]]
[sys :as systest])
;; Import all module functions into current namespace
;;
;; Python: from sys import *
(import [sys [*]])
fn
-----------
``fn``, like Python's ``lambda``, can be used to define an anonymous function.
Unlike Python's ``lambda``, the body of the function can comprise several
statements. The parameters are similar to ``defn``: the first parameter is
vector of parameters and the rest is the body of the function. ``fn`` returns a
new function. In the following example, an anonymous function is defined and
passed to another function for filtering output.
.. code-block:: clj
=> (setv people [{:name "Alice" :age 20}
... {:name "Bob" :age 25}
... {:name "Charlie" :age 50}
... {:name "Dave" :age 5}])
=> (defn display-people [people filter]
... (for [person people] (if (filter person) (print (:name person)))))
=> (display-people people (fn [person] (< (:age person) 25)))
Alice
Dave
Just as in normal function definitions, if the first element of the
body is a string, it serves as a docstring. This is useful for giving
class methods docstrings.
.. code-block:: clj
=> (setv times-three
... (fn [x]
... "Multiplies input by three and returns the result."
... (* x 3)))
This can be confirmed via Python's built-in ``help`` function::
=> (help times-three)
Help on function times_three:
times_three(x)
Multiplies input by three and returns result
(END)
fn/a
----
``fn/a`` is a variant of ``fn`` than defines an anonymous coroutine.
The parameters are similar to ``defn/a``: the first parameter is
vector of parameters and the rest is the body of the function. ``fn/a`` returns a
new coroutine.
last
-----------
.. versionadded:: 0.11.0
``last`` can be used for accessing the last element of a collection:
.. code-block:: clj
=> (last [2 4 6])
6
lfor
----
The comprehension forms ``lfor``, `sfor`_, `dfor`_, `gfor`_, and `for`_
are used to produce various kinds of loops, including Python-style
:ref:`comprehensions `. ``lfor`` in particular
creates a list comprehension. A simple use of ``lfor`` is::
=> (lfor x (range 5) (* 2 x))
[0, 2, 4, 6, 8]
``x`` is the name of a new variable, which is bound to each element of
``(range 5)``. Each such element in turn is used to evaluate the value
form ``(* 2 x)``, and the results are accumulated into a list.
Here's a more complex example::
=> (lfor
... x (range 3)
... y (range 3)
... :if (!= x y)
... :setv total (+ x y)
... [x y total])
[[0, 1, 1], [0, 2, 2], [1, 0, 1], [1, 2, 3], [2, 0, 2], [2, 1, 3]]
When there are several iteration clauses (here, the pairs of forms ``x
(range 3)`` and ``y (range 3)``), the result works like a nested loop or
Cartesian product: all combinations are considered in lexicographic
order.
The general form of ``lfor`` is::
(lfor CLAUSES VALUE)
where the ``VALUE`` is an arbitrary form that is evaluated to produce
each element of the result list, and ``CLAUSES`` is any number of
clauses. There are several types of clauses:
- Iteration clauses, which look like ``LVALUE ITERABLE``. The ``LVALUE``
is usually just a symbol, but could be something more complicated,
like ``[x y]``.
- ``:async LVALUE ITERABLE``, which is an
:ref:`asynchronous ` form of iteration clause.
- ``:do FORM``, which simply evaluates the ``FORM``. If you use
``(continue)`` or ``(break)`` here, they will apply to the innermost
iteration clause before the ``:do``.
- ``:setv LVALUE RVALUE``, which is equivalent to ``:do (setv LVALUE
RVALUE)``.
- ``:if CONDITION``, which is equivalent to ``:do (unless CONDITION
(continue))``.
For ``lfor``, ``sfor``, ``gfor``, and ``dfor``, variables are scoped as
if the comprehension form were its own function, so variables defined by
an iteration clause or ``:setv`` are not visible outside the form. In
fact, these forms are implemented as generator functions whenever they
contain Python statements, with the attendant consequences for calling
``return``. By contrast, ``for`` shares the caller's scope.
.. note:: An exception to the above scoping rules occurs on Python 2 for
``lfor`` specifically (and not ``sfor``, ``gfor``, or ``dfor``) when
Hy can implement the ``lfor`` as a Python list comprehension. Then,
variables will leak to the surrounding scope.
nonlocal
--------
.. versionadded:: 0.11.1
**PYTHON 3.0 AND UP ONLY!**
``nonlocal`` can be used to mark a symbol as not local to the current scope.
The parameters are the names of symbols to mark as nonlocal. This is necessary
to modify variables through nested ``fn`` scopes:
.. code-block:: clj
(defn some-function []
(setv x 0)
(register-some-callback
(fn [stuff]
(nonlocal x)
(setv x stuff))))
Without the call to ``(nonlocal x)``, the inner function would redefine ``x`` to
``stuff`` inside its local scope instead of overwriting the ``x`` in the outer
function.
See `PEP3104
=> (list (multiply (range 10) (range 10)))
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
=> (import random)
=> (defn random-numbers [low high]
... (while True (yield (.randint random low high))))
=> (list (take 15 (random-numbers 1 50)))
[7, 41, 6, 22, 32, 17, 5, 38, 18, 38, 17, 14, 23, 23, 19]
yield-from
----------
.. versionadded:: 0.9.13
**PYTHON 3.3 AND UP ONLY!**
``yield-from`` is used to call a subgenerator. This is useful if you
want your coroutine to be able to delegate its processes to another
coroutine, say, if using something fancy like
`asyncio `_.
I\'m fancy! --- I\'m to right right of fancy --- I\'m alone :(
' defn/a ------ ``defn/a`` macro is a variant of ``defn`` that instead defines coroutines. It takes three parameters: the *name* of the function to define, a vector of *parameters*, and the *body* of the function: .. code-block:: clj (defn/a name [params] body) defmain ------- .. versionadded:: 0.10.1 The ``defmain`` macro defines a main function that is immediately called with ``sys.argv`` as arguments if and only if this file is being executed as a script. In other words, this: .. code-block:: clj (defmain [&rest args] (do-something-with args)) is the equivalent of:: def main(*args): do_something_with(args) return 0 if __name__ == "__main__": import sys retval = main(*sys.argv) if isinstance(retval, int): sys.exit(retval) Note that as you can see above, if you return an integer from this function, this will be used as the exit status for your script. (Python defaults to exit status 0 otherwise, which means everything's okay!) Since ``(sys.exit 0)`` is not run explicitly in the case of a non-integer return from ``defmain``, it's a good idea to put ``(defmain)`` as the last piece of code in your file. If you want fancy command-line arguments, you can use the standard Python module ``argparse`` in the usual way: .. code-block:: clj (import argparse) (defmain [&rest _] (setv parser (argparse.ArgumentParser)) (.add-argument parser "STRING" :help "string to replicate") (.add-argument parser "-n" :type int :default 3 :help "number of copies") (setv args (parser.parse_args)) (print (* args.STRING args.n)) 0) .. _defmacro: defmacro -------- ``defmacro`` is used to define macros. The general format is ``(defmacro name [parameters] expr)``. The following example defines a macro that can be used to swap order of elements in code, allowing the user to write code in infix notation, where operator is in between the operands. .. code-block:: clj => (defmacro infix [code] ... (quasiquote ( ... (unquote (get code 1)) ... (unquote (get code 0)) ... (unquote (get code 2))))) => (infix (1 + 1)) 2 .. _defmacro/g!: defmacro/g! ------------ .. versionadded:: 0.9.12 ``defmacro/g!`` is a special version of ``defmacro`` that is used to automatically generate :ref:`gensym` for any symbol that starts with ``g!``. For example, ``g!a`` would become ``(gensym "a")``. .. seealso:: Section :ref:`using-gensym` .. _defmacro!: defmacro! --------- ``defmacro!`` is like ``defmacro/g!`` plus automatic once-only evaluation for ``o!`` parameters, which are available as the equivalent ``g!`` symbol. For example, .. code-block:: clj => (defn expensive-get-number [] (print "spam") 14) => (defmacro triple-1 [n] `(+ ~n ~n ~n)) => (triple-1 (expensive-get-number)) ; evals n three times spam spam spam 42 => (defmacro/g! triple-2 [n] `(do (setv ~g!n ~n) (+ ~g!n ~g!n ~g!n))) => (triple-2 (expensive-get-number)) ; avoid repeats with a gensym spam 42 => (defmacro! triple-3 [o!n] `(+ ~g!n ~g!n ~g!n)) => (triple-3 (expensive-get-number)) ; easier with defmacro! spam 42 deftag -------- .. versionadded:: 0.13.0 ``deftag`` defines a tag macro. A tag macro is a unary macro that has the same semantics as an ordinary macro defined with ``defmacro``. It is called with the syntax ``#tag FORM``, where ``tag`` is the name of the macro, and ``FORM`` is any form. The ``tag`` is often only one character, but it can be any symbol. .. code-block:: clj => (deftag ♣ [expr] `[~expr ~expr])