Adhere to CPython's documentation guidelines

- Inline code is written using ``double backticks``
- Italicized text uses *asterisks* rather than `single backticks`
- Function parameters are italicized rather than written as inline code
This commit is contained in:
Kevin Yap 2014-12-06 22:05:52 -08:00
parent d50485710c
commit 8c0ac0862f
8 changed files with 292 additions and 299 deletions

View File

@ -24,8 +24,8 @@ ap-if
Usage: ``(ap-if (foo) (print it))`` Usage: ``(ap-if (foo) (print it))``
Evaluate the first form for trutheyness, and bind it to ``it`` in both the Evaluates the first form for truthiness, and bind it to ``it`` in both the
true and false branch. true and false branches.
.. _ap-each: .. _ap-each:
@ -46,7 +46,7 @@ ap-each-while
Usage: ``(ap-each-while list pred body)`` Usage: ``(ap-each-while list pred body)``
Evaluate the form for each element where the predicate form returns Evaluate the form for each element where the predicate form returns
`True`. ``True``.
.. code-block:: hy .. code-block:: hy

View File

@ -4,8 +4,8 @@ loop/recur
.. versionadded:: 0.10.0 .. versionadded:: 0.10.0
The loop/recur macro gives programmers a simple way to use tail-call The ``loop`` / ``recur`` macro gives programmers a simple way to use
optimization (TCO) in their Hy code. tail-call optimization (TCO) in their Hy code.
A tail call is a subroutine call that happens inside another A tail call is a subroutine call that happens inside another
procedure as its final action; it may produce a return value which procedure as its final action; it may produce a return value which

View File

@ -4,8 +4,8 @@ defmulti
.. versionadded:: 0.10.0 .. versionadded:: 0.10.0
`defmulti` lets you arity-overload a function by the given number of ``defmulti`` lets you arity-overload a function by the given number of
args and/or kwargs. Inspired by Clojure's take on `defn`. args and/or kwargs. Inspired by Clojure's take on ``defn``.
.. code-block:: clj .. code-block:: clj

View File

@ -2,7 +2,6 @@
Hy (the language) Hy (the language)
================= =================
.. warning:: .. warning::
This is incomplete; please consider contributing to the documentation This is incomplete; please consider contributing to the documentation
effort. effort.
@ -15,21 +14,21 @@ Hy maintains, over everything else, 100% compatibility in both directions
with Python itself. All Hy code follows a few simple rules. Memorize with Python itself. All Hy code follows a few simple rules. Memorize
this, as it's going to come in handy. this, as it's going to come in handy.
These rules help ensure that Hy code is idiomatic and interface-able in both These rules help ensure that Hy code is idiomatic and interfaceable in both
languages. languages.
* Symbols in earmufs will be translated to the upper-cased version of that * Symbols in earmufs will be translated to the upper-cased version of that
string. For example, `foo` will become `FOO`. string. For example, ``foo`` will become ``FOO``.
* UTF-8 entities will be encoded using * UTF-8 entities will be encoded using
`punycode <http://en.wikipedia.org/wiki/Punycode>`_ and prefixed with `punycode <http://en.wikipedia.org/wiki/Punycode>`_ and prefixed with
`hy_`. For instance, `⚘` will become `hy_w7h`, `♥` will become `hy_g6h`, ``hy_``. For instance, ```` will become ``hy_w7h``, ```` will become
and `i♥u` will become `hy_iu_t0x`. ``hy_g6h``, and ``i♥u`` will become ``hy_iu_t0x``.
* Symbols that contain dashes will have them replaced with underscores. For * Symbols that contain dashes will have them replaced with underscores. For
example, `render-template` will become `render_template`. This means that example, ``render-template`` will become ``render_template``. This means
symbols with dashes will shadow their underscore equivalents, and vice that symbols with dashes will shadow their underscore equivalents, and vice
versa. versa.
@ -45,8 +44,7 @@ behavior that's slightly unexpected in some situations.
.. versionadded:: 0.10.0 .. versionadded:: 0.10.0
``.`` is used to perform attribute access on objects. It uses a small DSL
`.` is used to perform attribute access on objects. It uses a small DSL
to allow quick access to attributes and items in a nested data structure. to allow quick access to attributes and items in a nested data structure.
For instance, For instance,
@ -55,17 +53,17 @@ For instance,
(. foo bar baz [(+ 1 2)] frob) (. foo bar baz [(+ 1 2)] frob)
Compiles down to Compiles down to:
.. code-block:: python .. code-block:: python
foo.bar.baz[1 + 2].frob foo.bar.baz[1 + 2].frob
`.` compiles its first argument (in the example, `foo`) as the object on ``.`` compiles its first argument (in the example, *foo*) as the object on
which to do the attribute dereference. It uses bare symbols as which to do the attribute dereference. It uses bare symbols as attributes
attributes to access (in the example, `bar`, `baz`, `frob`), and to access (in the example, *bar*, *baz*, *frob*), and compiles the contents
compiles the contents of lists (in the example, ``[(+ 1 2)]``) for of lists (in the example, ``[(+ 1 2)]``) for indexation. Other arguments
indexation. Other arguments throw a compilation error. throw a compilation error.
Access to unknown attributes throws an :exc:`AttributeError`. Access to Access to unknown attributes throws an :exc:`AttributeError`. Access to
unknown keys throws an :exc:`IndexError` (on lists and tuples) or a unknown keys throws an :exc:`IndexError` (on lists and tuples) or a
@ -74,9 +72,9 @@ unknown keys throws an :exc:`IndexError` (on lists and tuples) or a
-> ->
-- --
`->` or `threading macro` is used to avoid nesting of expressions. The threading ``->`` (or the *threading macro*) is used to avoid nesting of expressions. The
macro inserts each expression into the next expressions first argument place. threading macro inserts each expression into the next expression's first argument
The following code demonstrates this: place. The following code demonstrates this:
.. code-block:: clj .. code-block:: clj
@ -88,9 +86,9 @@ The following code demonstrates this:
->> ->>
--- ---
`->>` or `threading tail macro` is similar to `threading macro` but instead of ``->>`` (or the *threading tail macro*) is similar to the *threading macro*, but
inserting each expression into the next expressions first argument, it instead of inserting each expression into the next expression's first argument,
appends it as the last argument. The following code demonstrates this: it appends it as the last argument. The following code demonstrates this:
.. code-block:: clj .. code-block:: clj
@ -102,10 +100,10 @@ appends it as the last argument. The following code demonstrates this:
apply apply
----- -----
`apply` is used to apply an optional list of arguments and an optional ``apply`` is used to apply an optional list of arguments and an optional
dictionary of kwargs to a function. dictionary of kwargs to a function.
Usage: `(apply fn-name [args] [kwargs])` Usage: ``(apply fn-name [args] [kwargs])``
Examples: Examples:
@ -133,9 +131,9 @@ Examples:
and and
--- ---
`and` is used in logical expressions. It takes at least two parameters. If all ``and`` is used in logical expressions. It takes at least two parameters. If
parameters evaluate to `True`, the last parameter is returned. In any other all parameters evaluate to ``True``, the last parameter is returned. In any
case, the first false value will be returned. Example usage: other case, the first false value will be returned. Example usage:
.. code-block:: clj .. code-block:: clj
@ -153,7 +151,7 @@ case, the first false value will be returned. Example usage:
.. note:: .. note::
`and` shortcuts and stops evaluating parameters as soon as the first ``and`` short-circuits and stops evaluating parameters as soon as the first
false is encountered. false is encountered.
.. code-block:: clj .. code-block:: clj
@ -165,24 +163,24 @@ case, the first false value will be returned. Example usage:
assert assert
------ ------
`assert` is used to verify conditions while the program is running. If the ``assert`` is used to verify conditions while the program is running. If the
condition is not met, an `AssertionError` is raised. The example usage: condition is not met, an ``AssertionError`` is raised. Example usage:
.. code-block:: clj .. code-block:: clj
(assert (= variable expected-value)) (assert (= variable expected-value))
Assert takes a single parameter, a conditional that evaluates to either `True` ``assert`` takes a single parameter, a conditional that evaluates to either
or `False`. ``True`` or ``False``.
assoc assoc
----- -----
`assoc` is used to associate a key with a value in a dictionary or to set an ``assoc`` is used to associate a key with a value in a dictionary or to set an
index of a list to a value. It takes at least three parameters: the `data index of a list to a value. It takes at least three parameters: the *data
structure` to be modified, `key` or `index` and `value`. If more than three structure* to be modified, a *key* or *index*, and a *value*. If more than
parameters are used, it will associate in pairs. three parameters are used, it will associate in pairs.
Examples of usage: Examples of usage:
@ -203,15 +201,15 @@ Examples of usage:
... (print collection)) ... (print collection))
[1, 2, None, 4] [1, 2, None, 4]
.. note:: `assoc` modifies the datastructure in place and returns `None`. .. note:: ``assoc`` modifies the datastructure in place and returns ``None``.
break break
----- -----
`break` is used to break out from a loop. It terminates the loop immediately. ``break`` is used to break out from a loop. It terminates the loop immediately.
The following example has an infinite `while` loop that is terminated as soon The following example has an infinite ``while`` loop that is terminated as soon
as the user enters `k`. as the user enters *k*.
.. code-block:: clj .. code-block:: clj
@ -223,8 +221,8 @@ as the user enters `k`.
cond cond
---- ----
`cond` can be used to build nested if-statements. The following example shows ``cond`` can be used to build nested ``if`` statements. The following example
the relationship between the macro and the expanded code: shows the relationship between the macro and its expansion:
.. code-block:: clj .. code-block:: clj
@ -234,7 +232,7 @@ the relationship between the macro and the expanded code:
(if condition-1 result-1 (if condition-1 result-1
(if condition-2 result-2)) (if condition-2 result-2))
As shown below only the first matching result block is executed. As shown below, only the first matching result block is executed.
.. code-block:: clj .. code-block:: clj
@ -251,9 +249,9 @@ As shown below only the first matching result block is executed.
continue continue
-------- --------
`continue` returns execution to the start of a loop. In the following example, ``continue`` returns execution to the start of a loop. In the following example,
function `(side-effect1)` is called for each iteration. `(side-effect2)` ``(side-effect1)`` is called for each iteration. ``(side-effect2)``, however,
however is called only for every other value in the list. is only called on every other value in the list.
.. code-block:: clj .. code-block:: clj
@ -271,11 +269,11 @@ however is called only for every other value in the list.
dict-comp dict-comp
--------- ---------
`dict-comp` is used to create dictionaries. It takes three or four parameters. ``dict-comp`` is used to create dictionaries. It takes three or four parameters.
The first two parameters are for controlling the return value The first two parameters are for controlling the return value (key-value pair)
(key-value pair), while the third is used to select items from a sequence. The while the third is used to select items from a sequence. The fourth and optional
fourth and optional parameter can be used to filter out some of the items in parameter can be used to filter out some of the items in the sequence based on a
the sequence based on a conditional expression. conditional expression.
.. code-block:: hy .. code-block:: hy
@ -286,10 +284,10 @@ the sequence based on a conditional expression.
do / progn do / progn
---------- ----------
`do` and `progn` are used to evaluate each of their arguments and return the last ``do`` and `progn` are used to evaluate each of their arguments and return the
one. Return values from every other than the last argument are discarded. It can be last one. Return values from every other than the last argument are discarded.
used in `lambda` or `list-comp` to perform more complex logic as shown by one of the It can be used in ``lambda`` or ``list-comp`` to perform more complex logic as
examples. shown in one of the following examples.
Some example usage: Some example usage:
@ -309,14 +307,14 @@ Some example usage:
... (x (range 10))) ... (x (range 10)))
[0, 2, 4, 6, 8, 20, 24, 28, 32, 36] [0, 2, 4, 6, 8, 20, 24, 28, 32, 36]
`do` can accept any number of arguments, from 1 to n. ``do`` can accept any number of arguments, from 1 to n.
def / setv def / setv
---------- ----------
`def` and `setv` are used to bind a value, object, or function to a symbol. For ``def`` and ``setv`` are used to bind a value, object, or function to a symbol.
example: For example:
.. code-block:: clj .. code-block:: clj
@ -332,7 +330,7 @@ example:
defclass defclass
-------- --------
New classes are declared with `defclass`. It can takes two optional parameters: New classes are declared with ``defclass``. It can takes two optional parameters:
a vector defining a possible super classes and another vector containing a vector defining a possible super classes and another vector containing
attributes of the new class as two item vectors. attributes of the new class as two item vectors.
@ -363,9 +361,9 @@ below:
defn / defun defn / defun
------------ ------------
`defn` and `defun` macros are used to define functions. They take three ``defn`` and ``defun`` macros are used to define functions. They take three
parameters: the `name` of the function to define, a vector of `parameters`, parameters: the *name* of the function to define, a vector of *parameters*,
and the `body` of the function: and the *body* of the function:
.. code-block:: clj .. code-block:: clj
@ -377,7 +375,7 @@ Parameters may have the following keywords in front of them:
Parameter is optional. The parameter can be given as a two item list, where Parameter is optional. The parameter can be given as a two item list, where
the first element is parameter name and the second is the default value. The the first element is parameter name and the second is the default value. The
parameter can be also given as a single item, in which case the default parameter can be also given as a single item, in which case the default
value is None. value is ``None``.
.. code-block:: clj .. code-block:: clj
@ -437,12 +435,11 @@ defn-alias / defun-alias
.. versionadded:: 0.10.0 .. versionadded:: 0.10.0
The `defn-alias` and `defun-alias` macros are much like `defn`_ above, The ``defn-alias`` and ``defun-alias`` macros are much like `defn`_,
with the difference that instead of defining a function with a single with the distinction that instead of defining a function with a single
name, these can also define aliases. Other than taking a list of name, these can also define aliases. Other than taking a list of
symbols for function names as the first parameter, `defn-alias` and symbols for function names as the first parameter, ``defn-alias`` and
`defun-alias` have no other differences compared to `defn` and ``defun-alias`` are no different from ``defn`` and ``defun``.
`defun`.
.. code-block:: clj .. code-block:: clj
@ -459,7 +456,7 @@ defmain
.. versionadded:: 0.10.1 .. versionadded:: 0.10.1
The `defmain` macro defines a main function that is immediately called 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 with ``sys.argv`` as arguments if and only if this file is being executed
as a script. In other words, this: as a script. In other words, this:
@ -486,9 +483,9 @@ function, this will be used as the exit status for your script.
(Python defaults to exit status 0 otherwise, which means everything's (Python defaults to exit status 0 otherwise, which means everything's
okay!) okay!)
(Since (sys.exit 0) is not run explicitly in case of a non-integer (Since ``(sys.exit 0)`` is not run explicitly in the case of a non-integer
return from defmain, it's good to put (defmain) as the last bit of return from ``defmain``, it's a good idea to put ``(defmain)`` as the last
code in your file.) piece of code in your file.)
.. _defmacro: .. _defmacro:
@ -496,11 +493,11 @@ code in your file.)
defmacro defmacro
-------- --------
`defmacro` is used to define macros. The general format is ``defmacro`` is used to define macros. The general format is
`(defmacro name [parameters] expr)`. ``(defmacro name [parameters] expr)``.
The following example defines a macro that can be used to swap order of elements in The following example defines a macro that can be used to swap order of elements
code, allowing the user to write code in infix notation, where operator is in in code, allowing the user to write code in infix notation, where operator is in
between the operands. between the operands.
.. code-block:: clj .. code-block:: clj
@ -519,9 +516,9 @@ between the operands.
defmacro-alias defmacro-alias
-------------- --------------
`defmacro-alias` is used to define macros with multiple names ``defmacro-alias`` is used to define macros with multiple names
(aliases). The general format is `(defmacro-alias [names] [parameters] (aliases). The general format is ``(defmacro-alias [names] [parameters]
expr)`. It creates multiple macros with the same parameter list and expr)``. It creates multiple macros with the same parameter list and
body, under the specified list of names. body, under the specified list of names.
The following example defines two macros, both of which allow the user The following example defines two macros, both of which allow the user
@ -547,11 +544,11 @@ defmacro/g!
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`defmacro/g!` is a special version of `defmacro` that is used to ``defmacro/g!`` is a special version of ``defmacro`` that is used to
automatically generate :ref:`gensym` for any symbol that automatically generate :ref:`gensym` for any symbol that starts with
starts with ``g!``. ``g!``.
So ``g!a`` would become ``(gensym "a")``. For example, ``g!a`` would become ``(gensym "a")``.
.. seealso:: .. seealso::
@ -562,7 +559,7 @@ defreader
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`defreader` defines a reader macro, enabling you to restructure or ``defreader`` defines a reader macro, enabling you to restructure or
modify syntax. modify syntax.
.. code-block:: clj .. code-block:: clj
@ -582,7 +579,7 @@ del
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`del` removes an object from the current namespace. ``del`` removes an object from the current namespace.
.. code-block:: clj .. code-block:: clj
@ -593,7 +590,7 @@ del
File "<console>", line 1, in <module> File "<console>", line 1, in <module>
NameError: name 'foo' is not defined NameError: name 'foo' is not defined
`del` can also remove objects from mappings, lists, and more. ``del`` can also remove objects from mappings, lists, and more.
.. code-block:: clj .. code-block:: clj
@ -615,7 +612,7 @@ doto
.. versionadded:: 0.10.1 .. versionadded:: 0.10.1
`doto` macro is used to simplify a sequence of method calls to an object. ``doto`` is used to simplify a sequence of method calls to an object.
.. code-block:: clj .. code-block:: clj
@ -634,7 +631,7 @@ doto
eval eval
---- ----
`eval` evaluates a quoted expression and returns the value. ``eval`` evaluates a quoted expression and returns the value.
.. code-block:: clj .. code-block:: clj
@ -652,7 +649,7 @@ eval-when-compile
first / car first / car
----------- -----------
`first` and `car` are macros for accessing the first element of a collection: ``first`` and ``car`` are macros for accessing the first element of a collection:
.. code-block:: clj .. code-block:: clj
@ -663,11 +660,11 @@ first / car
for for
--- ---
`for` is used to call a function for each element in a list or vector. ``for`` is used to call a function for each element in a list or vector.
The results of each call are discarded and the for expression returns The results of each call are discarded and the ``for`` expression returns
`None` instead. The example code iterates over `collection` and ``None`` instead. The example code iterates over *collection* and for each
for each `element` in `collection` calls the `side-effect` *element* in *collection* calls the ``side-effect`` function with *element*
function with `element` as its argument: as its argument:
.. code-block:: clj .. code-block:: clj
@ -678,8 +675,9 @@ function with `element` as its argument:
(for [element collection] (side-effect element) (for [element collection] (side-effect element)
(else (side-effect-2))) (else (side-effect-2)))
The optional `else` block is executed only if the `for` loop terminates The optional ``else`` block is only executed if the ``for`` loop terminates
normally. If the execution is halted with `break`, the `else` does not execute. normally. If the execution is halted with ``break``, the ``else`` block does
not execute.
.. code-block:: clj .. code-block:: clj
@ -703,12 +701,13 @@ normally. If the execution is halted with `break`, the `else` does not execute.
genexpr genexpr
------- -------
`genexpr` is used to create generator expressions. It takes two or three parameters. ``genexpr`` is used to create generator expressions. It takes two or three
The first parameter is the expression controlling the return value, while parameters. The first parameter is the expression controlling the return value,
the second is used to select items from a list. The third and optional while the second is used to select items from a list. The third and optional
parameter can be used to filter out some of the items in the list based on a parameter can be used to filter out some of the items in the list based on a
conditional expression. `genexpr` is similar to `list-comp`, except that it returns conditional expression. ``genexpr`` is similar to ``list-comp``, except it
an iterable that evaluates values one by one instead of evaluating them immediately. returns an iterable that evaluates values one by one instead of evaluating them
immediately.
.. code-block:: hy .. code-block:: hy
@ -725,8 +724,8 @@ gensym
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`gensym` is used to generate a unique symbol to allow writing macros ``gensym`` is used to generate a unique symbol that allows macros to be
without accidental variable name clashes. written without accidental variable name clashes.
.. code-block:: clj .. code-block:: clj
@ -743,10 +742,10 @@ without accidental variable name clashes.
get get
--- ---
`get` is used to access single elements in lists and dictionaries. `get` takes ``get`` is used to access single elements in lists and dictionaries. ``get``
two parameters: the `data structure` and the `index` or `key` of the item. takes two parameters: the *data structure* and the *index* or *key* of the
It will then return the corresponding value from the dictionary or the list. item. It will then return the corresponding value from the dictionary or the
Example usage: list. Example usage:
.. code-block:: clj .. code-block:: clj
@ -757,23 +756,23 @@ Example usage:
bark bark
two two
.. note:: `get` raises a KeyError if a dictionary is queried for a non-existing .. note:: ``get`` raises a KeyError if a dictionary is queried for a
key. non-existing key.
.. note:: `get` raises an IndexError if a list or a tuple is queried for an index .. note:: ``get`` raises an IndexError if a list or a tuple is queried for an
that is out of bounds. index that is out of bounds.
global global
------ ------
`global` can be used to mark a symbol as global. This allows the programmer to ``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 assign a value to a global symbol. Reading a global symbol does not require the
`global` keyword -- only assigning it does. ``global`` keyword -- only assigning it does.
The following example shows how the global symbol `a` is assigned a value in a 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, function and is later on printed in another function. Without the ``global``
the second function would have thrown a `NameError`. keyword, the second function would have thrown a ``NameError``.
.. code-block:: clj .. code-block:: clj
@ -793,13 +792,14 @@ if / if-not
.. versionadded:: 0.10.0 .. versionadded:: 0.10.0
if-not if-not
`if` is used to conditionally select code to be executed. It has to contain a ``if`` is used to conditionally select code to be executed. It has to contain a
condition block and the block to be executed if the condition block evaluates condition block and the block to be executed if the condition block evaluates
to `True`. Optionally, it may contain a final block that is executed in case to ``True``. Optionally, it may contain a final block that is executed in case
the evaluation of the condition is `False`. The `if-not` form is similar, but the evaluation of the condition is ``False``.
the second block will be executed when the condition fails while the third and
final block is executed when the test succeeds -- the opposite order of the `if` ``if-not`` is similar, but the second block will be executed when the condition
form. fails while the third and final block is executed when the test succeeds -- the
opposite order of ``if``.
Example usage: Example usage:
@ -813,9 +813,9 @@ Example usage:
(print "let's go and work") (print "let's go and work")
(print "let's go shopping")) (print "let's go shopping"))
Truth values of Python objects are respected. `None`, `False`, zero of any numeric Python truthiness is respected. ``None``, ``False``, zero of any numeric type,
type, an empty sequence, and an empty dictionary are considered `False`. Everything else an empty sequence, and an empty dictionary are considered ``False``; everything
is considered `True`. else is considered ``True``.
lisp-if / lif and lisp-if-not / lif-not lisp-if / lif and lisp-if-not / lif-not
@ -826,10 +826,11 @@ lisp-if / lif and lisp-if-not / lif-not
.. versionadded:: 0.10.2 .. versionadded:: 0.10.2
lisp-if-not / lif-not lisp-if-not / lif-not
For those that prefer a more Lispy `if` clause, we have `lisp-if`, or `lif`. This For those that prefer a more Lispy ``if`` clause, we have ``lisp-if``, or
*only* considers `None`/`nil` as false! All other "false-ish" Python values are ``lif``. This *only* considers ``None`` / ``nil`` to be false! All other
considered true. Conversely, we have `lisp-if-not` and `lif-not` in parallel to "false-ish" Python values are considered true. Conversely, we have
`if` and `if-not` which reverses the comparison. ``lisp-if-not`` and ``lif-not`` in parallel to ``if`` and ``if-not`` which
reverses the comparison.
.. code-block:: clj .. code-block:: clj
@ -863,8 +864,8 @@ considered true. Conversely, we have `lisp-if-not` and `lif-not` in parallel to
import import
------ ------
`import` is used to import modules, like in Python. There are several forms ``import`` is used to import modules, like in Python. There are several ways
of import you can use. that ``import`` can be used.
.. code-block:: clj .. code-block:: clj
@ -897,9 +898,9 @@ of import you can use.
lambda / fn lambda / fn
----------- -----------
`lambda` and `fn` can be used to define an anonymous function. The parameters are ``lambda`` and ``fn`` can be used to define an anonymous function. The parameters are
similar to `defn`: the first parameter is vector of parameters and the rest is the similar to ``defn``: the first parameter is vector of parameters and the rest is the
body of the function. `lambda` returns a new function. In the following example, an body of the function. ``lambda`` returns a new function. In the following example, an
anonymous function is defined and passed to another function for filtering output. anonymous function is defined and passed to another function for filtering output.
.. code-block:: clj .. code-block:: clj
@ -917,7 +918,7 @@ anonymous function is defined and passed to another function for filtering outpu
Dave Dave
Just as in normal function definitions, if the first element of the Just as in normal function definitions, if the first element of the
body is a string, it serves as docstring. This is useful for giving body is a string, it serves as a docstring. This is useful for giving
class methods docstrings. class methods docstrings.
.. code-block:: clj .. code-block:: clj
@ -940,8 +941,8 @@ This can be confirmed via Python's built-in ``help`` function::
let let
--- ---
`let` is used to create lexically scoped variables. They are created at the ``let`` is used to create lexically scoped variables. They are created at the
beginning of the `let` form and cease to exist after the form. The following beginning of the ``let`` form and cease to exist after the form. The following
example showcases this behaviour: example showcases this behaviour:
.. code-block:: clj .. code-block:: clj
@ -953,10 +954,10 @@ example showcases this behaviour:
6 6
5 5
The `let` macro takes two parameters: a vector defining `variables` and the The ``let`` macro takes two parameters: a vector defining *variables* and the
`body` which gets executed. `variables` is a vector where each element is either *body* which gets executed. *variables* is a vector where each element is either
a single variable or a vector defining a variable value pair. In the case of a a single variable or a vector defining a variable value pair. In the case of a
single variable, it is assigned value `None`; otherwise, the supplied value is single variable, it is assigned value ``None``; otherwise, the supplied value is
used. used.
.. code-block:: clj .. code-block:: clj
@ -968,7 +969,7 @@ used.
list-comp list-comp
--------- ---------
`list-comp` performs list comprehensions. It takes two or three parameters. ``list-comp`` performs list comprehensions. It takes two or three parameters.
The first parameter is the expression controlling the return value, while The first parameter is the expression controlling the return value, while
the second is used to select items from a list. The third and optional the second is used to select items from a list. The third and optional
parameter can be used to filter out some of the items in the list based on a parameter can be used to filter out some of the items in the list based on a
@ -990,9 +991,9 @@ conditional expression. Some examples:
not not
--- ---
`not` is used in logical expressions. It takes a single parameter and ``not`` is used in logical expressions. It takes a single parameter and
returns a reversed truth value. If `True` is given as a parameter, `False` returns a reversed truth value. If ``True`` is given as a parameter, ``False``
will be returned and vice-versa. Example usage: will be returned, and vice-versa. Example usage:
.. code-block:: clj .. code-block:: clj
@ -1009,8 +1010,8 @@ will be returned and vice-versa. Example usage:
or or
-- --
`or` is used in logical expressions. It takes at least two parameters. It will ``or`` is used in logical expressions. It takes at least two parameters. It
return the first non-false parameter. If no such value exists, the last will return the first non-false parameter. If no such value exists, the last
parameter will be returned. parameter will be returned.
.. code-block:: clj .. code-block:: clj
@ -1024,7 +1025,7 @@ parameter will be returned.
=> (and False 1 True False) => (and False 1 True False)
1 1
.. note:: `or` short-circuits and stops evaluating parameters as soon as the .. note:: ``or`` short-circuits and stops evaluating parameters as soon as the
first true value is encountered. first true value is encountered.
.. code-block:: clj .. code-block:: clj
@ -1036,24 +1037,23 @@ parameter will be returned.
print print
----- -----
`print` is used to output on screen. Example usage: ``print`` is used to output on screen. Example usage:
.. code-block:: clj .. code-block:: clj
(print "Hello world!") (print "Hello world!")
.. note:: `print` always returns None .. note:: ``print`` always returns ``None``.
quasiquote quasiquote
---------- ----------
`quasiquote` allows you to quote a form, but also selectively evaluate ``quasiquote`` allows you to quote a form, but also selectively evaluate
expressions. Expressions inside a `quasiquote` can be selectively evaluated expressions. Expressions inside a ``quasiquote`` can be selectively evaluated
using `unquote` (~). The evaluated form can also be spliced using using ``unquote`` (``~``). The evaluated form can also be spliced using
`unquote-splice` (~@). Quasiquote can be also written using the backquote (`) ``unquote-splice`` (``~@``). Quasiquote can be also written using the backquote
symbol. (`````) symbol.
.. code-block:: clj .. code-block:: clj
@ -1067,9 +1067,8 @@ symbol.
quote quote
----- -----
`quote` returns the form passed to it without evaluating it. `quote` can ``quote`` returns the form passed to it without evaluating it. ``quote`` can
be alternatively written using the (') symbol alternatively be written using the apostrophe (``'``) symbol.
.. code-block:: clj .. code-block:: clj
@ -1084,11 +1083,11 @@ be alternatively written using the (') symbol
require require
------- -------
`require` is used to import macros from a given module. It takes at least one ``require`` is used to import macros from a given module. It takes at least one
parameter specifying the module which macros should be imported. Multiple parameter specifying the module which macros should be imported. Multiple
modules can be imported with a single `require`. modules can be imported with a single ``require``.
The following example will import macros from `module-1` and `module-2`: The following example will import macros from ``module-1`` and ``module-2``:
.. code-block:: clj .. code-block:: clj
@ -1098,8 +1097,8 @@ The following example will import macros from `module-1` and `module-2`:
rest / cdr rest / cdr
---------- ----------
`rest` and `cdr` return the collection passed as an argument without the first ``rest`` and ``cdr`` return the collection passed as an argument without the
element: first element:
.. code-block:: clj .. code-block:: clj
@ -1110,7 +1109,7 @@ element:
set-comp set-comp
-------- --------
`set-comp` is used to create sets. It takes two or three parameters. ``set-comp`` is used to create sets. It takes two or three parameters.
The first parameter is for controlling the return value, while the second is The first parameter is for controlling the return value, while the second is
used to select items from a sequence. The third and optional parameter can be used to select items from a sequence. The third and optional parameter can be
used to filter out some of the items in the sequence based on a conditional used to filter out some of the items in the sequence based on a conditional
@ -1126,13 +1125,13 @@ expression.
slice slice
----- -----
`slice` can be used to take a subset of a list and create a new list from it. ``slice`` can be used to take a subset of a list and create a new list from it.
The form takes at least one parameter specifying the list to slice. Two The form takes at least one parameter specifying the list to slice. Two
optional parameters can be used to give the start and end position of the optional parameters can be used to give the start and end position of the
subset. If they are not supplied, default value of `None` will be used instead. subset. If they are not supplied, the default value of ``None`` will be used
The third optional parameter is used to control step between the elements. instead. The third optional parameter is used to control step between the elements.
`slice` follows the same rules as its Python counterpart. Negative indices are ``slice`` follows the same rules as its Python counterpart. Negative indices are
counted starting from the end of the list. Some example usage: counted starting from the end of the list. Some example usage:
.. code-block:: clj .. code-block:: clj
@ -1158,8 +1157,8 @@ counted starting from the end of the list. Some example usage:
throw / raise throw / raise
------------- -------------
The `throw` or `raise` forms can be used to raise an `Exception` at runtime. The ``throw`` or ``raise`` forms can be used to raise an ``Exception`` at
Example usage: runtime. Example usage:
.. code-block:: clj .. code-block:: clj
@ -1173,15 +1172,15 @@ Example usage:
; Throw an IOError("foobar") ; Throw an IOError("foobar")
`throw` can accept a single argument (an `Exception` class or instance) or ``throw`` can accept a single argument (an ``Exception`` class or instance)
no arguments to re-raise the last `Exception`. or no arguments to re-raise the last ``Exception``.
try try
--- ---
The `try` form is used to start a `try` / `catch` block. The form is used The ``try`` form is used to start a ``try`` / ``catch`` block. The form is
as follows: used as follows:
.. code-block:: clj .. code-block:: clj
@ -1191,19 +1190,19 @@ as follows:
(else (print "no errors")) (else (print "no errors"))
(finally (print "all done"))) (finally (print "all done")))
`try` must contain at least one `catch` block, and may optionally have an ``try`` must contain at least one ``catch`` block, and may optionally include
`else` or `finally` block. If an error is raised with a matching catch an ``else`` or ``finally`` block. If an error is raised with a matching catch
block during execution of `error-prone-function`, that catch block will block during the execution of ``error-prone-function``, that ``catch`` block
be executed. If no errors are raised, the `else` block is executed. The will be executed. If no errors are raised, the ``else`` block is executed. The
`finally` block will be executed last, regardless of whether or not an error ``finally`` block will be executed last regardless of whether or not an error
was raised. was raised.
unless unless
------ ------
The `unless` macro is a shorthand for writing an `if` statement that checks if the The ``unless`` macro is a shorthand for writing an ``if`` statement that checks if
given conditional is `False`. The following shows the expansion of this macro. the given conditional is ``False``. The following shows the expansion of this macro.
.. code-block:: clj .. code-block:: clj
@ -1217,8 +1216,8 @@ given conditional is `False`. The following shows the expansion of this macro.
unquote unquote
------- -------
Within a quasiquoted form, `unquote` forces evaluation of a symbol. `unquote` Within a quasiquoted form, ``unquote`` forces evaluation of a symbol. ``unquote``
is aliased to the `~` symbol. is aliased to the tilde (``~``) symbol.
.. code-block:: clj .. code-block:: clj
@ -1233,10 +1232,10 @@ is aliased to the `~` symbol.
unquote-splice unquote-splice
-------------- --------------
`unquote-splice` forces the evaluation of a symbol within a quasiquoted form, ``unquote-splice`` forces the evaluation of a symbol within a quasiquoted form,
much like `unquote`. `unquote-splice` can only be used when the symbol being much like ``unquote``. ``unquote-splice`` can only be used when the symbol
unquoted contains an iterable value, as it "splices" that iterable into the being unquoted contains an iterable value, as it "splices" that iterable into
quasiquoted form. `unquote-splice` is aliased to the `~@` symbol. the quasiquoted form. ``unquote-splice`` is aliased to the ``~@`` symbol.
.. code-block:: clj .. code-block:: clj
@ -1248,13 +1247,12 @@ quasiquoted form. `unquote-splice` is aliased to the `~@` symbol.
;=> (u'+' 1L 2L 3L 4L) ;=> (u'+' 1L 2L 3L 4L)
when when
---- ----
`when` is similar to `unless`, except it tests when the given conditional is ``when`` is similar to ``unless``, except it tests when the given conditional is
`True`. It is not possible to have an `else` block in a `when` macro. The following ``True``. It is not possible to have an ``else`` block in a ``when`` macro. The
shows the expansion of the macro. following shows the expansion of the macro.
.. code-block:: clj .. code-block:: clj
@ -1262,24 +1260,25 @@ shows the expansion of the macro.
(if conditional (do statement)) (if conditional (do statement))
while while
----- -----
`while` is used to execute one or more blocks as long as a condition is met. ``while`` is used to execute one or more blocks as long as a condition is met.
The following example will output "hello world!" to the screen indefinitely: The following example will output "Hello world!" to the screen indefinitely:
.. code-block:: clj .. code-block:: clj
(while True (print "hello world!")) (while True (print "Hello world!"))
with with
---- ----
`with` is used to wrap the execution of a block within a context manager. The ``with`` is used to wrap the execution of a block within a context manager. The
context manager can then set up the local system and tear it down in a controlled context manager can then set up the local system and tear it down in a controlled
manner. The archetypical example of using `with` is when processing files. `with` manner. The archetypical example of using ``with`` is when processing files.
can bind context to an argument or ignore it completely, as shown below: ``with`` can bind context to an argument or ignore it completely, as shown below:
.. code-block:: clj .. code-block:: clj
@ -1289,8 +1288,8 @@ can bind context to an argument or ignore it completely, as shown below:
(with [[arg (expr)] [(expr)]] block) (with [[arg (expr)] [(expr)]] block)
The following example will open file `NEWS` and print its content on screen. The The following example will open the ``NEWS`` file and print its content to the
file is automatically closed after it has been processed. screen. The file is automatically closed after it has been processed.
.. code-block:: clj .. code-block:: clj
@ -1300,9 +1299,9 @@ file is automatically closed after it has been processed.
with-decorator with-decorator
-------------- --------------
`with-decorator` is used to wrap a function with another. The function ``with-decorator`` is used to wrap a function with another. The function
performing the decoration should accept a single value: the function being performing the decoration should accept a single value: the function being
decorated, and return a new function. `with-decorator` takes a minimum decorated, and return a new function. ``with-decorator`` takes a minimum
of two parameters: the function performing decoration and the function of two parameters: the function performing decoration and the function
being decorated. More than one decorator function can be applied; they being decorated. More than one decorator function can be applied; they
will be applied in order from outermost to innermost, ie. the first will be applied in order from outermost to innermost, ie. the first
@ -1321,11 +1320,11 @@ are called just like a function call.
(defn some-function [] ...) (defn some-function [] ...)
In the following example, `inc-decorator` is used to decorate the function In the following example, ``inc-decorator`` is used to decorate the function
`addition` with a function that takes two parameters and calls the ``addition`` with a function that takes two parameters and calls the
decorated function with values that are incremented by 1. When decorated function with values that are incremented by 1. When
the decorated `addition` is called with values 1 and 1, the end result the decorated ``addition`` is called with values 1 and 1, the end result
will be 4 (1+1 + 1+1). will be 4 (``1+1 + 1+1``).
.. code-block:: clj .. code-block:: clj
@ -1350,7 +1349,8 @@ with-gensyms
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`with-gensym` is used to generate a set of :ref:`gensym` for use in a macro. ``with-gensym`` is used to generate a set of :ref:`gensym` for use in a macro.
The following code:
.. code-block:: hy .. code-block:: hy
@ -1374,11 +1374,11 @@ expands to:
yield yield
----- -----
`yield` is used to create a generator object that returns one or more values. ``yield`` is used to create a generator object that returns one or more values.
The generator is iterable and therefore can be used in loops, list The generator is iterable and therefore can be used in loops, list
comprehensions and other similar constructs. comprehensions and other similar constructs.
The function `random-numbers` shows how generators can be used to generate The function ``random-numbers`` shows how generators can be used to generate
infinite series without consuming infinite amount of memory. infinite series without consuming infinite amount of memory.
.. code-block:: clj .. code-block:: clj
@ -1407,7 +1407,7 @@ yield-from
**PYTHON 3.3 AND UP ONLY!** **PYTHON 3.3 AND UP ONLY!**
`yield-from` is used to call a subgenerator. This is useful if you ``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 want your coroutine to be able to delegate its processes to another
coroutine, say, if using something fancy like coroutine, say, if using something fancy like
`asyncio <http://docs.python.org/3.4/library/asyncio.html>`_. `asyncio <http://docs.python.org/3.4/library/asyncio.html>`_.

View File

@ -63,7 +63,7 @@ Command Line Options
hyc hyc
--- ---
Command line options Command Line Options
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
.. cmdoption:: file[, fileN] .. cmdoption:: file[, fileN]
@ -94,7 +94,7 @@ hy2py
.. versionadded:: 0.10.1 .. versionadded:: 0.10.1
Command line options Command Line Options
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
.. cmdoption:: -s .. cmdoption:: -s

View File

@ -13,7 +13,7 @@ butlast
Usage: ``(butlast coll)`` Usage: ``(butlast coll)``
Returns an iterator of all but the last item in ``coll``. Returns an iterator of all but the last item in *coll*.
.. code-block:: hy .. code-block:: hy
@ -40,7 +40,7 @@ coll?
Usage: ``(coll? x)`` Usage: ``(coll? x)``
Returns `True` if argument is iterable and not a string. Returns ``True`` if *x* is iterable and not a string.
.. code-block:: hy .. code-block:: hy
@ -61,7 +61,7 @@ cons
Usage: ``(cons a b)`` Usage: ``(cons a b)``
Returns a fresh :ref:`cons cell <hycons>` with car `a` and cdr `b`. Returns a fresh :ref:`cons cell <hycons>` with car *a* and cdr *b*.
.. code-block:: hy .. code-block:: hy
@ -81,7 +81,7 @@ cons?
Usage: ``(cons? foo)`` Usage: ``(cons? foo)``
Checks whether ``foo`` is a :ref:`cons cell <hycons>`. Checks whether *foo* is a :ref:`cons cell <hycons>`.
.. code-block:: hy .. code-block:: hy
@ -103,9 +103,8 @@ dec
Usage: ``(dec x)`` Usage: ``(dec x)``
Return one less than x. Equivalent to ``(- x 1)``. Returns one less than *x*. Equivalent to ``(- x 1)``. Raises ``TypeError``
if ``(not (numeric? x))``.
Raises ``TypeError`` if ``(not (numeric? x))``.
.. code-block:: hy .. code-block:: hy
@ -128,8 +127,8 @@ disassemble
Usage: ``(disassemble tree &optional [codegen false])`` Usage: ``(disassemble tree &optional [codegen false])``
Dump the Python AST for given Hy ``tree`` to standard output. If *codegen* Dump the Python AST for given Hy *tree* to standard output. If *codegen*
is ``true`` function prints Python code instead. is ``True``, the function prints Python code instead.
.. code-block:: hy .. code-block:: hy
@ -149,7 +148,7 @@ empty?
Usage: ``(empty? coll)`` Usage: ``(empty? coll)``
Return `True` if ``coll`` is empty. Equivalent to ``(= 0 (len coll))``. Returns ``True`` if *coll* is empty. Equivalent to ``(= 0 (len coll))``.
.. code-block:: hy .. code-block:: hy
@ -172,8 +171,8 @@ every?
Usage: ``(every? pred coll)`` Usage: ``(every? pred coll)``
Return `True` if ``(pred x)`` is logical true for every ``x`` in ``coll``, Returns ``True`` if ``(pred x)`` is logical true for every *x* in *coll*,
otherwise `False`. Return `True` if ``coll`` is empty. otherwise ``False``. Return ``True`` if *coll* is empty.
.. code-block:: hy .. code-block:: hy
@ -197,7 +196,7 @@ float?
Usage: ``(float? x)`` Usage: ``(float? x)``
Return `True` if x is a float. Returns ``True`` if *x* is a float.
.. code-block:: hy .. code-block:: hy
@ -215,9 +214,8 @@ even?
Usage: ``(even? x)`` Usage: ``(even? x)``
Return `True` if x is even. Returns ``True`` if *x* is even. Raises ``TypeError`` if
``(not (numeric? x))``.
Raises ``TypeError`` if ``(not (numeric? x))``.
.. code-block:: hy .. code-block:: hy
@ -238,7 +236,7 @@ identity
Usage: ``(identity x)`` Usage: ``(identity x)``
Returns argument supplied to the function Returns the argument supplied to the function.
.. code-block:: hy .. code-block:: hy
@ -256,9 +254,8 @@ inc
Usage: ``(inc x)`` Usage: ``(inc x)``
Return one more than x. Equivalent to ``(+ x 1)``. Returns one more than *x*. Equivalent to ``(+ x 1)``. Raises ``TypeError``
if ``(not (numeric? x))``.
Raises ``TypeError`` if ``(not (numeric? x))``.
.. code-block:: hy .. code-block:: hy
@ -277,9 +274,9 @@ Raises ``TypeError`` if ``(not (numeric? x))``.
instance? instance?
--------- ---------
Usage: ``(instance? CLASS x)`` Usage: ``(instance? class x)``
Return `True` if x is an instance of CLASS. Returns ``True`` if *x* is an instance of *class*.
.. code-block:: hy .. code-block:: hy
@ -304,7 +301,7 @@ integer?
Usage: ``(integer? x)`` Usage: ``(integer? x)``
Return `True` if x is an integer. For Python 2, this is Returns `True` if *x* is an integer. For Python 2, this is
either ``int`` or ``long``. For Python 3, this is ``int``. either ``int`` or ``long``. For Python 3, this is ``int``.
.. code-block:: hy .. code-block:: hy
@ -325,7 +322,7 @@ interleave
Usage: ``(interleave seq1 seq2 ...)`` Usage: ``(interleave seq1 seq2 ...)``
Return an iterable of the first item in each of the sequences, Returns an iterable of the first item in each of the sequences,
then the second, etc. then the second, etc.
.. code-block:: hy .. code-block:: hy
@ -346,7 +343,7 @@ interpose
Usage: ``(interpose item seq)`` Usage: ``(interpose item seq)``
Return an iterable of the elements of the sequence separated by the item. Returns an iterable of the elements of the sequence separated by the item.
.. code-block:: hy .. code-block:: hy
@ -364,7 +361,7 @@ iterable?
Usage: ``(iterable? x)`` Usage: ``(iterable? x)``
Return `True` if x is iterable. Iterable objects return a new iterator Returns ``True`` if *x* is iterable. Iterable objects return a new iterator
when ``(iter x)`` is called. Contrast with :ref:`iterator?-fn`. when ``(iter x)`` is called. Contrast with :ref:`iterator?-fn`.
.. code-block:: hy .. code-block:: hy
@ -397,9 +394,9 @@ iterator?
Usage: ``(iterator? x)`` Usage: ``(iterator? x)``
Return `True` if x is an iterator. Iterators are objects that return Returns ``True`` if *x* is an iterator. Iterators are objects that return
themselves as an iterator when ``(iter x)`` is called. themselves as an iterator when ``(iter x)`` is called. Contrast with
Contrast with :ref:`iterable?-fn`. :ref:`iterable?-fn`.
.. code-block:: hy .. code-block:: hy
@ -427,7 +424,7 @@ list*
Usage: ``(list* head &rest tail)`` Usage: ``(list* head &rest tail)``
Generate a chain of nested cons cells (a dotted list) containing the Generates a chain of nested cons cells (a dotted list) containing the
arguments. If the argument list only has one element, return it. arguments. If the argument list only has one element, return it.
.. code-block:: hy .. code-block:: hy
@ -453,7 +450,7 @@ macroexpand
Usage: ``(macroexpand form)`` Usage: ``(macroexpand form)``
Returns the full macro expansion of form. Returns the full macro expansion of *form*.
.. code-block:: hy .. code-block:: hy
@ -472,7 +469,7 @@ macroexpand-1
Usage: ``(macroexpand-1 form)`` Usage: ``(macroexpand-1 form)``
Returns the single step macro expansion of form. Returns the single step macro expansion of *form*.
.. code-block:: hy .. code-block:: hy
@ -507,9 +504,8 @@ neg?
Usage: ``(neg? x)`` Usage: ``(neg? x)``
Return `True` if x is less than zero (0). Returns ``True`` if *x* is less than zero. Raises ``TypeError`` if
``(not (numeric? x))``.
Raises ``TypeError`` if ``(not (numeric? x))``.
.. code-block:: hy .. code-block:: hy
@ -530,7 +526,7 @@ nil?
Usage: ``(nil? x)`` Usage: ``(nil? x)``
Return `True` if x is `nil`/`None`. Returns ``True`` if *x* is ``nil`` / ``None``.
.. code-block:: hy .. code-block:: hy
@ -559,7 +555,7 @@ none?
Usage: ``(none? x)`` Usage: ``(none? x)``
Return `True` if x is `None`. Returns ``True`` if *x* is ``None``.
.. code-block:: hy .. code-block:: hy
@ -585,9 +581,9 @@ nth
Usage: ``(nth coll n &optional [default nil])`` Usage: ``(nth coll n &optional [default nil])``
Return the `nth` item in a collection, counting from 0. Return the Returns the *n*-th item in a collection, counting from 0. Return the
default value, ``nil``, if out of bounds (unless specified otherwise). default value, ``nil``, if out of bounds (unless specified otherwise).
Raise ``ValueError`` if ``n`` is negative. Raises ``ValueError`` if *n* is negative.
.. code-block:: hy .. code-block:: hy
@ -619,8 +615,8 @@ numeric?
Usage: ``(numeric? x)`` Usage: ``(numeric? x)``
Return `True` if x is a numeric, as defined in the Python Returns ``True`` if *x* is a numeric, as defined in Python's
numbers module class ``numbers.Number``. ``numbers.Number`` class.
.. code-block:: hy .. code-block:: hy
@ -641,9 +637,8 @@ odd?
Usage: ``(odd? x)`` Usage: ``(odd? x)``
Return `True` if x is odd. Returns ``True`` if *x* is odd. Raises ``TypeError`` if
``(not (numeric? x))``.
Raises ``TypeError`` if ``(not (numeric? x))``.
.. code-block:: hy .. code-block:: hy
@ -664,9 +659,8 @@ pos?
Usage: ``(pos? x)`` Usage: ``(pos? x)``
Return `True` if x is greater than zero (0). Returns ``True`` if *x* is greater than zero. Raises ``TypeError``
if ``(not (numeric? x))``.
Raises ``TypeError`` if ``(not (numeric? x))``.
.. code-block:: hy .. code-block:: hy
@ -687,8 +681,7 @@ second
Usage: ``(second coll)`` Usage: ``(second coll)``
Return the second member of ``coll``. Equivalent to Returns the second member of *coll*. Equivalent to ``(get coll 1)``.
``(get coll 1)``
.. code-block:: hy .. code-block:: hy
@ -705,8 +698,8 @@ some
Usage: ``(some pred coll)`` Usage: ``(some pred coll)``
Return the first logical true value of ``(pred x)`` for any ``x`` in Returns the first logically-true value of ``(pred x)`` for any ``x`` in
``coll``, otherwise ``nil``. Return ``nil`` if ``coll`` is empty. *coll*, otherwise ``nil``. Return ``nil`` if *coll* is empty.
.. code-block:: hy .. code-block:: hy
@ -733,7 +726,7 @@ string?
Usage: ``(string? x)`` Usage: ``(string? x)``
Return `True` if x is a string. Returns ``True`` if *x* is a string.
.. code-block:: hy .. code-block:: hy
@ -750,7 +743,7 @@ zero?
Usage: ``(zero? x)`` Usage: ``(zero? x)``
Return `True` if x is zero (0). Returns ``True`` if *x* is zero.
.. code-block:: hy .. code-block:: hy
@ -828,7 +821,7 @@ cycle
Usage: ``(cycle coll)`` Usage: ``(cycle coll)``
Return an infinite iterator of the members of coll. Returns an infinite iterator of the members of coll.
.. code-block:: clj .. code-block:: clj
@ -846,7 +839,7 @@ distinct
Usage: ``(distinct coll)`` Usage: ``(distinct coll)``
Returns an iterator containing only the unique members in ``coll``. Returns an iterator containing only the unique members in *coll*.
.. code-block:: hy .. code-block:: hy
@ -867,8 +860,8 @@ drop
Usage: ``(drop n coll)`` Usage: ``(drop n coll)``
Return an iterator, skipping the first ``n`` members of ``coll`` Returns an iterator, skipping the first *n* members of *coll*.
Raises ``ValueError`` if ``n`` is negative. Raises ``ValueError`` if *n* is negative.
.. code-block:: hy .. code-block:: hy
@ -892,7 +885,8 @@ drop-last
Usage: ``(drop-last n coll)`` Usage: ``(drop-last n coll)``
Return an iterator of all but the last ``n`` items in ``coll``. Raise ``ValueError`` if ``n`` is negative. Returns an iterator of all but the last *n* items in *coll*. Raises
``ValueError`` if *n* is negative.
.. code-block:: hy .. code-block:: hy
@ -917,8 +911,7 @@ drop-while
Usage: ``(drop-while pred coll)`` Usage: ``(drop-while pred coll)``
Return an iterator, skipping members of ``coll`` until ``pred`` Returns an iterator, skipping members of *coll* until *pred* is ``False``.
is False.
.. code-block:: hy .. code-block:: hy
@ -939,7 +932,7 @@ filter
Usage: ``(filter pred coll)`` Usage: ``(filter pred coll)``
Return an iterator for all items in ``coll`` that pass the predicate ``pred``. Returns an iterator for all items in *coll* that pass the predicate *pred*.
See also :ref:`remove-fn`. See also :ref:`remove-fn`.
@ -960,7 +953,7 @@ flatten
Usage: ``(flatten coll)`` Usage: ``(flatten coll)``
Return a single list of all the items in ``coll``, by flattening all Returns a single list of all the items in *coll*, by flattening all
contained lists and/or tuples. contained lists and/or tuples.
.. code-block:: hy .. code-block:: hy
@ -979,7 +972,7 @@ iterate
Usage: ``(iterate fn x)`` Usage: ``(iterate fn x)``
Return an iterator of `x`, `fn(x)`, `fn(fn(x))`. Returns an iterator of *x*, *fn(x)*, *fn(fn(x))*, etc.
.. code-block:: hy .. code-block:: hy
@ -997,10 +990,9 @@ read
Usage: ``(read &optional [from-file eof])`` Usage: ``(read &optional [from-file eof])``
Reads the next hy expression from `from-file` (defaults to `sys.stdin`), and Reads the next Hy expression from *from-file* (defaulting to ``sys.stdin``), and
can take a single byte as EOF (defaults to an empty string). can take a single byte as EOF (defaults to an empty string). Raises ``EOFError``
Raises an `EOFError` if `from-file` ends before a complete expression can be if *from-file* ends before a complete expression can be parsed.
parsed.
.. code-block:: hy .. code-block:: hy
@ -1044,8 +1036,8 @@ remove
Usage: ``(remove pred coll)`` Usage: ``(remove pred coll)``
Return an iterator from ``coll`` with elements that pass the Returns an iterator from *coll* with elements that pass the
predicate, ``pred``, removed. predicate, *pred*, removed.
See also :ref:`filter-fn`. See also :ref:`filter-fn`.
@ -1069,7 +1061,7 @@ repeat
Usage: ``(repeat x)`` Usage: ``(repeat x)``
Return an iterator (infinite) of ``x``. Returns an iterator (infinite) of ``x``.
.. code-block:: hy .. code-block:: hy
@ -1084,7 +1076,7 @@ repeatedly
Usage: ``(repeatedly fn)`` Usage: ``(repeatedly fn)``
Return an iterator by calling ``fn`` repeatedly. Returns an iterator by calling *fn* repeatedly.
.. code-block:: hy .. code-block:: hy
@ -1101,8 +1093,8 @@ take
Usage: ``(take n coll)`` Usage: ``(take n coll)``
Return an iterator containing the first ``n`` members of ``coll``. Returns an iterator containing the first *n* members of *coll*.
Raises ``ValueError`` if ``n`` is negative. Raises ``ValueError`` if *n* is negative.
.. code-block:: hy .. code-block:: hy
@ -1122,7 +1114,7 @@ take-nth
Usage: ``(take-nth n coll)`` Usage: ``(take-nth n coll)``
Return an iterator containing every ``nth`` member of ``coll``. Returns an iterator containing every *n*-th member of *coll*.
.. code-block:: hy .. code-block:: hy
@ -1146,7 +1138,7 @@ take-while
Usage: ``(take-while pred coll)`` Usage: ``(take-while pred coll)``
Return an iterator from ``coll`` as long as predicate, ``pred`` returns True. Returns an iterator from *coll* as long as *pred* returns ``True``.
.. code-block:: hy .. code-block:: hy
@ -1168,8 +1160,9 @@ zipwith
Usage: ``(zipwith fn coll ...)`` Usage: ``(zipwith fn coll ...)``
Equivalent to ``zip``, but uses a multi-argument function instead of creating a tuple. Equivalent to ``zip``, but uses a multi-argument function instead of creating
If ``zipwith`` is called with N collections, then ``fn`` must accept N arguments. a tuple. If ``zipwith`` is called with N collections, then *fn* must accept
N arguments.
.. code-block:: hy .. code-block:: hy

View File

@ -27,7 +27,7 @@ Quickstart
6. Hit CTRL-D when you're done. 6. Hit CTRL-D when you're done.
OMG! That's amazing! I want to write a Hy program. *OMG! That's amazing! I want to write a Hy program.*
7. Open up an elite programming editor and type:: 7. Open up an elite programming editor and type::

View File

@ -264,8 +264,8 @@ What you'll notice is that ``cond`` switches off between a some statement
that is executed and checked conditionally for true or falseness, and that is executed and checked conditionally for true or falseness, and
then a bit of code to execute if it turns out to be true. You'll also then a bit of code to execute if it turns out to be true. You'll also
notice that the ``else`` is implemented at the end simply by checking notice that the ``else`` is implemented at the end simply by checking
for "true"--that's because true will always be true, so if we get this for ``true`` -- that's because ``true`` will always be true, so if we get
far, we'll always run that one! this far, we'll always run that one!
You might notice above that if you have code like: You might notice above that if you have code like:
@ -325,7 +325,7 @@ example:
(os.mkdir "/tmp/somedir/anotherdir") (os.mkdir "/tmp/somedir/anotherdir")
(print "Hey, that path isn't there!")) (print "Hey, that path isn't there!"))
Python's context managers ('with' statements) are used like this: Python's context managers (``with`` statements) are used like this:
.. code-block:: clj .. code-block:: clj
@ -488,7 +488,7 @@ Protips!
======== ========
Hy also features something known as the "threading macro", a really neat Hy also features something known as the "threading macro", a really neat
feature of Clojure's. The "threading macro" (written as "->"), is used feature of Clojure's. The "threading macro" (written as ``->``) is used
to avoid deep nesting of expressions. to avoid deep nesting of expressions.
The threading macro inserts each expression into the next expression's first The threading macro inserts each expression into the next expression's first