Yaltik/hy
2
0
Fork 0
Code Pull Requests Releases Activity

Fixes to language documentation

Browse Source 
- Use backticks consistently for inline code
- Capitalize section headers and proper nouns
- Minor grammatical fixes
This commit is contained in:
Kevin Yap 2014-12-06 12:28:28 -08:00
parent 7d0fe31ebe
commit 997501bcc4
5 changed files with 194 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

299
docs/language/api.rst
View File

@ -13,14 +13,14 @@ Theory of Hy
Hy maintains, over everything else, 100% compatibility in both directions 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, it's going to come in handy. this, as it's going to come in handy.
These rules help make sure code is idiomatic and interface-able in both These rules help ensure that Hy code is idiomatic and interface-able in both
languages. languages.
* Symbols in earmufs will be translated to the uppercased 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
@ -33,8 +33,8 @@ languages.
versa. versa.
Builtins Built-Ins
======== =========
Hy features a number of special forms that are used to help generate Hy features a number of special forms that are used to help generate
correct Python AST. The following are "special" forms, which may have correct Python AST. The following are "special" forms, which may have
@ -47,7 +47,7 @@ behavior that's slightly unexpected in some situations.
`.` 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 datastructure. to allow quick access to attributes and items in a nested data structure.
For instance, For instance,
@ -69,7 +69,7 @@ indexation. Other arguments 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
:exc:`KeyError` (on dicts). :exc:`KeyError` (on dictionaries).
-> ->
-- --
@ -89,7 +89,7 @@ The following code demonstrates this:
--- ---
`->>` or `threading tail macro` is similar to `threading macro` but instead of `->>` or `threading tail macro` is similar to `threading macro` but instead of
inserting each expression into the next expression’s first argument place, it inserting each expression into the next expression’s first argument, it
appends it as the last argument. The following code demonstrates this: appends it as the last argument. The following code demonstrates this:
.. code-block:: clj .. code-block:: clj
@ -133,9 +133,9 @@ Examples:
and and
--- ---
`and` form is used in logical expressions. It takes at least two parameters. If `and` is used in logical expressions. It takes at least two parameters. If all
all parameters evaluate to `True` the last parameter is returned. In any other parameters evaluate to `True`, the last parameter is returned. In any other
case the first false value will be returned. Examples of usage: case, the first false value will be returned. Example usage:
.. code-block:: clj .. code-block:: clj
@ -165,7 +165,7 @@ case the first false value will be returned. Examples of 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. The example usage:
.. code-block:: clj .. code-block:: clj
@ -179,10 +179,10 @@ or `False`.
assoc assoc
----- -----
`assoc` form is used to associate a key with a value in a dictionary or to set `assoc` is used to associate a key with a value in a dictionary or to set an
an index of a list to a value. It takes at least three parameters: `datastructure` index of a list to a value. It takes at least three parameters: the `data
to be modified, `key` or `index` and `value`. If more than three parameters are structure` to be modified, `key` or `index` and `value`. If more than three
used it will associate in pairs. parameters are used, it will associate in pairs.
Examples of usage: Examples of usage:
@ -210,24 +210,21 @@ 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 as the user enters `k`.
the user enters `k`.
.. code-block:: clj .. code-block:: clj
(while True (if (= "k" (raw-input "? ")) (while True (if (= "k" (raw-input "? "))
(break) (break)
(print "Try again"))) (print "Try again")))
cond cond
---- ----
`cond` macro can be used to build nested if-statements. `cond` can be used to build nested if-statements. The following example shows
the relationship between the macro and the expanded code:
The following example shows the relationship between the macro and the expanded
code:
.. code-block:: clj .. code-block:: clj
@ -246,7 +243,7 @@ As shown below only the first matching result block is executed.
... [(= value 5) (print "value is equal to 5")] ... [(= value 5) (print "value is equal to 5")]
... [(> value 5) (print "value is greater than 5")] ... [(> value 5) (print "value is greater than 5")]
... [True (print "value is something that it should not be")])) ... [True (print "value is something that it should not be")]))
=> (check-value 6) => (check-value 6)
value is greater than 5 value is greater than 5
@ -255,7 +252,7 @@ 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)` function `(side-effect1)` is called for each iteration. `(side-effect2)`
however is called only for every other value in the list. however is called only for every other value in the list.
.. code-block:: clj .. code-block:: clj
@ -289,10 +286,10 @@ the sequence based on a conditional expression.
do / progn do / progn
---------- ----------
the `do` and `progn` forms are used to evaluate each of their arguments and `do` and `progn` are used to evaluate each of their arguments and return the last
return the last one. Return values from every other than the last argument are one. Return values from every other than the last argument are discarded. It can be
discarded. It can be used in `lambda` or `list-comp` to perform more complex used in `lambda` or `list-comp` to perform more complex logic as shown by one of the
logic as shown by one of the examples. examples.
Some example usage: Some example usage:
@ -306,9 +303,9 @@ Some example usage:
;; assuming that (side-effect) is a function that we want to call for each ;; assuming that (side-effect) is a function that we want to call for each
;; and every value in the list, but whose return value we do not care about ;; and every value in the list, but whose return value we do not care about
=> (list-comp (do (side-effect x) => (list-comp (do (side-effect x)
... (if (< x 5) (* 2 x) ... (if (< x 5) (* 2 x)
... (* 4 x))) ... (* 4 x)))
... (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]
@ -316,9 +313,9 @@ Some example usage:
def / setv def / setv
----------------- ----------
`def` and `setv` are used to bind value, object or a function to a symbol. For `def` and `setv` are used to bind a value, object, or function to a symbol. For
example: example:
.. code-block:: clj .. code-block:: clj
@ -335,7 +332,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.
@ -367,17 +364,17 @@ 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: `name` of the function to define, vector of `parameters` and the parameters: the `name` of the function to define, a vector of `parameters`,
`body` of the function: and the `body` of the function:
.. code-block:: clj .. code-block:: clj
(defn name [params] body) (defn name [params] body)
Parameters may have following keywords in front of them: Parameters may have the following keywords in front of them:
&optional &optional
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.
@ -394,10 +391,10 @@ Parameters may have following keywords in front of them:
101.0 101.0
&key &key
&kwargs &kwargs
parameter will contain 0 or more keyword arguments. Parameter will contain 0 or more keyword arguments.
The following code examples defines a function that will print all keyword The following code examples defines a function that will print all keyword
arguments and their values. arguments and their values.
@ -412,7 +409,7 @@ Parameters may have following keywords in front of them:
parameter-1 1 parameter-1 1
&rest &rest
parameter will contain 0 or more positional arguments. No other positional Parameter will contain 0 or more positional arguments. No other positional
arguments may be specified after this one. arguments may be specified after this one.
The following code example defines a function that can be given 0 to n The following code example defines a function that can be given 0 to n
@ -463,8 +460,8 @@ 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:
.. code-block:: clj .. code-block:: clj
@ -484,7 +481,7 @@ is the equivalent of::
if isinstance(retval, int): if isinstance(retval, int):
sys.exit(retval) sys.exit(retval)
Note, as you can see above, if you return an integer from this 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. 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!)
@ -596,7 +593,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 a mapping, a list, ... `del` can also remove objects from mappings, lists, and more.
.. code-block:: clj .. code-block:: clj
@ -618,7 +615,7 @@ doto
.. versionadded:: 0.10.1 .. versionadded:: 0.10.1
`doto` macro is used to make a sequence of method calls for an object easy. `doto` macro is used to simplify a sequence of method calls to an object.
.. code-block:: clj .. code-block:: clj
@ -664,11 +661,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 `element` in `collection` calls the `side-effect` for each `element` in `collection` calls the `side-effect`
function with `element` as its argument: function with `element` as its argument:
@ -687,7 +684,7 @@ normally. If the execution is halted with `break`, the `else` does not execute.
.. code-block:: clj .. code-block:: clj
=> (for [element [1 2 3]] (if (< element 3) => (for [element [1 2 3]] (if (< element 3)
... (print element) ... (print element)
... (break)) ... (break))
... (else (print "loop finished"))) ... (else (print "loop finished")))
1 1
@ -709,7 +706,7 @@ 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 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
conditional expression. `genexpr` is similar to `list-comp`, except that it returns conditional expression. `genexpr` is similar to `list-comp`, except that it returns
an iterable that evaluates values one by one instead of evaluating them immediately. an iterable that evaluates values one by one instead of evaluating them immediately.
@ -728,7 +725,7 @@ gensym
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`gensym` form is used to generate a unique symbol to allow writing macros `gensym` is used to generate a unique symbol to allow writing macros
without accidental variable name clashes. without accidental variable name clashes.
.. code-block:: clj .. code-block:: clj
@ -746,10 +743,10 @@ without accidental variable name clashes.
get get
--- ---
`get` form is used to access single elements in lists and dictionaries. `get` `get` is used to access single elements in lists and dictionaries. `get` takes
takes two parameters, the `datastructure` and the `index` or `key` of the item. two parameters: the `data structure` and the `index` or `key` of the item.
It will then return the corresponding value from the dictionary or the list. It will then return the corresponding value from the dictionary or the list.
Example usages: Example usage:
.. code-block:: clj .. code-block:: clj
@ -772,11 +769,11 @@ 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, just the assigning does. `global` keyword -- only assigning it does.
Following example shows how global `a` is assigned a value in a function and later The following example shows how the global symbol `a` is assigned a value in a
on printed on another function. Without the `global` keyword, the second function function and is later on printed in another function. Without the `global` keyword,
would thrown a `NameError`. the second function would have thrown a `NameError`.
.. code-block:: clj .. code-block:: clj
@ -793,29 +790,32 @@ would thrown a `NameError`.
if / if-not if / if-not
----------- -----------
the `if` form is used to conditionally select code to be executed. It has to .. versionadded:: 0.10.0
contain the condition block and the block to be executed if the condition if-not
evaluates `True`. Optionally it may contain a block that is executed in case
the evaluation of the condition is `False`. The `if-not` form (*new in `if` is used to conditionally select code to be executed. It has to contain a
0.10.0*) is similar, but the first block after the test will be condition block and the block to be executed if the condition block evaluates
executed when the test fails, while the other, conditional one, when to `True`. Optionally, it may contain a final block that is executed in case
the test succeeds - opposite of the order of the `if` form. the evaluation of the condition is `False`. The `if-not` form is similar, but
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`
form.
Example usage: Example usage:
.. code-block:: clj .. code-block:: clj
(if (money-left? account) (if (money-left? account)
(print "lets go shopping") (print "let's go shopping")
(print "lets go and work")) (print "let's go and work"))
(if-not (money-left? account) (if-not (money-left? account)
(print "lets go and work") (print "let's go and work")
(print "lets go shopping")) (print "let's go shopping"))
Truth values of Python objects are respected. Values `None`, `False`, zero of Truth values of Python objects are respected. `None`, `False`, zero of any numeric
any numeric type, empty sequence and empty dictionary are considered `False`. type, an empty sequence, and an empty dictionary are considered `False`. Everything else
Everything else is considered `True`. is considered `True`.
lisp-if / lif and lisp-if-not / lif-not lisp-if / lif and lisp-if-not / lif-not
@ -826,10 +826,10 @@ 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 lisp-y if clause, we have lisp-if, or lif. This For those that prefer a more Lispy `if` clause, we have `lisp-if`, or `lif`. This
*only* considers None/nil as false! All other values of python *only* considers `None`/`nil` as false! All other "false-ish" Python values are
"falseiness" are considered true. Conversely, we have lisp-if-not or lif-not, considered true. Conversely, we have `lisp-if-not` and `lif-not` in parallel to
in parallel to if / if-not, which reverses the comparison. `if` and `if-not` which reverses the comparison.
.. code-block:: clj .. code-block:: clj
@ -851,7 +851,7 @@ in parallel to if / if-not, which reverses the comparison.
=> (lisp-if-not False "true" "false") => (lisp-if-not False "true" "false")
"false" "false"
; And, same thing ; Equivalent but shorter
=> (lif True "true" "false") => (lif True "true" "false")
"true" "true"
=> (lif nil "true" "false") => (lif nil "true" "false")
@ -898,9 +898,9 @@ 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`: 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 example an anonymous body of the function. `lambda` returns a new function. In the following example, an
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
@ -927,7 +927,7 @@ class methods docstrings.
... "Multiplies input by three and returns the result." ... "Multiplies input by three and returns the result."
... (* x 3))) ... (* x 3)))
Then test it via the Python built-in ``help`` function:: This can be confirmed via Python's built-in ``help`` function::
=> (help times-three) => (help times-three)
Help on function times_three: Help on function times_three:
@ -941,22 +941,22 @@ 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 `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
=> (let [[x 5]] (print x) => (let [[x 5]] (print x)
... (let [[x 6]] (print x)) ... (let [[x 6]] (print x))
... (print x)) ... (print x))
5 5
6 6
5 5
`let` macro takes two parameters: a vector defining `variables` and `body`, The `let` macro takes two parameters: a vector defining `variables` and the
which is being 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 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
@ -971,7 +971,7 @@ 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
conditional expression. Some examples: conditional expression. Some examples:
.. code-block:: clj .. code-block:: clj
@ -990,9 +990,9 @@ conditional expression. Some examples:
not not
--- ---
`not` form 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. Examples for usage: will be returned and vice-versa. Example usage:
.. code-block:: clj .. code-block:: clj
@ -1009,8 +1009,8 @@ will be returned and vice-versa. Examples for usage:
or or
-- --
`or` form is used in logical expressions. It takes at least two parameters. It `or` is used in logical expressions. It takes at least two parameters. It will
will return the first non-false parameter. If no such value exist, the last 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,8 +1024,8 @@ parameter will be returned.
=> (and False 1 True False) => (and False 1 True False)
1 1
.. note:: `or` shortcuts and stops evaluating parameters as soon as the first .. note:: `or` short-circuits and stops evaluating parameters as soon as the
true is encountered. first true value is encountered.
.. code-block:: clj .. code-block:: clj
@ -1036,7 +1036,7 @@ parameter will be returned.
print print
----- -----
the `print` form is used to output on screen. Example usage: `print` is used to output on screen. Example usage:
.. code-block:: clj .. code-block:: clj
@ -1048,11 +1048,11 @@ the `print` form is used to output on screen. Example usage:
quasiquote quasiquote
---------- ----------
`quasiquote` allows you to quote a form, but also to `quasiquote` allows you to quote a form, but also selectively evaluate
selectively evaluate expressions, expressions inside a `quasiquote` expressions. Expressions inside a `quasiquote` can be selectively evaluated
can be selectively evaluated using `unquote` (~). The evaluated form can using `unquote` (~). The evaluated form can also be spliced using
also be spliced using `unquote-splice` (~@). Quasiquote can be also written `unquote-splice` (~@). Quasiquote can be also written using the backquote (`)
using the backquote (`) symbol. symbol.
.. code-block:: clj .. code-block:: clj
@ -1067,7 +1067,7 @@ using the backquote (`) symbol.
quote quote
----- -----
`quote` returns the form passed to it without evaluating. `quote` can `quote` returns the form passed to it without evaluating it. `quote` can
be alternatively written using the (') symbol be alternatively written using the (') symbol
@ -1129,13 +1129,11 @@ 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, default value of `None` will be used instead.
Third optional parameter is used to control step between the elements. The third optional parameter is used to control step between the elements.
`slice` follows the same rules as the Python counterpart. Negative indecies are `slice` follows the same rules as its Python counterpart. Negative indices are
counted starting from the end of the list. counted starting from the end of the list. Some example usage:
Some examples of
usage:
.. code-block:: clj .. code-block:: clj
@ -1160,32 +1158,30 @@ 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 runtime.
Example usage:
Example usage
.. code-block:: clj .. code-block:: clj
(throw) (throw)
; re-rase the last exception ; re-rase the last exception
(throw IOError) (throw IOError)
; Throw an IOError ; Throw an IOError
(throw (IOError "foobar")) (throw (IOError "foobar"))
; 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) or
no arguments to re-raise the last Exception. 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 used
as follows as follows:
.. code-block:: clj .. code-block:: clj
@ -1197,23 +1193,24 @@ as follows
`try` must contain at least one `catch` block, and may optionally have an `try` must contain at least one `catch` block, and may optionally have an
`else` or `finally` block. If an error is raised with a matching catch `else` or `finally` block. If an error is raised with a matching catch
block during execution of `error-prone-function` then that catch block will block during execution of `error-prone-function`, that catch block will
be executed. If no errors are raised the `else` block is executed. Regardless be executed. If no errors are raised, the `else` block is executed. The
if an error was raised or not, the `finally` block is executed as last. `finally` block will be executed last, regardless of whether or not an error
was raised.
unless unless
------ ------
`unless` macro is a shorthand for writing a if-statement that checks if the The `unless` macro is a shorthand for writing an `if` statement that checks if the
given conditional is False. The following shows how the macro expands into code. given conditional is `False`. The following shows the expansion of this macro.
.. code-block:: clj .. code-block:: clj
(unless conditional statement) (unless conditional statement)
(if conditional (if conditional
None None
(do statement)) (do statement))
@ -1256,8 +1253,8 @@ 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 `when` macro. The following `True`. It is not possible to have an `else` block in a `when` macro. The following
shows how the macro is expanded into code. shows the expansion of the macro.
.. code-block:: clj .. code-block:: clj
@ -1268,10 +1265,8 @@ shows how the macro is expanded into code.
while while
----- -----
`while` form is used to execute a single or more blocks as long as a condition `while` is used to execute one or more blocks as long as a condition is met.
is being met. The following example will output "hello world!" to the screen indefinitely:
The following example will output "hello world!" on screen indefinitely:
.. code-block:: clj .. code-block:: clj
@ -1281,10 +1276,10 @@ The following example will output "hello world!" on screen indefinitely:
with with
---- ----
`with` is used to wrap execution of a block with a context manager. The context `with` is used to wrap the execution of a block within a context manager. The
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. Typical example of using `with` is processing files. `with` can bind manner. The archetypical example of using `with` is when processing files. `with`
context to an argument or ignore it completely, as shown below: can bind context to an argument or ignore it completely, as shown below:
.. code-block:: clj .. code-block:: clj
@ -1306,12 +1301,12 @@ 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 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
decorator will be the outermost one & so on. Decorators with arguments decorator will be the outermost one, and so on. Decorators with arguments
are called just like a function call. are called just like a function call.
.. code-block:: clj .. code-block:: clj
@ -1326,11 +1321,10 @@ 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 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
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
@ -1356,8 +1350,7 @@ with-gensyms
.. versionadded:: 0.9.12 .. versionadded:: 0.9.12
`with-gensym` form is used to generate a set of :ref:`gensym` for use `with-gensym` is used to generate a set of :ref:`gensym` for use in a macro.
in a macro.
.. code-block:: hy .. code-block:: hy
@ -1381,11 +1374,11 @@ expands to:
yield yield
----- -----
`yield` is used to create a generator object, that returns 1 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
@ -1416,5 +1409,5 @@ yield-from
`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>`_.

2
docs/language/cli.rst
View File

@ -7,7 +7,7 @@ Command Line Interface
hy hy
-- --
Command line options Command Line Options
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
.. cmdoption:: -c <command> .. cmdoption:: -c <command>

46
docs/language/core.rst
View File

@ -1,10 +1,10 @@
================= =======
Hy Core Hy Core
================= =======
Core Functions Core Functions
=============== ==============
.. _butlast-fn: .. _butlast-fn:
@ -40,7 +40,7 @@ coll?
Usage: ``(coll? x)`` Usage: ``(coll? x)``
Returns true if argument is iterable and not a string. Returns `True` if argument is iterable and not a string.
.. code-block:: hy .. code-block:: hy
@ -149,7 +149,7 @@ empty?
Usage: ``(empty? coll)`` Usage: ``(empty? coll)``
Return True if ``coll`` is empty, i.e. ``(= 0 (len coll))``. Return `True` if ``coll`` is empty. Equivalent to ``(= 0 (len coll))``.
.. code-block:: hy .. code-block:: hy
@ -172,7 +172,8 @@ every?
Usage: ``(every? pred coll)`` Usage: ``(every? pred coll)``
Return True if ``(pred x)`` is logical true for every ``x`` in ``coll``, otherwise False. Return True if ``coll`` is empty. Return `True` if ``(pred x)`` is logical true for every ``x`` in ``coll``,
otherwise `False`. Return `True` if ``coll`` is empty.
.. code-block:: hy .. code-block:: hy
@ -196,7 +197,7 @@ float?
Usage: ``(float? x)`` Usage: ``(float? x)``
Return True if x is a float. Return `True` if x is a float.
.. code-block:: hy .. code-block:: hy
@ -214,7 +215,7 @@ even?
Usage: ``(even? x)`` Usage: ``(even? x)``
Return True if x is even. Return `True` if x is even.
Raises ``TypeError`` if ``(not (numeric? x))``. Raises ``TypeError`` if ``(not (numeric? x))``.
@ -278,7 +279,7 @@ instance?
Usage: ``(instance? CLASS x)`` Usage: ``(instance? CLASS x)``
Return True if x is an instance of CLASS. Return `True` if x is an instance of CLASS.
.. code-block:: hy .. code-block:: hy
@ -303,7 +304,7 @@ integer?
Usage: ``(integer? x)`` Usage: ``(integer? x)``
Return True if x is an integer. For Python 2, this is Return `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
@ -324,7 +325,8 @@ interleave
Usage: ``(interleave seq1 seq2 ...)`` Usage: ``(interleave seq1 seq2 ...)``
Return an iterable of the first item in each of the sequences, then the second etc. Return an iterable of the first item in each of the sequences,
then the second, etc.
.. code-block:: hy .. code-block:: hy
@ -362,7 +364,7 @@ iterable?
Usage: ``(iterable? x)`` Usage: ``(iterable? x)``
Return True if x is iterable. Iterable objects return a new iterator Return `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
@ -395,7 +397,7 @@ iterator?
Usage: ``(iterator? x)`` Usage: ``(iterator? x)``
Return True if x is an iterator. Iterators are objects that return Return `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 :ref:`iterable?-fn`. Contrast with :ref:`iterable?-fn`.
@ -502,7 +504,7 @@ neg?
Usage: ``(neg? x)`` Usage: ``(neg? x)``
Return True if x is less than zero (0). Return `True` if x is less than zero (0).
Raises ``TypeError`` if ``(not (numeric? x))``. Raises ``TypeError`` if ``(not (numeric? x))``.
@ -521,11 +523,11 @@ Raises ``TypeError`` if ``(not (numeric? x))``.
.. _nil?-fn: .. _nil?-fn:
nil? nil?
----- ----
Usage: ``(nil? x)`` Usage: ``(nil? x)``
Return True if x is nil/None. Return `True` if x is `nil`/`None`.
.. code-block:: hy .. code-block:: hy
@ -554,7 +556,7 @@ none?
Usage: ``(none? x)`` Usage: ``(none? x)``
Return True if x is None. Return `True` if x is `None`.
.. code-block:: hy .. code-block:: hy
@ -614,7 +616,7 @@ numeric?
Usage: ``(numeric? x)`` Usage: ``(numeric? x)``
Return True if x is a numeric, as defined in the Python Return `True` if x is a numeric, as defined in the Python
numbers module class ``numbers.Number``. numbers module class ``numbers.Number``.
.. code-block:: hy .. code-block:: hy
@ -636,7 +638,7 @@ odd?
Usage: ``(odd? x)`` Usage: ``(odd? x)``
Return True if x is odd. Return `True` if x is odd.
Raises ``TypeError`` if ``(not (numeric? x))``. Raises ``TypeError`` if ``(not (numeric? x))``.
@ -659,7 +661,7 @@ pos?
Usage: ``(pos? x)`` Usage: ``(pos? x)``
Return True if x is greater than zero (0). Return `True` if x is greater than zero (0).
Raises ``TypeError`` if ``(not (numeric? x))``. Raises ``TypeError`` if ``(not (numeric? x))``.
@ -728,7 +730,7 @@ string?
Usage: ``(string? x)`` Usage: ``(string? x)``
Return True if x is a string. Return `True` if x is a string.
.. code-block:: hy .. code-block:: hy
@ -745,7 +747,7 @@ zero?
Usage: ``(zero? x)`` Usage: ``(zero? x)``
Return True if x is zero (0). Return `True` if x is zero (0).
.. code-block:: hy .. code-block:: hy

32
docs/language/internals.rst
View File

@ -10,7 +10,7 @@ Internal Hy Documentation
Hy Models Hy Models
========= =========
Introduction to Hy models Introduction to Hy Models
------------------------- -------------------------
Hy models are a very thin layer on top of regular Python objects, Hy models are a very thin layer on top of regular Python objects,
@ -33,7 +33,7 @@ macros, be that in the compiler or in pure hy macros.
``HyObject`` is not intended to be used directly to instantiate Hy ``HyObject`` is not intended to be used directly to instantiate Hy
models, but only as a mixin for other classes. models, but only as a mixin for other classes.
Compound models Compound Models
--------------- ---------------
Parenthesized and bracketed lists are parsed as compound models by the Parenthesized and bracketed lists are parsed as compound models by the
@ -77,7 +77,7 @@ The decision of using a list instead of a dict as the base class for
benefit of allowing compound expressions as dict keys (as, for instance, benefit of allowing compound expressions as dict keys (as, for instance,
the :ref:`HyExpression` Python class isn't hashable). the :ref:`HyExpression` Python class isn't hashable).
Atomic models Atomic Models
------------- -------------
In the input stream, double-quoted strings, respecting the Python In the input stream, double-quoted strings, respecting the Python
@ -115,7 +115,7 @@ strings.
.. _hy_numeric_models: .. _hy_numeric_models:
Numeric models Numeric Models
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
``hy.models.integer.HyInteger`` represents integer literals (using the ``hy.models.integer.HyInteger`` represents integer literals (using the
@ -217,7 +217,7 @@ from source to runtime.
.. _lexing: .. _lexing:
Steps 1 and 2: Tokenizing and parsing Steps 1 and 2: Tokenizing and Parsing
------------------------------------- -------------------------------------
The first stage of compiling Hy is to lex the source into tokens that we can The first stage of compiling Hy is to lex the source into tokens that we can
@ -238,7 +238,7 @@ on (directly), and it's what the compiler uses when it compiles Hy down.
.. _compiling: .. _compiling:
Step 3: Hy compilation to Python AST Step 3: Hy Compilation to Python AST
------------------------------------ ------------------------------------
This is where most of the magic in Hy happens. This is where we take Hy AST This is where most of the magic in Hy happens. This is where we take Hy AST
@ -262,7 +262,7 @@ All methods that preform a compilation are marked with the ``@builds()``
decorator. You can either pass the class of the Hy model that it compiles, decorator. You can either pass the class of the Hy model that it compiles,
or you can use a string for expressions. I'll clear this up in a second. or you can use a string for expressions. I'll clear this up in a second.
First stage type-dispatch First Stage Type-Dispatch
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Let's start in the ``compile`` method. The first thing we do is check the Let's start in the ``compile`` method. The first thing we do is check the
@ -276,14 +276,14 @@ Hy AST to Python AST. The ``compile_string`` method takes the ``HyString``, and
returns an ``ast.Str()`` that's populated with the correct line-numbers and returns an ``ast.Str()`` that's populated with the correct line-numbers and
content. content.
Macro-expand Macro-Expand
~~~~~~~~~~~~ ~~~~~~~~~~~~
If we get a ``HyExpression``, we'll attempt to see if this is a known If we get a ``HyExpression``, we'll attempt to see if this is a known
Macro, and push to have it expanded by invoking ``hy.macros.macroexpand``, then Macro, and push to have it expanded by invoking ``hy.macros.macroexpand``, then
push the result back into ``HyASTCompiler.compile``. push the result back into ``HyASTCompiler.compile``.
Second stage expression-dispatch Second Stage Expression-Dispatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The only special case is the ``HyExpression``, since we need to create different The only special case is the ``HyExpression``, since we need to create different
@ -300,7 +300,7 @@ properly handle that case as well (most likely by raising an ``Exception``).
If the String isn't known to Hy, it will default to create an ``ast.Call``, If the String isn't known to Hy, it will default to create an ``ast.Call``,
which will try to do a runtime call (in Python, something like ``foo()``). which will try to do a runtime call (in Python, something like ``foo()``).
Issues hit with Python AST Issues Hit with Python AST
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
Python AST is great; it's what's enabled us to write such a powerful project Python AST is great; it's what's enabled us to write such a powerful project
@ -351,7 +351,7 @@ into::
By forcing things into an ``ast.expr`` if we can, but the general idea holds. By forcing things into an ``ast.expr`` if we can, but the general idea holds.
Step 4: Python bytecode output and runtime Step 4: Python Bytecode Output and Runtime
------------------------------------------ ------------------------------------------
After we have a Python AST tree that's complete, we can try and compile it to After we have a Python AST tree that's complete, we can try and compile it to
@ -365,8 +365,8 @@ Hy Macros
.. _using-gensym: .. _using-gensym:
Using gensym for safer macros Using gensym for Safer Macros
------------------------------ -----------------------------
When writing macros, one must be careful to avoid capturing external variables When writing macros, one must be careful to avoid capturing external variables
or using variable names that might conflict with user code. or using variable names that might conflict with user code.
@ -447,13 +447,13 @@ Our final version of ``nif``, built with ``defmacro/g!`` becomes:
Checking macro arguments and raising exceptions Checking Macro Arguments and Raising Exceptions
----------------------------------------------- -----------------------------------------------
Hy Compiler Builtins Hy Compiler Built-Ins
==================== =====================
.. todo:: .. todo::
Write this. Write this.

14
docs/language/readermacros.rst
View File

@ -6,8 +6,8 @@
Reader Macros Reader Macros
============= =============
Reader macros gives LISP the power to modify and alter syntax on the fly. Reader macros gives Lisp the power to modify and alter syntax on the fly.
You don't want polish notation? A reader macro can easily do just that. Want You don't want Polish notation? A reader macro can easily do just that. Want
Clojure's way of having a regex? Reader macros can also do this easily. Clojure's way of having a regex? Reader macros can also do this easily.
@ -33,7 +33,7 @@ else. This is a problem reader macros are able to solve in a neat way.
=> #t(1 2 3) => #t(1 2 3)
(1, 2, 3) (1, 2, 3)
You could even do like clojure, and have a literal for regular expressions! You could even do it like Clojure and have a literal for regular expressions!
:: ::
@ -46,10 +46,10 @@ You could even do like clojure, and have a literal for regular expressions!
Implementation Implementation
============== ==============
``defreader`` takes a single character as symbol name for the reader macro, ``defreader`` takes a single character as symbol name for the reader macro;
anything longer will return an error. Implementation wise, ``defreader`` anything longer will return an error. Implementation-wise, ``defreader``
expands into a lambda covered with a decorator, this decorator saves the expands into a lambda covered with a decorator. This decorator saves the
lambda in a dict with its module name and symbol. lambda in a dictionary with its module name and symbol.
:: ::