From 997501bcc4eaf7fd896fec5ba0819fd620074b96 Mon Sep 17 00:00:00 2001 From: Kevin Yap Date: Sat, 6 Dec 2014 12:28:28 -0800 Subject: [PATCH 1/4] Fixes to language documentation - Use backticks consistently for inline code - Capitalize section headers and proper nouns - Minor grammatical fixes --- docs/language/api.rst | 299 ++++++++++++++++----------------- docs/language/cli.rst | 2 +- docs/language/core.rst | 46 ++--- docs/language/internals.rst | 32 ++-- docs/language/readermacros.rst | 14 +- 5 files changed, 194 insertions(+), 199 deletions(-) diff --git a/docs/language/api.rst b/docs/language/api.rst index 72d5b6b..515cb22 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -13,14 +13,14 @@ Theory of Hy Hy maintains, over everything else, 100% compatibility in both directions 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. - * Symbols in earmufs will be translated to the uppercased version of that - string. For example, `*foo*` will become `FOO`. + * Symbols in earmufs will be translated to the upper-cased version of that + string. For example, `foo` will become `FOO`. * UTF-8 entities will be encoded using `punycode `_ and prefixed with @@ -33,8 +33,8 @@ languages. versa. -Builtins -======== +Built-Ins +========= Hy features a number of special forms that are used to help generate 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 -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, @@ -69,7 +69,7 @@ indexation. Other arguments throw a compilation error. Access to unknown attributes throws an :exc:`AttributeError`. Access to 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 -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: .. code-block:: clj @@ -133,9 +133,9 @@ Examples: and --- -`and` form is used in logical expressions. It takes at least two parameters. If -all parameters evaluate to `True` the last parameter is returned. In any other -case the first false value will be returned. Examples of usage: +`and` is used in logical expressions. It takes at least two parameters. If all +parameters evaluate to `True`, the last parameter is returned. In any other +case, the first false value will be returned. Example usage: .. code-block:: clj @@ -165,7 +165,7 @@ case the first false value will be returned. Examples of usage: 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: .. code-block:: clj @@ -179,10 +179,10 @@ or `False`. assoc ----- -`assoc` form 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: `datastructure` -to be modified, `key` or `index` and `value`. If more than three parameters are -used it will associate in pairs. +`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 +structure` to be modified, `key` or `index` and `value`. If more than three +parameters are used, it will associate in pairs. Examples of usage: @@ -210,24 +210,21 @@ break ----- `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 as -the user enters `k`. +The following example has an infinite `while` loop that is terminated as soon +as the user enters `k`. .. code-block:: clj - (while True (if (= "k" (raw-input "? ")) - (break) + (while True (if (= "k" (raw-input "? ")) + (break) (print "Try again"))) cond ---- -`cond` macro can be used to build nested if-statements. - -The following example shows the relationship between the macro and the expanded -code: +`cond` can be used to build nested if-statements. The following example shows +the relationship between the macro and the expanded code: .. 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 greater than 5")] ... [True (print "value is something that it should not be")])) - + => (check-value 6) value is greater than 5 @@ -255,7 +252,7 @@ continue -------- `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. .. code-block:: clj @@ -289,10 +286,10 @@ the sequence based on a conditional expression. do / progn ---------- -the `do` and `progn` forms are used to evaluate each of their arguments and -return the last one. Return values from every other than the last argument are -discarded. It can be used in `lambda` or `list-comp` to perform more complex -logic as shown by one of the examples. +`do` and `progn` are used to evaluate each of their arguments and return the last +one. Return values from every other than the last argument are discarded. It can be +used in `lambda` or `list-comp` to perform more complex logic as shown by one of the +examples. Some example usage: @@ -306,9 +303,9 @@ Some example usage: ;; 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 - => (list-comp (do (side-effect x) - ... (if (< x 5) (* 2 x) - ... (* 4 x))) + => (list-comp (do (side-effect x) + ... (if (< x 5) (* 2 x) + ... (* 4 x))) ... (x (range 10))) [0, 2, 4, 6, 8, 20, 24, 28, 32, 36] @@ -316,9 +313,9 @@ Some example usage: 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: .. code-block:: clj @@ -335,7 +332,7 @@ example: 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 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 -parameters: `name` of the function to define, vector of `parameters` and the -`body` of the function: +parameters: the `name` of the function to define, a vector of `parameters`, +and the `body` of the function: .. code-block:: clj (defn name [params] body) -Parameters may have following keywords in front of them: +Parameters may have the following keywords in front of them: &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 parameter can be also given as a single item, in which case the default value is None. @@ -394,10 +391,10 @@ Parameters may have following keywords in front of them: 101.0 &key - + &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 arguments and their values. @@ -412,7 +409,7 @@ Parameters may have following keywords in front of them: parameter-1 1 &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. The following code example defines a function that can be given 0 to n @@ -463,8 +460,8 @@ defmain .. versionadded:: 0.10.1 The `defmain` macro defines a main function that is immediately called -with sys.argv as arguments if and only if this file is being executed -as a script. In other words this: +with ``sys.argv`` as arguments if and only if this file is being executed +as a script. In other words, this: .. code-block:: clj @@ -484,7 +481,7 @@ is the equivalent of:: if isinstance(retval, int): 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. (Python defaults to exit status 0 otherwise, which means everything's okay!) @@ -596,7 +593,7 @@ del File "", line 1, in 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 @@ -618,7 +615,7 @@ doto .. 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 @@ -664,11 +661,11 @@ first / car for -------- +--- `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 -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` 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 => (for [element [1 2 3]] (if (< element 3) - ... (print element) + ... (print element) ... (break)) ... (else (print "loop finished"))) 1 @@ -709,7 +706,7 @@ genexpr `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 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 an iterable that evaluates values one by one instead of evaluating them immediately. @@ -728,7 +725,7 @@ gensym .. 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. .. code-block:: clj @@ -746,10 +743,10 @@ without accidental variable name clashes. get --- -`get` form is used to access single elements in lists and dictionaries. `get` -takes two parameters, the `datastructure` and the `index` or `key` of the item. -It will then return the corresponding value from the dictionary or the list. -Example usages: +`get` is used to access single elements in lists and dictionaries. `get` takes +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. +Example usage: .. code-block:: clj @@ -772,11 +769,11 @@ global `global` can be used to mark a symbol as global. This allows the programmer to assign a value to a global symbol. Reading a global symbol does not require the -`global` keyword, 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 -on printed on another function. Without the `global` keyword, the second function -would thrown a `NameError`. +The following example shows how the global symbol `a` is assigned a value in a +function and is later on printed in another function. Without the `global` keyword, +the second function would have thrown a `NameError`. .. code-block:: clj @@ -793,29 +790,32 @@ would thrown a `NameError`. if / if-not ----------- -the `if` form is used to conditionally select code to be executed. It has to -contain the condition block and the block to be executed if the condition -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 -0.10.0*) is similar, but the first block after the test will be -executed when the test fails, while the other, conditional one, when -the test succeeds - opposite of the order of the `if` form. +.. versionadded:: 0.10.0 + if-not + +`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 +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 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: .. code-block:: clj (if (money-left? account) - (print "lets go shopping") - (print "lets go and work")) + (print "let's go shopping") + (print "let's go and work")) (if-not (money-left? account) - (print "lets go and work") - (print "lets go shopping")) + (print "let's go and work") + (print "let's go shopping")) -Truth values of Python objects are respected. Values `None`, `False`, zero of -any numeric type, empty sequence and empty dictionary are considered `False`. -Everything else is considered `True`. +Truth values of Python objects are respected. `None`, `False`, zero of any numeric +type, an empty sequence, and an empty dictionary are considered `False`. Everything else +is considered `True`. 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 lisp-if-not / lif-not -For those that prefer a more lisp-y if clause, we have lisp-if, or lif. This -*only* considers None/nil as false! All other values of python -"falseiness" are considered true. Conversely, we have lisp-if-not or lif-not, -in parallel to if / if-not, which reverses the comparison. +For those that prefer a more Lispy `if` clause, we have `lisp-if`, or `lif`. This +*only* considers `None`/`nil` as false! All other "false-ish" Python values are +considered true. Conversely, we have `lisp-if-not` and `lif-not` in parallel to +`if` and `if-not` which reverses the comparison. .. code-block:: clj @@ -851,7 +851,7 @@ in parallel to if / if-not, which reverses the comparison. => (lisp-if-not False "true" "false") "false" - ; And, same thing + ; Equivalent but shorter => (lif True "true" "false") "true" => (lif nil "true" "false") @@ -898,9 +898,9 @@ lambda / fn ----------- `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 -body of the function. lambda returns a new function. In the example an anonymous -function is defined and passed to another function for filtering output. +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 +anonymous function is defined and passed to another function for filtering output. .. code-block:: clj @@ -927,7 +927,7 @@ class methods docstrings. ... "Multiplies input by three and returns the result." ... (* 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 on function times_three: @@ -941,22 +941,22 @@ let --- `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: .. code-block:: clj - => (let [[x 5]] (print x) - ... (let [[x 6]] (print x)) + => (let [[x 5]] (print x) + ... (let [[x 6]] (print x)) ... (print x)) 5 6 5 -`let` macro takes two parameters: a vector defining `variables` and `body`, -which is being 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 -single variable, it is assigned value None, otherwise the supplied value is +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 +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 used. .. code-block:: clj @@ -971,7 +971,7 @@ list-comp `list-comp` performs list comprehensions. It takes two or three parameters. 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 -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: .. code-block:: clj @@ -990,9 +990,9 @@ conditional expression. Some examples: 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` -will be returned and vice-versa. Examples for usage: +will be returned and vice-versa. Example usage: .. code-block:: clj @@ -1009,8 +1009,8 @@ will be returned and vice-versa. Examples for usage: or -- -`or` form is used in logical expressions. It takes at least two parameters. It -will return the first non-false parameter. If no such value exist, the last +`or` is used in logical expressions. It takes at least two parameters. It will +return the first non-false parameter. If no such value exists, the last parameter will be returned. .. code-block:: clj @@ -1024,8 +1024,8 @@ parameter will be returned. => (and False 1 True False) 1 -.. note:: `or` shortcuts and stops evaluating parameters as soon as the first - true is encountered. +.. note:: `or` short-circuits and stops evaluating parameters as soon as the + first true value is encountered. .. code-block:: clj @@ -1036,7 +1036,7 @@ parameter will be returned. print ----- -the `print` form is used to output on screen. Example usage: +`print` is used to output on screen. Example usage: .. code-block:: clj @@ -1048,11 +1048,11 @@ the `print` form is used to output on screen. Example usage: quasiquote ---------- -`quasiquote` allows you to quote a form, but also to -selectively evaluate expressions, expressions inside a `quasiquote` -can be selectively evaluated using `unquote` (~). The evaluated form can -also be spliced using `unquote-splice` (~@). Quasiquote can be also written -using the backquote (`) symbol. +`quasiquote` allows you to quote a form, but also selectively evaluate +expressions. Expressions inside a `quasiquote` can be selectively evaluated +using `unquote` (~). The evaluated form can also be spliced using +`unquote-splice` (~@). Quasiquote can be also written using the backquote (`) +symbol. .. code-block:: clj @@ -1067,7 +1067,7 @@ using the backquote (`) symbol. 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 @@ -1129,13 +1129,11 @@ slice `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 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. -Third optional parameter is used to control step between the elements. +subset. If they are not supplied, default value of `None` will be used instead. +The third optional parameter is used to control step between the elements. -`slice` follows the same rules as the Python counterpart. Negative indecies are -counted starting from the end of the list. -Some examples of -usage: +`slice` follows the same rules as its Python counterpart. Negative indices are +counted starting from the end of the list. Some example usage: .. code-block:: clj @@ -1160,32 +1158,30 @@ usage: throw / raise ------------- -the `throw` or `raise` forms can be used to raise an Exception at runtime. - - -Example usage +The `throw` or `raise` forms can be used to raise an `Exception` at runtime. +Example usage: .. code-block:: clj (throw) ; re-rase the last exception - + (throw IOError) ; Throw an IOError - + (throw (IOError "foobar")) ; Throw an IOError("foobar") -`throw` can accept a single argument (an `Exception` class or instance), or -no arguments to re-raise the last Exception. +`throw` can accept a single argument (an `Exception` class or instance) or +no arguments to re-raise the last `Exception`. try --- -the `try` form is used to start a `try` / `catch` block. The form is used -as follows +The `try` form is used to start a `try` / `catch` block. The form is used +as follows: .. code-block:: clj @@ -1197,23 +1193,24 @@ as follows `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 -block during execution of `error-prone-function` then that catch block will -be executed. If no errors are raised the `else` block is executed. Regardless -if an error was raised or not, the `finally` block is executed as last. +block during execution of `error-prone-function`, that catch block 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 +was raised. unless ------ -`unless` macro is a shorthand for writing a if-statement that checks if the -given conditional is False. The following shows how the macro expands into code. +The `unless` macro is a shorthand for writing an `if` statement that checks if the +given conditional is `False`. The following shows the expansion of this macro. .. code-block:: clj (unless conditional statement) - (if conditional - None + (if conditional + None (do statement)) @@ -1256,8 +1253,8 @@ when ---- `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 -shows how the macro is expanded into code. +`True`. It is not possible to have an `else` block in a `when` macro. The following +shows the expansion of the macro. .. code-block:: clj @@ -1268,10 +1265,8 @@ shows how the macro is expanded into code. while ----- -`while` form is used to execute a single or more blocks as long as a condition -is being met. - -The following example will output "hello world!" on screen indefinitely: +`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: .. code-block:: clj @@ -1281,10 +1276,10 @@ The following example will output "hello world!" on screen indefinitely: with ---- -`with` is used to wrap execution of a block with a context manager. The 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 -context to an argument or ignore it completely, as shown below: +`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 +manner. The archetypical example of using `with` is when processing files. `with` +can bind context to an argument or ignore it completely, as shown below: .. code-block:: clj @@ -1306,12 +1301,12 @@ with-decorator -------------- `with-decorator` is used to wrap a function with another. The function -performing decoration should accept a single value, the function being -decorated and return a new function. `with-decorator` takes a minimum -of two parameters, the function performing decoration and the function -being decorated. More than one decorator function can be applied, they +performing the decoration should accept a single value: the function being +decorated, and return a new function. `with-decorator` takes a minimum +of two parameters: the function performing decoration and the function +being decorated. More than one decorator function can be applied; they 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. .. code-block:: clj @@ -1326,11 +1321,10 @@ are called just like a function call. (defn some-function [] ...) - -In the following example, `inc-decorator` is used to decorate function +In the following example, `inc-decorator` is used to decorate the function `addition` with a function that takes two parameters and calls the 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). .. code-block:: clj @@ -1356,8 +1350,7 @@ with-gensyms .. versionadded:: 0.9.12 -`with-gensym` form 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. .. code-block:: hy @@ -1381,11 +1374,11 @@ expands to: 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 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. .. code-block:: clj @@ -1416,5 +1409,5 @@ yield-from `yield-from` is used to call a subgenerator. This is useful if you want your coroutine to be able to delegate its processes to another -coroutine, say if using something fancy like +coroutine, say, if using something fancy like `asyncio `_. diff --git a/docs/language/cli.rst b/docs/language/cli.rst index 8eba855..e062f75 100644 --- a/docs/language/cli.rst +++ b/docs/language/cli.rst @@ -7,7 +7,7 @@ Command Line Interface hy -- -Command line options +Command Line Options ^^^^^^^^^^^^^^^^^^^^ .. cmdoption:: -c diff --git a/docs/language/core.rst b/docs/language/core.rst index fa9dc80..3a7c2df 100644 --- a/docs/language/core.rst +++ b/docs/language/core.rst @@ -1,10 +1,10 @@ -================= +======= Hy Core -================= +======= Core Functions -=============== +============== .. _butlast-fn: @@ -40,7 +40,7 @@ coll? 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 @@ -149,7 +149,7 @@ empty? 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 @@ -172,7 +172,8 @@ every? 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 @@ -196,7 +197,7 @@ float? Usage: ``(float? x)`` -Return True if x is a float. +Return `True` if x is a float. .. code-block:: hy @@ -214,7 +215,7 @@ even? Usage: ``(even? x)`` -Return True if x is even. +Return `True` if x is even. Raises ``TypeError`` if ``(not (numeric? x))``. @@ -278,7 +279,7 @@ instance? 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 @@ -303,7 +304,7 @@ integer? 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``. .. code-block:: hy @@ -324,7 +325,8 @@ interleave 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 @@ -362,7 +364,7 @@ iterable? 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`. .. code-block:: hy @@ -395,7 +397,7 @@ iterator? 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. Contrast with :ref:`iterable?-fn`. @@ -502,7 +504,7 @@ neg? 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))``. @@ -521,11 +523,11 @@ Raises ``TypeError`` if ``(not (numeric? x))``. .. _nil?-fn: nil? ------ +---- Usage: ``(nil? x)`` -Return True if x is nil/None. +Return `True` if x is `nil`/`None`. .. code-block:: hy @@ -554,7 +556,7 @@ none? Usage: ``(none? x)`` -Return True if x is None. +Return `True` if x is `None`. .. code-block:: hy @@ -614,7 +616,7 @@ numeric? 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``. .. code-block:: hy @@ -636,7 +638,7 @@ odd? Usage: ``(odd? x)`` -Return True if x is odd. +Return `True` if x is odd. Raises ``TypeError`` if ``(not (numeric? x))``. @@ -659,7 +661,7 @@ pos? 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))``. @@ -728,7 +730,7 @@ string? Usage: ``(string? x)`` -Return True if x is a string. +Return `True` if x is a string. .. code-block:: hy @@ -745,7 +747,7 @@ zero? Usage: ``(zero? x)`` -Return True if x is zero (0). +Return `True` if x is zero (0). .. code-block:: hy diff --git a/docs/language/internals.rst b/docs/language/internals.rst index 05df3c9..cc25efb 100644 --- a/docs/language/internals.rst +++ b/docs/language/internals.rst @@ -10,7 +10,7 @@ Internal Hy Documentation Hy Models ========= -Introduction to Hy models +Introduction to Hy Models ------------------------- 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 models, but only as a mixin for other classes. -Compound models +Compound Models --------------- 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, the :ref:`HyExpression` Python class isn't hashable). -Atomic models +Atomic Models ------------- In the input stream, double-quoted strings, respecting the Python @@ -115,7 +115,7 @@ strings. .. _hy_numeric_models: -Numeric models +Numeric Models ~~~~~~~~~~~~~~ ``hy.models.integer.HyInteger`` represents integer literals (using the @@ -217,7 +217,7 @@ from source to runtime. .. _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 @@ -238,7 +238,7 @@ on (directly), and it's what the compiler uses when it compiles Hy down. .. _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 @@ -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, 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 @@ -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 content. -Macro-expand +Macro-Expand ~~~~~~~~~~~~ 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 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 @@ -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``, 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 @@ -351,7 +351,7 @@ into:: 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 @@ -365,8 +365,8 @@ Hy Macros .. _using-gensym: -Using gensym for safer macros ------------------------------- +Using gensym for Safer Macros +----------------------------- When writing macros, one must be careful to avoid capturing external variables 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:: Write this. diff --git a/docs/language/readermacros.rst b/docs/language/readermacros.rst index a48ef36..f633f9e 100644 --- a/docs/language/readermacros.rst +++ b/docs/language/readermacros.rst @@ -6,8 +6,8 @@ Reader Macros ============= -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 +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 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) (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 ============== -``defreader`` takes a single character as symbol name for the reader macro, -anything longer will return an error. Implementation wise, ``defreader`` -expands into a lambda covered with a decorator, this decorator saves the -lambda in a dict with its module name and symbol. +``defreader`` takes a single character as symbol name for the reader macro; +anything longer will return an error. Implementation-wise, ``defreader`` +expands into a lambda covered with a decorator. This decorator saves the +lambda in a dictionary with its module name and symbol. :: From d657e5eb2db6259cd79179e1c9a13561a22d6a61 Mon Sep 17 00:00:00 2001 From: Kevin Yap Date: Sat, 6 Dec 2014 12:32:11 -0800 Subject: [PATCH 2/4] Fixes to contributor module documentation - Changed "Contrib" to "Contributor" - Fixed mismatched inline code in list* usage - Added missing hyperlink targets --- docs/contrib/anaphoric.rst | 4 ++-- docs/contrib/index.rst | 6 +++--- docs/contrib/loop.rst | 2 +- docs/contrib/multi.rst | 4 ++-- docs/language/core.rst | 15 +++++++++------ 5 files changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/contrib/anaphoric.rst b/docs/contrib/anaphoric.rst index 44d6bd1..4b42a58 100644 --- a/docs/contrib/anaphoric.rst +++ b/docs/contrib/anaphoric.rst @@ -46,7 +46,7 @@ ap-each-while Usage: ``(ap-each-while list pred body)`` Evaluate the form for each element where the predicate form returns -True. +`True`. .. code-block:: hy @@ -63,7 +63,7 @@ ap-map Usage: ``(ap-map form list)`` The anaphoric form of map works just like regular map except that -instead of a function object it takes a Hy form. The special name, +instead of a function object it takes a Hy form. The special name ``it`` is bound to the current object from the list in the iteration. .. code-block:: hy diff --git a/docs/contrib/index.rst b/docs/contrib/index.rst index 53dcf23..eda11f2 100644 --- a/docs/contrib/index.rst +++ b/docs/contrib/index.rst @@ -1,6 +1,6 @@ - -Contrib Modules Index -===================== +========================= +Contributor Modules Index +========================= Contents: diff --git a/docs/contrib/loop.rst b/docs/contrib/loop.rst index 84b37ea..d3d3c03 100644 --- a/docs/contrib/loop.rst +++ b/docs/contrib/loop.rst @@ -25,7 +25,7 @@ optimization (TCO) in their Hy code. allowing efficient structured programming. -- Wikipedia (http://en.wikipedia.org/wiki/Tail_call) - + Macros ====== diff --git a/docs/contrib/multi.rst b/docs/contrib/multi.rst index 91d8cfa..f308191 100644 --- a/docs/contrib/multi.rst +++ b/docs/contrib/multi.rst @@ -4,8 +4,8 @@ defmulti .. versionadded:: 0.10.0 -`defmulti` lets you arity-overload a function by the given number of -args and/or kwargs. Inspired by clojures take on `defn`. +`defmulti` lets you arity-overload a function by the given number of +args and/or kwargs. Inspired by Clojure's take on `defn`. .. code-block:: clj diff --git a/docs/language/core.rst b/docs/language/core.rst index 3a7c2df..742c274 100644 --- a/docs/language/core.rst +++ b/docs/language/core.rst @@ -419,6 +419,9 @@ Contrast with :ref:`iterable?-fn`. => (iterator? (iter {:a 1 :b 2 :c 3})) True + +.. _list*-fn: + list* ----- @@ -484,7 +487,7 @@ merge-with .. versionadded:: 0.10.1 -Usage: ``(merge-with f &rest maps) +Usage: ``(merge-with f &rest maps)`` Returns a map that consist of the rest of the maps joined onto first. If a key occurs in more than one map, the mapping(s) from the latter @@ -612,7 +615,7 @@ Raise ``ValueError`` if ``n`` is negative. .. _numeric?-fn: numeric? ---------- +-------- Usage: ``(numeric? x)`` @@ -680,7 +683,7 @@ Raises ``TypeError`` if ``(not (numeric? x))``. .. _second-fn: second -------- +------ Usage: ``(second coll)`` @@ -762,7 +765,7 @@ Return `True` if x is zero (0). Sequence Functions -======================= +================== Sequence functions can either create or operate on a potentially infinite sequence without requiring the sequence be fully realized in @@ -821,7 +824,7 @@ To get the Fibonacci number at index 9, (starting from 0): .. _cycle-fn: cycle ------- +----- Usage: ``(cycle coll)`` @@ -1156,7 +1159,7 @@ Return an iterator from ``coll`` as long as predicate, ``pred`` returns True. => (list (take-while neg? [ 1 2 3 -4 5])) [] -.. _zipwith: +.. _zipwith-fn: zipwith ------- From d50485710c069ab3001c89a71322e387c98a21e0 Mon Sep 17 00:00:00 2001 From: Kevin Yap Date: Sat, 6 Dec 2014 22:35:32 -0800 Subject: [PATCH 3/4] Change documentation code block language to Hy --- docs/language/core.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/language/core.rst b/docs/language/core.rst index 742c274..0d1a1b7 100644 --- a/docs/language/core.rst +++ b/docs/language/core.rst @@ -494,7 +494,7 @@ If a key occurs in more than one map, the mapping(s) from the latter (left-to-right) will be combined with the mapping in the result by calling ``(f val-in-result val-in-latter)``. -.. code-block:: clojure +.. code-block:: hy => (merge-with (fn [x y] (+ x y)) {"a" 10 "b" 20} {"a" 1 "c" 30}) {u'a': 11L, u'c': 30L, u'b': 20L} @@ -1171,7 +1171,7 @@ Usage: ``(zipwith fn coll ...)`` Equivalent to ``zip``, but uses a multi-argument function instead of creating a tuple. If ``zipwith`` is called with N collections, then ``fn`` must accept N arguments. -.. code-block:: clojure +.. code-block:: hy => (import operator) => (list (zipwith operator.add [1 2 3] [4 5 6])) From 8c0ac0862f74178c4355bcdd49713f89adf52aa5 Mon Sep 17 00:00:00 2001 From: Kevin Yap Date: Sat, 6 Dec 2014 22:05:52 -0800 Subject: [PATCH 4/4] 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 --- docs/contrib/anaphoric.rst | 6 +- docs/contrib/loop.rst | 4 +- docs/contrib/multi.rst | 4 +- docs/language/api.rst | 416 ++++++++++++++++++------------------- docs/language/cli.rst | 4 +- docs/language/core.rst | 147 +++++++------ docs/quickstart.rst | 2 +- docs/tutorial.rst | 8 +- 8 files changed, 292 insertions(+), 299 deletions(-) diff --git a/docs/contrib/anaphoric.rst b/docs/contrib/anaphoric.rst index 4b42a58..4ab30d9 100644 --- a/docs/contrib/anaphoric.rst +++ b/docs/contrib/anaphoric.rst @@ -24,8 +24,8 @@ ap-if Usage: ``(ap-if (foo) (print it))`` -Evaluate the first form for trutheyness, and bind it to ``it`` in both the -true and false branch. +Evaluates the first form for truthiness, and bind it to ``it`` in both the +true and false branches. .. _ap-each: @@ -46,7 +46,7 @@ ap-each-while Usage: ``(ap-each-while list pred body)`` Evaluate the form for each element where the predicate form returns -`True`. +``True``. .. code-block:: hy diff --git a/docs/contrib/loop.rst b/docs/contrib/loop.rst index d3d3c03..5dd9877 100644 --- a/docs/contrib/loop.rst +++ b/docs/contrib/loop.rst @@ -4,8 +4,8 @@ loop/recur .. versionadded:: 0.10.0 -The loop/recur macro gives programmers a simple way to use tail-call -optimization (TCO) in their Hy code. +The ``loop`` / ``recur`` macro gives programmers a simple way to use +tail-call optimization (TCO) in their Hy code. A tail call is a subroutine call that happens inside another procedure as its final action; it may produce a return value which diff --git a/docs/contrib/multi.rst b/docs/contrib/multi.rst index f308191..aa094cd 100644 --- a/docs/contrib/multi.rst +++ b/docs/contrib/multi.rst @@ -4,8 +4,8 @@ defmulti .. versionadded:: 0.10.0 -`defmulti` lets you arity-overload a function by the given number of -args and/or kwargs. Inspired by Clojure's take on `defn`. +``defmulti`` lets you arity-overload a function by the given number of +args and/or kwargs. Inspired by Clojure's take on ``defn``. .. code-block:: clj diff --git a/docs/language/api.rst b/docs/language/api.rst index 515cb22..7391367 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -2,7 +2,6 @@ Hy (the language) ================= - .. warning:: This is incomplete; please consider contributing to the documentation 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 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. * 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 `punycode `_ and prefixed with - `hy_`. For instance, `⚘` will become `hy_w7h`, `♥` will become `hy_g6h`, - and `i♥u` will become `hy_iu_t0x`. + ``hy_``. For instance, ``⚘`` will become ``hy_w7h``, ``♥`` will become + ``hy_g6h``, and ``i♥u`` will become ``hy_iu_t0x``. * Symbols that contain dashes will have them replaced with underscores. For - example, `render-template` will become `render_template`. This means that - symbols with dashes will shadow their underscore equivalents, and vice + example, ``render-template`` will become ``render_template``. This means + that symbols with dashes will shadow their underscore equivalents, and vice versa. @@ -45,8 +44,7 @@ behavior that's slightly unexpected in some situations. .. 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. For instance, @@ -55,17 +53,17 @@ For instance, (. foo bar baz [(+ 1 2)] frob) -Compiles down to +Compiles down to: .. code-block:: python foo.bar.baz[1 + 2].frob -`.` compiles its first argument (in the example, `foo`) as the object on -which to do the attribute dereference. It uses bare symbols as -attributes to access (in the example, `bar`, `baz`, `frob`), and -compiles the contents of lists (in the example, ``[(+ 1 2)]``) for -indexation. Other arguments throw a compilation error. +``.`` compiles its first argument (in the example, *foo*) as the object on +which to do the attribute dereference. It uses bare symbols as attributes +to access (in the example, *bar*, *baz*, *frob*), and compiles the contents +of lists (in the example, ``[(+ 1 2)]``) for indexation. Other arguments +throw a compilation error. Access to unknown attributes throws an :exc:`AttributeError`. Access to 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 -macro inserts each expression into the next expression’s first argument place. -The following code demonstrates this: +``->`` (or the *threading macro*) is used to avoid nesting of expressions. The +threading macro inserts each expression into the next expression's first argument +place. The following code demonstrates this: .. code-block:: clj @@ -88,9 +86,9 @@ The following code demonstrates this: ->> --- -`->>` or `threading tail macro` is similar to `threading macro` but instead of -inserting each expression into the next expression’s first argument, it -appends it as the last argument. The following code demonstrates this: +``->>`` (or the *threading tail macro*) is similar to the *threading macro*, but +instead of inserting each expression into the next expression's first argument, +it appends it as the last argument. The following code demonstrates this: .. code-block:: clj @@ -102,10 +100,10 @@ appends it as the last argument. The following code demonstrates this: 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. -Usage: `(apply fn-name [args] [kwargs])` +Usage: ``(apply fn-name [args] [kwargs])`` Examples: @@ -133,9 +131,9 @@ Examples: and --- -`and` is used in logical expressions. It takes at least two parameters. If all -parameters evaluate to `True`, the last parameter is returned. In any other -case, the first false value will be returned. Example usage: +``and`` is used in logical expressions. It takes at least two parameters. If +all parameters evaluate to ``True``, the last parameter is returned. In any +other case, the first false value will be returned. Example usage: .. code-block:: clj @@ -153,7 +151,7 @@ case, the first false value will be returned. Example usage: .. 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. .. code-block:: clj @@ -165,24 +163,24 @@ case, the first false value will be returned. Example usage: assert ------ -`assert` is used to verify conditions while the program is running. If the -condition is not met, an `AssertionError` is raised. The example usage: +``assert`` is used to verify conditions while the program is running. If the +condition is not met, an ``AssertionError`` is raised. Example usage: .. code-block:: clj (assert (= variable expected-value)) -Assert takes a single parameter, a conditional that evaluates to either `True` -or `False`. +``assert`` takes a single parameter, a conditional that evaluates to either +``True`` or ``False``. assoc ----- -`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 -structure` to be modified, `key` or `index` and `value`. If more than three -parameters are used, it will associate in pairs. +``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 +structure* to be modified, a *key* or *index*, and a *value*. If more than +three parameters are used, it will associate in pairs. Examples of usage: @@ -203,15 +201,15 @@ Examples of usage: ... (print collection)) [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` 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 -as the user enters `k`. +``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 +as the user enters *k*. .. code-block:: clj @@ -223,8 +221,8 @@ as the user enters `k`. cond ---- -`cond` can be used to build nested if-statements. The following example shows -the relationship between the macro and the expanded code: +``cond`` can be used to build nested ``if`` statements. The following example +shows the relationship between the macro and its expansion: .. code-block:: clj @@ -234,7 +232,7 @@ the relationship between the macro and the expanded code: (if condition-1 result-1 (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 @@ -251,9 +249,9 @@ As shown below only the first matching result block is executed. continue -------- -`continue` returns execution to the start of a loop. In the following example, -function `(side-effect1)` is called for each iteration. `(side-effect2)` -however is called only for every other value in the list. +``continue`` returns execution to the start of a loop. In the following example, +``(side-effect1)`` is called for each iteration. ``(side-effect2)``, however, +is only called on every other value in the list. .. code-block:: clj @@ -271,11 +269,11 @@ however is called only for every other value in the list. dict-comp --------- -`dict-comp` is used to create dictionaries. It takes three or four parameters. -The first two parameters are for controlling the return value -(key-value pair), while the third is used to select items from a sequence. The -fourth and optional parameter can be used to filter out some of the items in -the sequence based on a conditional expression. +``dict-comp`` is used to create dictionaries. It takes three or four parameters. +The first two parameters are for controlling the return value (key-value pair) +while the third is used to select items from a sequence. The fourth and optional +parameter can be used to filter out some of the items in the sequence based on a +conditional expression. .. code-block:: hy @@ -286,10 +284,10 @@ the sequence based on a conditional expression. do / progn ---------- -`do` and `progn` are used to evaluate each of their arguments and return the last -one. Return values from every other than the last argument are discarded. It can be -used in `lambda` or `list-comp` to perform more complex logic as shown by one of the -examples. +``do`` and `progn` are used to evaluate each of their arguments and return the +last one. Return values from every other than the last argument are discarded. +It can be used in ``lambda`` or ``list-comp`` to perform more complex logic as +shown in one of the following examples. Some example usage: @@ -309,14 +307,14 @@ Some example usage: ... (x (range 10))) [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` and `setv` are used to bind a value, object, or function to a symbol. For -example: +``def`` and ``setv`` are used to bind a value, object, or function to a symbol. +For example: .. code-block:: clj @@ -332,7 +330,7 @@ example: 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 attributes of the new class as two item vectors. @@ -363,9 +361,9 @@ below: defn / defun ------------ -`defn` and `defun` macros are used to define functions. They take three -parameters: the `name` of the function to define, a vector of `parameters`, -and the `body` of the function: +``defn`` and ``defun`` macros are used to define functions. They take three +parameters: the *name* of the function to define, a vector of *parameters*, +and the *body* of the function: .. 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 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 - value is None. + value is ``None``. .. code-block:: clj @@ -437,12 +435,11 @@ defn-alias / defun-alias .. versionadded:: 0.10.0 -The `defn-alias` and `defun-alias` macros are much like `defn`_ above, -with the difference that instead of defining a function with a single +The ``defn-alias`` and ``defun-alias`` macros are much like `defn`_, +with the distinction that instead of defining a function with a single name, these can also define aliases. Other than taking a list of -symbols for function names as the first parameter, `defn-alias` and -`defun-alias` have no other differences compared to `defn` and -`defun`. +symbols for function names as the first parameter, ``defn-alias`` and +``defun-alias`` are no different from ``defn`` and ``defun``. .. code-block:: clj @@ -459,7 +456,7 @@ defmain .. 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 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 okay!) -(Since (sys.exit 0) is not run explicitly in case of a non-integer -return from defmain, it's good to put (defmain) as the last bit of -code in your file.) +(Since ``(sys.exit 0)`` is not run explicitly in the case of a non-integer +return from ``defmain``, it's a good idea to put ``(defmain)`` as the last +piece of code in your file.) .. _defmacro: @@ -496,11 +493,11 @@ code in your file.) defmacro -------- -`defmacro` is used to define macros. The general format is -`(defmacro name [parameters] expr)`. +``defmacro`` is used to define macros. The general format is +``(defmacro name [parameters] expr)``. -The following example defines a macro that can be used to swap order of elements in -code, allowing the user to write code in infix notation, where operator is in +The following example defines a macro that can be used to swap order of elements +in code, allowing the user to write code in infix notation, where operator is in between the operands. .. code-block:: clj @@ -519,9 +516,9 @@ between the operands. defmacro-alias -------------- -`defmacro-alias` is used to define macros with multiple names -(aliases). The general format is `(defmacro-alias [names] [parameters] -expr)`. It creates multiple macros with the same parameter list and +``defmacro-alias`` is used to define macros with multiple names +(aliases). The general format is ``(defmacro-alias [names] [parameters] +expr)``. It creates multiple macros with the same parameter list and body, under the specified list of names. The following example defines two macros, both of which allow the user @@ -547,11 +544,11 @@ defmacro/g! .. versionadded:: 0.9.12 -`defmacro/g!` is a special version of `defmacro` that is used to -automatically generate :ref:`gensym` for any symbol that -starts with ``g!``. +``defmacro/g!`` is a special version of ``defmacro`` that is used to +automatically generate :ref:`gensym` for any symbol that starts with +``g!``. -So ``g!a`` would become ``(gensym "a")``. +For example, ``g!a`` would become ``(gensym "a")``. .. seealso:: @@ -562,7 +559,7 @@ defreader .. 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. .. code-block:: clj @@ -582,7 +579,7 @@ del .. versionadded:: 0.9.12 -`del` removes an object from the current namespace. +``del`` removes an object from the current namespace. .. code-block:: clj @@ -593,7 +590,7 @@ del File "", line 1, in 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 @@ -615,7 +612,7 @@ doto .. 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 @@ -634,7 +631,7 @@ doto eval ---- -`eval` evaluates a quoted expression and returns the value. +``eval`` evaluates a quoted expression and returns the value. .. code-block:: clj @@ -652,7 +649,7 @@ eval-when-compile 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 @@ -663,11 +660,11 @@ first / car for --- -`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 -`None` instead. The example code iterates over `collection` and -for each `element` in `collection` calls the `side-effect` -function with `element` as its argument: +``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 +``None`` instead. The example code iterates over *collection* and for each +*element* in *collection* calls the ``side-effect`` function with *element* +as its argument: .. code-block:: clj @@ -678,8 +675,9 @@ function with `element` as its argument: (for [element collection] (side-effect element) (else (side-effect-2))) -The optional `else` block is executed only if the `for` loop terminates -normally. If the execution is halted with `break`, the `else` does not execute. +The optional ``else`` block is only executed if the ``for`` loop terminates +normally. If the execution is halted with ``break``, the ``else`` block does +not execute. .. code-block:: clj @@ -703,12 +701,13 @@ normally. If the execution is halted with `break`, the `else` does not execute. genexpr ------- -`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 second is used to select items from a list. The third and optional +``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 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 -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. +conditional expression. ``genexpr`` is similar to ``list-comp``, except it +returns an iterable that evaluates values one by one instead of evaluating them +immediately. .. code-block:: hy @@ -725,8 +724,8 @@ gensym .. versionadded:: 0.9.12 -`gensym` is used to generate a unique symbol to allow writing macros -without accidental variable name clashes. +``gensym`` is used to generate a unique symbol that allows macros to be +written without accidental variable name clashes. .. code-block:: clj @@ -743,10 +742,10 @@ without accidental variable name clashes. get --- -`get` is used to access single elements in lists and dictionaries. `get` takes -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. -Example usage: +``get`` is used to access single elements in lists and dictionaries. ``get`` +takes 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. Example usage: .. code-block:: clj @@ -757,23 +756,23 @@ Example usage: bark two -.. note:: `get` raises a KeyError if a dictionary is queried for a non-existing - key. +.. note:: ``get`` raises a KeyError if a dictionary is queried for a + non-existing key. -.. note:: `get` raises an IndexError if a list or a tuple is queried for an index - that is out of bounds. +.. note:: ``get`` raises an IndexError if a list or a tuple is queried for an + index that is out of bounds. 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 -`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 -function and is later on printed in another function. Without the `global` keyword, -the second function would have thrown a `NameError`. +The following example shows how the global symbol ``a`` is assigned a value in a +function and is later on printed in another function. Without the ``global`` +keyword, the second function would have thrown a ``NameError``. .. code-block:: clj @@ -793,13 +792,14 @@ if / if-not .. versionadded:: 0.10.0 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 -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 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. +to ``True``. Optionally, it may contain a final block that is executed in case +the evaluation of the condition is ``False``. + +``if-not`` 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 ``if``. Example usage: @@ -813,9 +813,9 @@ Example usage: (print "let's go and work") (print "let's go shopping")) -Truth values of Python objects are respected. `None`, `False`, zero of any numeric -type, an empty sequence, and an empty dictionary are considered `False`. Everything else -is considered `True`. +Python truthiness is respected. ``None``, ``False``, zero of any numeric type, +an empty sequence, and an empty dictionary are considered ``False``; everything +else is considered ``True``. 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 lisp-if-not / lif-not -For those that prefer a more Lispy `if` clause, we have `lisp-if`, or `lif`. This -*only* considers `None`/`nil` as false! All other "false-ish" Python values are -considered true. Conversely, we have `lisp-if-not` and `lif-not` in parallel to -`if` and `if-not` which reverses the comparison. +For those that prefer a more Lispy ``if`` clause, we have ``lisp-if``, or +``lif``. This *only* considers ``None`` / ``nil`` to be false! All other +"false-ish" Python values are considered true. Conversely, we have +``lisp-if-not`` and ``lif-not`` in parallel to ``if`` and ``if-not`` which +reverses the comparison. .. code-block:: clj @@ -863,8 +864,8 @@ considered true. Conversely, we have `lisp-if-not` and `lif-not` in parallel to import ------ -`import` is used to import modules, like in Python. There are several forms -of import you can use. +``import`` is used to import modules, like in Python. There are several ways +that ``import`` can be used. .. code-block:: clj @@ -897,9 +898,9 @@ of import you can use. lambda / fn ----------- -`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 -body of the function. `lambda` returns a new function. In the following example, an +``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 +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. .. code-block:: clj @@ -917,7 +918,7 @@ anonymous function is defined and passed to another function for filtering outpu Dave 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. .. code-block:: clj @@ -940,8 +941,8 @@ This can be confirmed via Python's built-in ``help`` function:: let --- -`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 +``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 example showcases this behaviour: .. code-block:: clj @@ -953,10 +954,10 @@ example showcases this behaviour: 6 5 -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 +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 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. .. code-block:: clj @@ -968,7 +969,7 @@ used. 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 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 @@ -990,9 +991,9 @@ conditional expression. Some examples: not --- -`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` -will be returned and vice-versa. Example usage: +``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`` +will be returned, and vice-versa. Example usage: .. code-block:: clj @@ -1009,8 +1010,8 @@ will be returned and vice-versa. Example usage: or -- -`or` is used in logical expressions. It takes at least two parameters. It will -return the first non-false parameter. If no such value exists, the last +``or`` is used in logical expressions. It takes at least two parameters. It +will return the first non-false parameter. If no such value exists, the last parameter will be returned. .. code-block:: clj @@ -1024,7 +1025,7 @@ parameter will be returned. => (and False 1 True False) 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. .. code-block:: clj @@ -1036,24 +1037,23 @@ parameter will be returned. print ----- -`print` is used to output on screen. Example usage: +``print`` is used to output on screen. Example usage: .. code-block:: clj (print "Hello world!") -.. note:: `print` always returns None +.. note:: ``print`` always returns ``None``. quasiquote ---------- -`quasiquote` allows you to quote a form, but also selectively evaluate -expressions. Expressions inside a `quasiquote` can be selectively evaluated -using `unquote` (~). The evaluated form can also be spliced using -`unquote-splice` (~@). Quasiquote can be also written using the backquote (`) -symbol. - +``quasiquote`` allows you to quote a form, but also selectively evaluate +expressions. Expressions inside a ``quasiquote`` can be selectively evaluated +using ``unquote`` (``~``). The evaluated form can also be spliced using +``unquote-splice`` (``~@``). Quasiquote can be also written using the backquote +(`````) symbol. .. code-block:: clj @@ -1067,9 +1067,8 @@ symbol. quote ----- -`quote` returns the form passed to it without evaluating it. `quote` can -be alternatively written using the (') symbol - +``quote`` returns the form passed to it without evaluating it. ``quote`` can +alternatively be written using the apostrophe (``'``) symbol. .. code-block:: clj @@ -1084,11 +1083,11 @@ be alternatively written using the (') symbol 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 -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 @@ -1098,8 +1097,8 @@ The following example will import macros from `module-1` and `module-2`: rest / cdr ---------- -`rest` and `cdr` return the collection passed as an argument without the first -element: +``rest`` and ``cdr`` return the collection passed as an argument without the +first element: .. code-block:: clj @@ -1110,7 +1109,7 @@ element: 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 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 @@ -1126,13 +1125,13 @@ expression. 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 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. -The third optional parameter is used to control step between the elements. +subset. If they are not supplied, the default value of ``None`` will be used +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: .. code-block:: clj @@ -1158,8 +1157,8 @@ counted starting from the end of the list. Some example usage: throw / raise ------------- -The `throw` or `raise` forms can be used to raise an `Exception` at runtime. -Example usage: +The ``throw`` or ``raise`` forms can be used to raise an ``Exception`` at +runtime. Example usage: .. code-block:: clj @@ -1173,15 +1172,15 @@ Example usage: ; Throw an IOError("foobar") -`throw` can accept a single argument (an `Exception` class or instance) or -no arguments to re-raise the last `Exception`. +``throw`` can accept a single argument (an ``Exception`` class or instance) +or no arguments to re-raise the last ``Exception``. try --- -The `try` form is used to start a `try` / `catch` block. The form is used -as follows: +The ``try`` form is used to start a ``try`` / ``catch`` block. The form is +used as follows: .. code-block:: clj @@ -1191,19 +1190,19 @@ as follows: (else (print "no errors")) (finally (print "all done"))) -`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 -block during execution of `error-prone-function`, that catch block 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 +``try`` must contain at least one ``catch`` block, and may optionally include +an ``else`` or ``finally`` block. If an error is raised with a matching catch +block during the execution of ``error-prone-function``, that ``catch`` block +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 was raised. unless ------ -The `unless` macro is a shorthand for writing an `if` statement that checks if the -given conditional is `False`. The following shows the expansion of this macro. +The ``unless`` macro is a shorthand for writing an ``if`` statement that checks if +the given conditional is ``False``. The following shows the expansion of this macro. .. code-block:: clj @@ -1217,8 +1216,8 @@ given conditional is `False`. The following shows the expansion of this macro. unquote ------- -Within a quasiquoted form, `unquote` forces evaluation of a symbol. `unquote` -is aliased to the `~` symbol. +Within a quasiquoted form, ``unquote`` forces evaluation of a symbol. ``unquote`` +is aliased to the tilde (``~``) symbol. .. code-block:: clj @@ -1233,10 +1232,10 @@ is aliased to the `~` symbol. unquote-splice -------------- -`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 -unquoted contains an iterable value, as it "splices" that iterable into the -quasiquoted form. `unquote-splice` is aliased to the `~@` symbol. +``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 unquoted contains an iterable value, as it "splices" that iterable into +the quasiquoted form. ``unquote-splice`` is aliased to the ``~@`` symbol. .. code-block:: clj @@ -1248,13 +1247,12 @@ quasiquoted form. `unquote-splice` is aliased to the `~@` symbol. ;=> (u'+' 1L 2L 3L 4L) - when ---- -`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 -shows the expansion of the macro. +``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 shows the expansion of the macro. .. code-block:: clj @@ -1262,24 +1260,25 @@ shows the expansion of the macro. (if conditional (do statement)) + while ----- -`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: +``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: .. code-block:: clj - (while True (print "hello world!")) + (while True (print "Hello world!")) 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 -manner. The archetypical example of using `with` is when processing files. `with` -can bind context to an argument or ignore it completely, as shown below: +manner. The archetypical example of using ``with`` is when processing files. +``with`` can bind context to an argument or ignore it completely, as shown below: .. 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) -The following example will open file `NEWS` and print its content on screen. The -file is automatically closed after it has been processed. +The following example will open the ``NEWS`` file and print its content to the +screen. The file is automatically closed after it has been processed. .. code-block:: clj @@ -1300,9 +1299,9 @@ file is automatically closed after it has been processed. 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 -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 being decorated. More than one decorator function can be applied; they 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 [] ...) -In the following example, `inc-decorator` is used to decorate the function -`addition` with a function that takes two parameters and calls the +In the following example, ``inc-decorator`` is used to decorate the function +``addition`` with a function that takes two parameters and calls the decorated function with values that are incremented by 1. When -the decorated `addition` is called with values 1 and 1, the end result -will be 4 (1+1 + 1+1). +the decorated ``addition`` is called with values 1 and 1, the end result +will be 4 (``1+1 + 1+1``). .. code-block:: clj @@ -1350,7 +1349,8 @@ with-gensyms .. 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 @@ -1374,11 +1374,11 @@ expands to: 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 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. .. code-block:: clj @@ -1407,7 +1407,7 @@ yield-from **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 coroutine, say, if using something fancy like `asyncio `_. diff --git a/docs/language/cli.rst b/docs/language/cli.rst index e062f75..6670d0c 100644 --- a/docs/language/cli.rst +++ b/docs/language/cli.rst @@ -63,7 +63,7 @@ Command Line Options hyc --- -Command line options +Command Line Options ^^^^^^^^^^^^^^^^^^^^ .. cmdoption:: file[, fileN] @@ -94,7 +94,7 @@ hy2py .. versionadded:: 0.10.1 -Command line options +Command Line Options ^^^^^^^^^^^^^^^^^^^^ .. cmdoption:: -s diff --git a/docs/language/core.rst b/docs/language/core.rst index 0d1a1b7..916995e 100644 --- a/docs/language/core.rst +++ b/docs/language/core.rst @@ -13,7 +13,7 @@ butlast 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 @@ -40,7 +40,7 @@ coll? 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 @@ -61,7 +61,7 @@ cons Usage: ``(cons a b)`` -Returns a fresh :ref:`cons cell ` with car `a` and cdr `b`. +Returns a fresh :ref:`cons cell ` with car *a* and cdr *b*. .. code-block:: hy @@ -81,7 +81,7 @@ cons? Usage: ``(cons? foo)`` -Checks whether ``foo`` is a :ref:`cons cell `. +Checks whether *foo* is a :ref:`cons cell `. .. code-block:: hy @@ -103,9 +103,8 @@ dec Usage: ``(dec x)`` -Return one less than x. Equivalent to ``(- x 1)``. - -Raises ``TypeError`` if ``(not (numeric? x))``. +Returns one less than *x*. Equivalent to ``(- x 1)``. Raises ``TypeError`` +if ``(not (numeric? x))``. .. code-block:: hy @@ -128,8 +127,8 @@ disassemble Usage: ``(disassemble tree &optional [codegen false])`` -Dump the Python AST for given Hy ``tree`` to standard output. If *codegen* -is ``true`` function prints Python code instead. +Dump the Python AST for given Hy *tree* to standard output. If *codegen* +is ``True``, the function prints Python code instead. .. code-block:: hy @@ -149,7 +148,7 @@ empty? 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 @@ -172,8 +171,8 @@ every? 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. +Returns ``True`` if ``(pred x)`` is logical true for every *x* in *coll*, +otherwise ``False``. Return ``True`` if *coll* is empty. .. code-block:: hy @@ -197,7 +196,7 @@ float? Usage: ``(float? x)`` -Return `True` if x is a float. +Returns ``True`` if *x* is a float. .. code-block:: hy @@ -215,9 +214,8 @@ even? Usage: ``(even? x)`` -Return `True` if x is even. - -Raises ``TypeError`` if ``(not (numeric? x))``. +Returns ``True`` if *x* is even. Raises ``TypeError`` if +``(not (numeric? x))``. .. code-block:: hy @@ -238,7 +236,7 @@ identity Usage: ``(identity x)`` -Returns argument supplied to the function +Returns the argument supplied to the function. .. code-block:: hy @@ -256,9 +254,8 @@ inc Usage: ``(inc x)`` -Return one more than x. Equivalent to ``(+ x 1)``. - -Raises ``TypeError`` if ``(not (numeric? x))``. +Returns one more than *x*. Equivalent to ``(+ x 1)``. Raises ``TypeError`` +if ``(not (numeric? x))``. .. code-block:: hy @@ -277,9 +274,9 @@ Raises ``TypeError`` if ``(not (numeric? x))``. 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 @@ -304,7 +301,7 @@ integer? 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``. .. code-block:: hy @@ -325,7 +322,7 @@ interleave 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. .. code-block:: hy @@ -346,7 +343,7 @@ interpose 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 @@ -364,7 +361,7 @@ iterable? 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`. .. code-block:: hy @@ -397,9 +394,9 @@ iterator? Usage: ``(iterator? x)`` -Return `True` if x is an iterator. Iterators are objects that return -themselves as an iterator when ``(iter x)`` is called. -Contrast with :ref:`iterable?-fn`. +Returns ``True`` if *x* is an iterator. Iterators are objects that return +themselves as an iterator when ``(iter x)`` is called. Contrast with +:ref:`iterable?-fn`. .. code-block:: hy @@ -427,7 +424,7 @@ list* 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. .. code-block:: hy @@ -453,7 +450,7 @@ macroexpand Usage: ``(macroexpand form)`` -Returns the full macro expansion of form. +Returns the full macro expansion of *form*. .. code-block:: hy @@ -472,7 +469,7 @@ macroexpand-1 Usage: ``(macroexpand-1 form)`` -Returns the single step macro expansion of form. +Returns the single step macro expansion of *form*. .. code-block:: hy @@ -507,9 +504,8 @@ neg? Usage: ``(neg? x)`` -Return `True` if x is less than zero (0). - -Raises ``TypeError`` if ``(not (numeric? x))``. +Returns ``True`` if *x* is less than zero. Raises ``TypeError`` if +``(not (numeric? x))``. .. code-block:: hy @@ -530,7 +526,7 @@ nil? Usage: ``(nil? x)`` -Return `True` if x is `nil`/`None`. +Returns ``True`` if *x* is ``nil`` / ``None``. .. code-block:: hy @@ -559,7 +555,7 @@ none? Usage: ``(none? x)`` -Return `True` if x is `None`. +Returns ``True`` if *x* is ``None``. .. code-block:: hy @@ -585,9 +581,9 @@ nth 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). -Raise ``ValueError`` if ``n`` is negative. +Raises ``ValueError`` if *n* is negative. .. code-block:: hy @@ -619,8 +615,8 @@ numeric? Usage: ``(numeric? x)`` -Return `True` if x is a numeric, as defined in the Python -numbers module class ``numbers.Number``. +Returns ``True`` if *x* is a numeric, as defined in Python's +``numbers.Number`` class. .. code-block:: hy @@ -641,9 +637,8 @@ odd? Usage: ``(odd? x)`` -Return `True` if x is odd. - -Raises ``TypeError`` if ``(not (numeric? x))``. +Returns ``True`` if *x* is odd. Raises ``TypeError`` if +``(not (numeric? x))``. .. code-block:: hy @@ -664,9 +659,8 @@ pos? Usage: ``(pos? x)`` -Return `True` if x is greater than zero (0). - -Raises ``TypeError`` if ``(not (numeric? x))``. +Returns ``True`` if *x* is greater than zero. Raises ``TypeError`` +if ``(not (numeric? x))``. .. code-block:: hy @@ -687,8 +681,7 @@ second Usage: ``(second coll)`` -Return the second member of ``coll``. Equivalent to -``(get coll 1)`` +Returns the second member of *coll*. Equivalent to ``(get coll 1)``. .. code-block:: hy @@ -705,8 +698,8 @@ some Usage: ``(some pred coll)`` -Return the first logical true value of ``(pred x)`` for any ``x`` in -``coll``, otherwise ``nil``. Return ``nil`` if ``coll`` is empty. +Returns the first logically-true value of ``(pred x)`` for any ``x`` in +*coll*, otherwise ``nil``. Return ``nil`` if *coll* is empty. .. code-block:: hy @@ -733,7 +726,7 @@ string? Usage: ``(string? x)`` -Return `True` if x is a string. +Returns ``True`` if *x* is a string. .. code-block:: hy @@ -750,7 +743,7 @@ zero? Usage: ``(zero? x)`` -Return `True` if x is zero (0). +Returns ``True`` if *x* is zero. .. code-block:: hy @@ -828,7 +821,7 @@ cycle Usage: ``(cycle coll)`` -Return an infinite iterator of the members of coll. +Returns an infinite iterator of the members of coll. .. code-block:: clj @@ -846,7 +839,7 @@ distinct 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 @@ -867,8 +860,8 @@ drop Usage: ``(drop n coll)`` -Return an iterator, skipping the first ``n`` members of ``coll`` -Raises ``ValueError`` if ``n`` is negative. +Returns an iterator, skipping the first *n* members of *coll*. +Raises ``ValueError`` if *n* is negative. .. code-block:: hy @@ -892,7 +885,8 @@ drop-last 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 @@ -917,8 +911,7 @@ drop-while Usage: ``(drop-while pred coll)`` -Return an iterator, skipping members of ``coll`` until ``pred`` -is False. +Returns an iterator, skipping members of *coll* until *pred* is ``False``. .. code-block:: hy @@ -939,7 +932,7 @@ filter 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`. @@ -960,7 +953,7 @@ flatten 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. .. code-block:: hy @@ -979,7 +972,7 @@ iterate 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 @@ -997,10 +990,9 @@ read Usage: ``(read &optional [from-file eof])`` -Reads the next hy expression from `from-file` (defaults to `sys.stdin`), and -can take a single byte as EOF (defaults to an empty string). -Raises an `EOFError` if `from-file` ends before a complete expression can be -parsed. +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). Raises ``EOFError`` +if *from-file* ends before a complete expression can be parsed. .. code-block:: hy @@ -1044,8 +1036,8 @@ remove Usage: ``(remove pred coll)`` -Return an iterator from ``coll`` with elements that pass the -predicate, ``pred``, removed. +Returns an iterator from *coll* with elements that pass the +predicate, *pred*, removed. See also :ref:`filter-fn`. @@ -1069,7 +1061,7 @@ repeat Usage: ``(repeat x)`` -Return an iterator (infinite) of ``x``. +Returns an iterator (infinite) of ``x``. .. code-block:: hy @@ -1084,7 +1076,7 @@ repeatedly Usage: ``(repeatedly fn)`` -Return an iterator by calling ``fn`` repeatedly. +Returns an iterator by calling *fn* repeatedly. .. code-block:: hy @@ -1101,8 +1093,8 @@ take Usage: ``(take n coll)`` -Return an iterator containing the first ``n`` members of ``coll``. -Raises ``ValueError`` if ``n`` is negative. +Returns an iterator containing the first *n* members of *coll*. +Raises ``ValueError`` if *n* is negative. .. code-block:: hy @@ -1122,7 +1114,7 @@ take-nth 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 @@ -1146,7 +1138,7 @@ take-while 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 @@ -1168,8 +1160,9 @@ zipwith Usage: ``(zipwith fn coll ...)`` -Equivalent to ``zip``, but uses a multi-argument function instead of creating a tuple. -If ``zipwith`` is called with N collections, then ``fn`` must accept N arguments. +Equivalent to ``zip``, but uses a multi-argument function instead of creating +a tuple. If ``zipwith`` is called with N collections, then *fn* must accept +N arguments. .. code-block:: hy diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 5ed70e0..1809a1f 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -27,7 +27,7 @@ Quickstart 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:: diff --git a/docs/tutorial.rst b/docs/tutorial.rst index dd71d26..1134420 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -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 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 -for "true"--that's because true will always be true, so if we get this -far, we'll always run that one! +for ``true`` -- that's because ``true`` will always be true, so if we get +this far, we'll always run that one! You might notice above that if you have code like: @@ -325,7 +325,7 @@ example: (os.mkdir "/tmp/somedir/anotherdir") (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 @@ -488,7 +488,7 @@ Protips! ======== 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. The threading macro inserts each expression into the next expression's first