From 9c31e34a264e4db02b7d3e563a4ac9105fd654ee Mon Sep 17 00:00:00 2001 From: Tuukka Turto Date: Sat, 6 Jul 2013 23:43:47 +0300 Subject: [PATCH] documentation for builtins relates #18 --- docs/language/api.rst | 158 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) diff --git a/docs/language/api.rst b/docs/language/api.rst index 0e58402..03623da 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -75,6 +75,7 @@ case the first false value will be returned. Examples of usage: I can has False False + assert ------ @@ -88,6 +89,7 @@ condition is not met, an `AssertionError` is raised. The example usage: Assert takes a single parameter, a conditional that evaluates to either `True` or `False`. + assoc ----- @@ -111,6 +113,7 @@ Examples of usage: .. note:: `assoc` modifies the datastructure in place and returns `None`. + break ----- @@ -144,6 +147,7 @@ however is called only for every other value in the list. (continue)) (side-effect2 x))) + do / progn ---------- @@ -176,10 +180,48 @@ Some example usage: def / setf / setv ----------------- +`def`, `setv` and `setf` are used to bind value, object or a function to a +symbol. For example: + +.. code-block:: clj + + => (def names ["Alice" "Bob" "Charlie"] + => (print names) + [u'Alice', u'Bob', u'Charlie'] + + => (setf counter (fn [collection item] (.count collection item))) + => (counter [1 2 3 4 5 2 3] 2) + 2 + defclass -------- +new classes are declared with `defclass`. It can takes two optional parameters: +a vector defining a possible super class and another vector containing +attributes of the new class as two item vectors. + +.. code-block:: clj + + (defclass class-name [super-class] + [[attribute value]]) + +Both values and functions can be bound on the new class as shown by the example +below: + +.. code-block:: clj + + => (defclass Cat [] + ... [[age None] + ... [colour "white"] + ... [speak (fn [self] (print "Meow"))]]) + + => (def spot (Cat)) + => (setv spot.colour "Black") + 'Black' + => (.speak spot) + Meow + defmacro -------- @@ -200,6 +242,19 @@ eval-when-compile foreach ------- +`foreach` is used to call a function for each element in a list or vector. +Results are discarded and None is returned instead. Example code iterates over +collection and calls side-effect to each element in the collection: + +.. code-block:: clj + + ;; assuming that (side-effect) is a function that takes a single parameter + (foreach [element collection] (side-effect element)) + + ;; foreach can have an optional else block + (foreach [element collection] (side-effect element) + (else (side-effect2 element))) + get --- @@ -224,6 +279,7 @@ Example usages: .. note:: `get` raises an IndexError if a list is queried for an index that is out of bounds. + global ------ @@ -283,10 +339,51 @@ of import you can use. kwapply ------- +`kwapply` can be used to supply keyword arguments to a function. + +For example: + +.. code-block:: clj + + => (defn rent-car [&kwargs kwargs] + ... (cond ((in :brand kwargs) (print "brand:" (:brand kwargs))) + ... ((in :model kwargs) (print "model:" (:model kwargs))))) + + => (kwapply (rent-car) {:model "T-Model"}) + model: T-Model + + => (defn total-purchase [price amount &optional [fees 1.05] [vat 1.1]] + ... (* price amount fees vat)) + + => (total-purchase 10 15) + 173.25 + + => (kwapply (total-purchase 10 15) {"vat" 1.05}) + 165.375 + 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. + +.. code-block:: clj + + => (def people [{:name "Alice" :age 20} + ... {:name "Bob" :age 25} + ... {:name "Charlie" :age 50} + ... {:name "Dave" :age 5}]) + + => (defn display-people [people filter] + ... (foreach [person people] (if (filter person) (print (:name person))))) + + => (display-people people (fn [person] (< (:age person) 25))) + Alice + Dave + list-comp --------- @@ -309,6 +406,7 @@ conditional expression. Some examples: => (list-comp (* x 2) [x collection] (< x 5)) [0, 2, 4, 6, 8] + not --- @@ -374,6 +472,7 @@ the `print` form is used to output on screen. Example usage: .. note:: `print` always returns None + require ------- @@ -469,16 +568,75 @@ The following example will output "hello world!" on screen indefinetely: (while True (print "hello world!")) + 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: + +.. code-block:: clj + + (with [arg (expr)] block) + + (with [(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. + +.. code-block:: clj + + (with [f (open "NEWS")] (print (.read f))) + 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 two parameters, the function performing +decoration and the function being decorated. + +In the following example, `inc-decorator` is used to decorate 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 will be 4 (1+1 + 1+1). + +.. code-block:: clj + + => (defn inc-decorator [func] + ... (fn [value-1 value-2] (func (+ value-1 1) (+ value-2 1)))) + => (with-decorator inc-decorator (defn addition [a b] (+ a b))) + => (addition 1 1) + 4 + yield ----- +`yield` is used to create a generator object, that returns 1 or more values. +The generator is iterable and therefore can be used in loops, list +comprehensions and other similar constructs. +Especially the second example shows how generators can be used to generate +infinite series without consuming infinite amount of memory. +.. code-block:: clj + + => (defn multiply [bases coefficients] + ... (foreach [(, base coefficient) (zip bases coefficients)] + ... (yield (* base coefficient)))) + + => (multiply (range 5) (range 5)) + + + => (list-comp value [value (multiply (range 10) (range 10))]) + [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] + + => (import random) + => (defn random-numbers [low high] + ... (while True (yield (.randint random low high)))) + => (list-comp x [x (take 15 (random-numbers 1 50))])]) + [7, 41, 6, 22, 32, 17, 5, 38, 18, 38, 17, 14, 23, 23, 19]