lfe_clj.txt

lfe_clj(3)                                                          lfe_clj(3)



NAME
       clj - LFE Clojure interface library.

SYNOPSIS
       This  module  provides Clojure-inspired functions and macros for use in
       LFE.

EXPORTS
       N.B.  Instead of making fully-qualified calls to  the  macros  exported
       from  clj,  you  may  (include-lib "lfe/include/clj.lfe") and then call
       them directly, e.g.

              (include-lib "lfe/include/clj.lfe")

              (-> 2 (+ 2) (=:= 4)) ; 'true

   Function Macros
       (defn name [arg ...] {{doc-string}} ...)

       (defn {{doc-string}} ([argpat ...] ...))

       Define and automatically export a function.

       (defn- name [arg ...] {{doc-string}} ...)

       (defn- {{doc-string}} ([argpat ...] ...))

       Equivalent to defun.

       (fn (arg ...) ...)

       Equivalent to lambda.

   Threading Macros
       Note: The original versions were copied from Tim Dysinger’s lfesl  repo
       here:

              https://github.com/lfex/lfesl/blob/master/include/thread.lfe

       They have since been modified to be safely exportable.

       (-> ...)

       Thread first.

       Example usage, demonstrating ordering:

              > (set o '(#(a 1) #(b 2) #(c 3)))
              (#(a 1) #(b 2) #(c 3))
              > (clj:-> o
              >         (++ '(#(d 4)))
              >         (++ '(#(e 5)))
              >         (++ '(#(f 6))))
              (#(a 1) #(b 2) #(c 3) #(d 4) #(e 5) #(f 6))

       Note that the use of -> in this example results in each successive val‐
       ue being appended to the input list.

       Another example showing how this works:

              > (lists:sublist
              >   (lists:reverse
              >     (lists:sort
              >       (lists:merge
              >         (string:tokens
              >           (string:to_upper "a b c d e")
              >           " ")
              >         '("X" "F" "L"))))
              >   2 3)
              ("L" "F" "E")

       Can be rewritten as this:

              > (clj:-> "a b c d e"
              >         (string:to_upper)
              >         (string:tokens " ")
              >         (lists:merge '("X" "F" "L"))
              >         (lists:sort)
              >         (lists:reverse)
              >         (lists:sublist 2 3))
              ("L" "F" "E")

       (->> ...)

       Thread last.

       Example usage, demonstrating ordering:

              > (set o '(#(a 1) #(b 2) #(c 3)))
              (#(a 1) #(b 2) #(c 3))
              > (clj:->> o
              >          (++ '(#(d 4)))
              >          (++ '(#(e 5)))
              >          (++ '(#(f 6))))
              (#(f 6) #(e 5) #(d 4) #(a 1) #(b 2) #(c 3))

       Note that the use of ->> in this example  results  in  each  successive
       value being prepended to the input list.

       Another example showing how this:

              > (lists:foldl #'+/2 0
              >   (clj:take 10
              >     (lists:filter
              >       (clj:comp #'clj:even?/1 #'clj:round/1)
              >       (lists:map
              >         (lambda (x)
              >           (math:pow x 2))
              >         (clj:seq 42)))))
              1540.0

       Can be rewritten as this:

              > (clj:->> (clj:seq 42)
              >          (lists:map (lambda (x) (math:pow x 2)))
              >          (lists:filter (clj:comp #'clj:even?/1 #'clj:round/1))
              >          (clj:take 10)
              >          (lists:foldl #'+/2 0))
              1540.0

       (as-> expr name . sexps)

       Bind  name  to  expr, evaluate the first sexp in the lexical context of
       that binding, then bind name to that result, repeating for each succes‐
       sive sexp in sexps, returning the result of the last sexp.

       (cond-> expr . clauses)

       Given  an  expression  and  a set of test/sexp pairs, thread x (via ->)
       through each sexp  for  which  the  corresponding  test  expression  is
       truthy,  i.e. neither  'false  nor  'undefined.  Note that, unlike cond
       branching, cond-> threading does not  short  circuit  after  the  first
       truthy test expression.

       (cond->> expr . clauses)

       Given  an  expression  and a set of test/sexp pairs, thread x (via ->>)
       through each sexp  for  which  the  corresponding  test  expression  is
       truthy,  i.e. neither  'false  nor  'undefined.  Note that, unlike cond
       branching, cond->> threading does not short  circuit  after  the  first
       truthy test expression.

       (some-> x . sexps)

       When  x  is not 'undefined, thread it into the first sexp (via ->), and
       when that result is not 'undefined, through the next, etc.

       (some->> x . sexps)

       When x is not 'undefined, thread it into the first sexp (via ->>),  and
       when that result is not 'undefined, through the next, etc.

   Conditional Macros
       (if-let ((patt test)) then {{else}})

       If test evaluates to anything other than 'false or 'undefined, evaluate
       then with patt bound to the value of test, otherwise else, if supplied,
       else 'undefined.

       (iff-let ((patt test)) . body)

       When test evaluates to anything other than 'false or 'undefined, evalu‐
       ate body with patt bound to the value of test, otherwise return  'unde‐
       fined.

       (condp pred expr . clauses)

       Given  a  binary  predicate,  an expression and a set of clauses of the
       form:

              test-expr result-expr

              test-expr >> result-fn

       where result-fn is a unary function, if (pred test-expr  expr)  returns
       anything other than 'undefined or 'false, the clause is a match.

       If  a  binary  clause matches, return result-expr.  If a ternary clause
       matches, call result-fn with the result of the predicate and return the
       result.

       If no clause matches and a single default expression is given after the
       clauses, return it.  If no default expression is given  and  no  clause
       matches, throw a no-matching-clause error.

       (if-not test then)

       (if-not test then else)

       If  test  evaluates  to 'false or 'undefined, evaluate and return then,
       otherwise else, if supplied, else 'undefined.

       (iff test . body)

       Like Clojure’s when.  If test evaluates to anything other  than  'false
       or 'undefined, evaluate body in an implicit progn.

       (when-not test . body)

       If test evaluates to 'false or 'undefined, evaluate body in an implicit
       progn.  Otherwise return 'undefined.

       (not= x)

       (not= x y)

       (not= x y . more)

       Same as (not (== ...)).

   Predicate Macros
       Allowed in guards, unless otherwise stated.

       (tuple? x)

       Return 'true if x is a tuple.

       (atom? x)

       Return 'true if x is an atom.

       (binary? x)

       Return 'true if x is a binary.

       (bitstring? x)

       Return 'true if x is a bitstring.

       (boolean? x)

       (bool? x)

       Return 'true if x is a boolean.

       (float? x)

       Return 'true if x is a float.

       (function? f)

       (func? f)

       Return 'true if x is a function.

       (function? f n)

       (func? f n)

       Return 'true if f is an n-ary function.

       (integer? x)

       (int? x)

       Return 'true if x is an integer.

       (number? x)

       Return 'true if x is a number.

       (record? x record-tag)

       (record? x record-tag size)

       Return 'true if x is a tuple and its first element is  record-tag.   If
       size is given, check that x is a record-tag record of size size.

       N.B.  record?/2 may yield unexpected results, due to difference between
       the Erlang and LFE  compilers.   As  such,  whenever  possible,  prefer
       record?/3."

       (reference? x)

       Return 'true if x is a reference.

       (map? x)

       Return  'true if x is a map.  Return 'false on versions of Erlang with‐
       out maps.

       (undefined? x)

       (undef? x)

       Return 'true if x is the atom 'undefined.

       (nil? x)

       Return 'true if x is the atom 'nil or the empty list.

       (true? x)

       Return 'true if x is the atom 'true.

       (false? x)

       Return 'true if x is the atom 'false.

       (falsy? x)

       Return 'true if x is one of the atoms 'false and 'undefined.

       (odd? x)

       Return 'true if x is odd.

       (even? x)

       Return 'true if x is even.

       (zero? x)

       Return 'true if x is zero.

       (pos? x)

       Return 'true if x is greater than zero.

       (neg? x)

       Return 'true if x is less than zero.

       (identical? x)

       Return 'true if x is exactly equal to y.

   Other Macros
       (str x1, x2 ... xn)

       Given arbitrary number of arguments, return a string consisting of each
       of their string representations.

       N.B.   Because Erlang characters are represented as integers, this will
       not work for chars, e.g. #\a, which will be  presented  in  the  return
       value as its integer value, i.e. "97".

              > (clj:str #\a "bc")
              "97bc"
              > (clj:str "a" "bc")
              "abc"

       (lazy-seq)

       (lazy-seq seq)

       Return  a  (possibly infinite) lazy sequence from a given lazy sequence
       seq or a finite lazy sequence from given list seq.  A lazy sequence  is
       treated  as  finite if at any iteration it produces the empty list, in‐
       stead of a cons cell with data as the head and a nullary  function  for
       the next iteration as the tail.

       (conj coll . xs)

       conj[oin]  a value onto an existing collection.  Prepend to a list, ap‐
       pend to a tuple, and merge maps.

   Clojure-inspired if Macro
       (if test then)

       (if test then else)

       If test evaluates to anything other than 'false or  'undefined,  return
       then, otherwise else, if given, else 'undefined.

   Function Composition
       (comp f g)

       Right to left function composition.

       (comp fs x)

       Compose  a list of functions fs, right to left, and apply the resulting
       function to x.

       (comp f g x)

       Equivalent to (funcall (comp f g) x).

       (comp fs)

       Compose a list of functions fs from right to left.

       (comp)

       Equivalent to #'identity/1.

   Usage
       The following examples assume #'1+/1 is defined:

              > (defun 1+ (x) (+ x 1))
              1+

              > (funcall (clj:comp #'math:sin/1 #'math:asin/1) 0.5)
              0.49999999999999994
              > (funcall (clj:comp (list #'1+/1 #'math:sin/1 #'math:asin/1) 0.5))
              1.5

       Or used in another function call:

              > (lists:filter (clj:comp #'not/1 #'zero?/1)
                  '(0 1 0 2 0 3 0 4))
              (1 2 3 4)

       The usage above is best when comp will be called by higher-order  func‐
       tions like lists:foldl/3 or lists:filter/2, etc.  However, one may also
       call comp in the following manner, best suited for direct usage:

              > (clj:comp #'math:sin/1 #'math:asin/1 0.5)
              0.49999999999999994
              > (clj:comp (list #'1+/1 #'math:sin/1 #'math:asin/1) 0.5)
              1.5

   Partial Application
       (partial f args)

       (partial f arg-1)

       Partially apply f to a given argument arg-1 or list of args.

   Usage
              > (set f (clj:partial #'+/2 1))
              #Fun<clj.3.121115395>
              > (funcall f 2)
              3
              > (set f (clj:partial #'+/3 1))
              #Fun<clj.3.121115395>
              > (funcall f '(2 3))
              6
              > (set f (clj:partial #'+/3 '(2 3)))
              #Fun<clj.3.121115395>
              > (funcall f 4)
              9
              > (set f (clj:partial #'+/4 '(2 3)))
              #Fun<clj.3.121115395>
              > (funcall f '(4 5))
              14

       Note that to partially apply a function that expects a list,  you  must
       wrap said list into a (singleton) list.

              > (set double (clj:partial #'*/2 2))
              #Fun<clj.5.16146786>
              > (set f (clj:partial #'lists:map/2 double))
              #Fun<clj.5.16146786>
              > (funcall f '((1 2 3)))
              (2 4 6)

   Predicate Functions
       N.B.  These functions may not be used in guards.

       (string? data)

       Return 'true if data is a flat list of printable characters.

       (unicode? data)

       Return 'true if data is a flat list of printable Unicode characters.

       (list? data)

       Return 'true if data is a list and not a string.

       (set? data)

       Return 'true if data is appears to be a (possibly ordered) set.

       (dict? data)

       Return 'true if data is a dictionary.

       (proplist? lst)

       Return  'true  if  lst is a list where proplist-kv?/1 returns 'true for
       all elements in lst.

       (proplist-kv? data)

       Return 'true if a data is a key/value tuple or an atom.

       (queue? x)

       Return 'true if x is a queue.

       (empty? x)

       Return 'true if x is the empty list, tuple, map, dictionary, queue,  or
       general balanced tree.

       (every? pred lst)

       (all? pred lst)

       Return 'true if (pred x) returns 'true for every x in lst.

       (any? pred lst)

       Return 'true if (pred x) returns 'true for any x in lst.

       (not-any? pred lst)

       Return 'false if (pred x) returns 'true for any x in lst.

       (element? elem data)

       Return  'true  if elem is an element of data, where data is a list, set
       or ordset.

   Sequence Functions
       (seq end)

       Equivalent to (seq 1 end).

       (seq start end)

       Equivalent to (seq start end 1).

       (seq start end step)

       Return a sequence of integers, starting with start, containing the suc‐
       cessive  results  of adding step to the previous element, until end has
       been reached or password.  In the latter case, end is not an element of
       the sequence.

       (next func)

       Equivalent to (next func 1 1).

       (next func start)

       Equivalent to (next func start 1).

       (next func start step)

       Return  a  nullary  function that returns a cons cell with start as the
       head and a nullary function, (next func (funcall func start step) step)
       as  the  tail.  The result can be treated as a (possibly infinite) lazy
       list, which only computes subsequent values as needed.

       (lazy-seq seq)

       Return a lazy sequence (possibly infinite) from given lazy sequence seq
       or  finite lazy sequence from given list seq.  Lazy sequence is treated
       as finite if at any iteration it produces empty list instead of data as
       its head and nullary function for next iteration as its tail.

       (cycle lst)

       Return a lazy infinite sequence with all elements from a given list lst
       or another lazy sequence cycled.

       See next/3 for details on the structure.

       (range)

       Equivalent to (range 1 1).

       (range start)

       Equivalent to (range start 1).

       (range start step)

       Return a lazy list of integers, starting with start and  increasing  by
       step.  Equivalent to (next #'+/2 start step).  See also: next/3.

       (drop n lst)

       (drop ’all lst)

       Return a list of all but the first n elements in lst.  If n is the atom
       all, return the empty list.

       (take n lst)

       (take ’all lst)

       Given a (possibly lazy) list lst, return a list of the first n elements
       of  lst,  or  all elements if there are fewer than n.  If n is the atom
       all and lst is a “normal” list, return lst.

       (split-at n lst)

       Return a tuple of `#(,(take n lst) ,(drop n lst)).

       (partition n lst)

       Equivalent to (partition n n lst).

       (partition n step lst)

       Equivalent to (partition n step () lst).

       (partition n step pad lst)

       Return a list of lists of n items each, at offsets step apart.  Use the
       elements of pad as necessary to complete the last partition up to n el‐
       ements.  In case there are not enough padding elements, return a parti‐
       tion with less than n items.

       (partition-all n lst)

       Equivalent to (partition-all n n lst).

       (partition-all n step lst)

       Return  a list of lists like partition/3, possibly including partitions
       with fewer than n elements at the end.

       (interleave list-1 list-2)

       Return a list of the first element of each list, then the second, etc.

       (get-in data keys)

       Equivalent to (get-in data keys 'undefined).

       (get-in data keys not-found)

       Return the value in a nested associative structure,  where  keys  is  a
       list  of keys or list indices.  Return the atom not-found if the key is
       not present or index is out of bounds, or the not-found value.

       (reduce func (cons head tail))

       Equivalent to (reduce func head tail).

       (reduce func acc lst)

       Equivalent to (lists:foldl func acc lst).

       (repeat x)

       Return a lazy infinite sequence of xs.

       See next/3 for details on the structure.

       (repeat n f)

       Given a nullary function f, return a list of n applications of f.

       (repeat n x)

       Given a term x, return a list of n copies of x.

   Other Functions
       (identity x)

       Identity function.

       (constantly x)

       Return a unary function that returns x.  N.B.  This is  like  Haskell’s
       const rather than Clojure’s constantly.

       (inc x)

       Increment x by 1.

       (dec x)

       Decrement x by 1.

AUTHORS
       Tim Dysinger, Duncan McGreggor, Eric Bailey.



                                   2015-2016                        lfe_clj(3)