From ece7f872860d286536cb1a5d4f9d5b7da6dc88be Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Mon, 28 Aug 2023 23:56:23 +0300 Subject: update docs, fix doctests, include macros in the docs --- doc/core.md | 2099 ----------------------------------------------------------- 1 file changed, 2099 deletions(-) delete mode 100644 doc/core.md (limited to 'doc/core.md') diff --git a/doc/core.md b/doc/core.md deleted file mode 100644 index 578efef..0000000 --- a/doc/core.md +++ /dev/null @@ -1,2099 +0,0 @@ -# Core (v1.1.1) -Fennel-cljlib - functions from Clojure's core.clj implemented on top -of Fennel. - -This library contains a set of functions providing functions that -behave similarly to Clojure's equivalents. Library itself has nothing -Fennel specific, so it should work on Lua, e.g: - -``` lua -Lua 5.3.5 Copyright (C) 1994-2018 Lua.org, PUC-Rio -> clj = require"cljlib" -> table.concat(clj.mapv(function (x) return x * x end, {1, 2, 3}), " ") --- 1 4 9 -``` - -This example is mapping an anonymous `function` over a table, -producing new table and concatenating it with `" "`. - -However, this library also provides Fennel-specific set of -[macros](./macros.md), that provides additional facilities like `defn` -or `defmulti` which extend the language allowing writing code that -looks and works mostly like Clojure. - -Each function in this library is created with `defn`, which is a -special macro for creating multi-arity functions. So when you see -function signature like `(foo [x])`, this means that this is function -`foo`, that accepts exactly one argument `x`. In contrary, functions -created with `fn` will produce `(foo x)` signature (`x` is not inside -brackets). - -Functions, which signatures look like `(foo ([x]) ([x y]) ([x y & -zs]))`, it is a multi-arity function, which accepts either one, two, -or three-or-more arguments. Each `([...])` represents different body -of a function which is chosen by checking amount of arguments passed -to the function. See [Clojure's doc section on multi-arity -functions](https://clojure.org/guides/learn/functions#_multi_arity_functions). - -## Compatibility -This library is mainly developed with Lua 5.4, and tested against -Lua 5.2, 5.3, 5.4, and LuaJIT 2.1.0-beta3. Note, that in lua 5.2 and -LuaJIT equality semantics are a bit different from Lua 5.3 and Lua 5.4. -Main difference is that when comparing two tables, they must have -exactly the same `__eq` metamethods, so comparing hash sets with hash -sets will work, but comparing sets with other tables works only in -Lua5.3+. Another difference is that Lua 5.2 and LuaJIT don't have -inbuilt UTF-8 library, therefore [`seq`](#seq) function will not work for -non-ASCII strings. - -**Table of contents** - -- [`apply`](#apply) -- [`add`](#add) -- [`sub`](#sub) -- [`mul`](#mul) -- [`div`](#div) -- [`le`](#le) -- [`lt`](#lt) -- [`ge`](#ge) -- [`gt`](#gt) -- [`inc`](#inc) -- [`dec`](#dec) -- [`eq`](#eq) -- [`map?`](#map) -- [`vector?`](#vector) -- [`multifn?`](#multifn) -- [`set?`](#set) -- [`nil?`](#nil) -- [`zero?`](#zero) -- [`pos?`](#pos) -- [`neg?`](#neg) -- [`even?`](#even) -- [`odd?`](#odd) -- [`string?`](#string) -- [`boolean?`](#boolean) -- [`true?`](#true) -- [`false?`](#false) -- [`int?`](#int) -- [`pos-int?`](#pos-int) -- [`neg-int?`](#neg-int) -- [`double?`](#double) -- [`empty?`](#empty) -- [`not-empty`](#not-empty) -- [`vector`](#vector-1) -- [`seq`](#seq) -- [`first`](#first) -- [`rest`](#rest) -- [`last`](#last) -- [`butlast`](#butlast) -- [`conj`](#conj) -- [`disj`](#disj) -- [`cons`](#cons) -- [`concat`](#concat) -- [`reduce`](#reduce) -- [`reduced`](#reduced) -- [`reduce-kv`](#reduce-kv) -- [`mapv`](#mapv) -- [`filter`](#filter) -- [`every?`](#every) -- [`some`](#some) -- [`not-any?`](#not-any) -- [`range`](#range) -- [`reverse`](#reverse) -- [`take`](#take) -- [`nthrest`](#nthrest) -- [`partition`](#partition) -- [`identity`](#identity) -- [`comp`](#comp) -- [`complement`](#complement) -- [`constantly`](#constantly) -- [`memoize`](#memoize) -- [`assoc`](#assoc) -- [`hash-map`](#hash-map) -- [`get`](#get) -- [`get-in`](#get-in) -- [`keys`](#keys) -- [`vals`](#vals) -- [`find`](#find) -- [`dissoc`](#dissoc) -- [`remove-method`](#remove-method) -- [`remove-all-methods`](#remove-all-methods) -- [`methods`](#methods) -- [`get-method`](#get-method) -- [`hash-set`](#hash-set) -- [`assoc!`](#assoc-1) -- [`assoc-in`](#assoc-in) -- [`cat`](#cat) -- [`class`](#class) -- [`completing`](#completing) -- [`conj!`](#conj-1) -- [`contains?`](#contains) -- [`count`](#count) -- [`cycle`](#cycle) -- [`dedupe`](#dedupe) -- [`deref`](#deref) -- [`disj!`](#disj-1) -- [`dissoc!`](#dissoc-1) -- [`distinct`](#distinct) -- [`doall`](#doall) -- [`dorun`](#dorun) -- [`drop`](#drop) -- [`drop-last`](#drop-last) -- [`drop-while`](#drop-while) -- [`empty`](#empty-1) -- [`ensure-reduced`](#ensure-reduced) -- [`filterv`](#filterv) -- [`frequencies`](#frequencies) -- [`group-by`](#group-by) -- [`halt-when`](#halt-when) -- [`interleave`](#interleave) -- [`interpose`](#interpose) -- [`into`](#into) -- [`iterate`](#iterate) -- [`keep`](#keep) -- [`keep-indexed`](#keep-indexed) -- [`lazy-seq`](#lazy-seq) -- [`line-seq`](#line-seq) -- [`list`](#list) -- [`list*`](#list-1) -- [`map`](#map-1) -- [`map-indexed`](#map-indexed) -- [`mapcat`](#mapcat) -- [`merge`](#merge) -- [`next`](#next) -- [`nth`](#nth) -- [`nthnext`](#nthnext) -- [`partition-all`](#partition-all) -- [`partition-by`](#partition-by) -- [`persistent!`](#persistent) -- [`pop`](#pop) -- [`pop!`](#pop-1) -- [`random-sample`](#random-sample) -- [`realized?`](#realized) -- [`reduced?`](#reduced-1) -- [`reductions`](#reductions) -- [`remove`](#remove) -- [`repeat`](#repeat) -- [`repeatedly`](#repeatedly) -- [`replace`](#replace) -- [`rseq`](#rseq) -- [`seq?`](#seq-1) -- [`sequence`](#sequence) -- [`some?`](#some-1) -- [`sort`](#sort) -- [`split-at`](#split-at) -- [`split-with`](#split-with) -- [`take-last`](#take-last) -- [`take-nth`](#take-nth) -- [`take-while`](#take-while) -- [`transduce`](#transduce) -- [`transient`](#transient) -- [`tree-seq`](#tree-seq) -- [`unreduced`](#unreduced) -- [`update`](#update) -- [`update-in`](#update-in) -- [`vec`](#vec) -- [`zipmap`](#zipmap) - -## `apply` -Function signature: - -``` -(apply ([f args]) ([f a args]) ([f a b args]) ([f a b c args]) ([f a b c d & args])) -``` - -Apply `f` to the argument list formed by prepending intervening -arguments to `args`, and `f` must support variadic amount of -arguments. - -### Examples -Applying `add` to different amount of arguments: - -``` fennel -(assert-eq (apply add [1 2 3 4]) 10) -(assert-eq (apply add 1 [2 3 4]) 10) -(assert-eq (apply add 1 2 3 4 5 6 [7 8 9]) 45) -``` - -## `add` -Function signature: - -``` -(add ([]) ([a]) ([a b]) ([a b c]) ([a b c d]) ([a b c d & rest])) -``` - -Sum arbitrary amount of numbers. - -## `sub` -Function signature: - -``` -(sub ([]) ([a]) ([a b]) ([a b c]) ([a b c d]) ([a b c d & rest])) -``` - -Subtract arbitrary amount of numbers. - -## `mul` -Function signature: - -``` -(mul ([]) ([a]) ([a b]) ([a b c]) ([a b c d]) ([a b c d & rest])) -``` - -Multiply arbitrary amount of numbers. - -## `div` -Function signature: - -``` -(div ([a]) ([a b]) ([a b c]) ([a b c d]) ([a b c d & rest])) -``` - -Divide arbitrary amount of numbers. - -## `le` -Function signature: - -``` -(le ([a]) ([a b]) ([a b & [c d & more]])) -``` - -Returns true if nums are in monotonically non-decreasing order - -## `lt` -Function signature: - -``` -(lt ([a]) ([a b]) ([a b & [c d & more]])) -``` - -Returns true if nums are in monotonically decreasing order - -## `ge` -Function signature: - -``` -(ge ([a]) ([a b]) ([a b & [c d & more]])) -``` - -Returns true if nums are in monotonically non-increasing order - -## `gt` -Function signature: - -``` -(gt ([a]) ([a b]) ([a b & [c d & more]])) -``` - -Returns true if nums are in monotonically increasing order - -## `inc` -Function signature: - -``` -(inc [x]) -``` - -Increase number `x` by one - -## `dec` -Function signature: - -``` -(dec [x]) -``` - -Decrease number `x` by one - -## `eq` -Function signature: - -``` -(eq ([]) ([_]) ([a b]) ([a b & cs])) -``` - -Comparison function. - -Accepts arbitrary amount of values, and does the deep comparison. If -values implement `__eq` metamethod, tries to use it, by checking if -first value is equal to second value, and the second value is equal to -the first value. If values are not equal and are tables does the deep -comparison. Tables as keys are supported. - -## `map?` -Function signature: - -``` -(map? [x]) -``` - -Check whether `x` is an associative table. - -Non-empty tables are tested by calling `next`. If the length of the -table is greater than zero, the last integer key is passed to the -`next`, and if `next` returns a key, the table is considered -associative. If the length is zero, `next` is called with what `paris` -returns for the table, and if the key is returned, table is considered -associative. - -Empty tables can't be analyzed with this method, and `map?` will -always return `false`. If you need this test pass for empty table, -see `hash-map` for creating tables that have additional metadata -attached for this test to work. - -### Examples -Non-empty map: - -``` fennel -(assert-is (map? {:a 1 :b 2})) -``` - -Empty tables don't pass the test: - -``` fennel -(assert-not (map? {})) -``` - -Empty tables created with `hash-map` will pass the test: - -``` fennel -(assert-is (map? (hash-map))) -``` - -## `vector?` -Function signature: - -``` -(vector? [x]) -``` - -Check whether `tbl` is a sequential table. - -Non-empty sequential tables are tested for two things: -- `next` returns the key-value pair, -- key, that is returned by the `next` is equal to `1`. - -Empty tables can't be analyzed with this method, and `vector?` will -always return `false`. If you need this test pass for empty table, -see `vector` for creating tables that have additional -metadata attached for this test to work. - -### Examples -Non-empty vector: - -``` fennel -(assert-is (vector? [1 2 3 4])) -``` - -Empty tables don't pass the test: - -``` fennel -(assert-not (vector? [])) -``` - -Empty tables created with `vector` will pass the test: - -``` fennel -(assert-is (vector? (vector))) -``` - -## `multifn?` -Function signature: - -``` -(multifn? [mf]) -``` - -Test if `mf` is an instance of `multifn`. - -`multifn` is a special kind of table, created with `defmulti` macros -from `macros.fnl`. - -## `set?` -Function signature: - -``` -(set? [x]) -``` - -Check if object is a set. - -## `nil?` -Function signature: - -``` -(nil? ([]) ([x])) -``` - -Test if `x` is nil. - -## `zero?` -Function signature: - -``` -(zero? [x]) -``` - -Test if `x` is equal to zero. - -## `pos?` -Function signature: - -``` -(pos? [x]) -``` - -Test if `x` is greater than zero. - -## `neg?` -Function signature: - -``` -(neg? [x]) -``` - -Test if `x` is less than zero. - -## `even?` -Function signature: - -``` -(even? [x]) -``` - -Test if `x` is even. - -## `odd?` -Function signature: - -``` -(odd? [x]) -``` - -Test if `x` is odd. - -## `string?` -Function signature: - -``` -(string? [x]) -``` - -Test if `x` is a string. - -## `boolean?` -Function signature: - -``` -(boolean? [x]) -``` - -Test if `x` is a Boolean - -## `true?` -Function signature: - -``` -(true? [x]) -``` - -Test if `x` is `true` - -## `false?` -Function signature: - -``` -(false? [x]) -``` - -Test if `x` is `false` - -## `int?` -Function signature: - -``` -(int? [x]) -``` - -Test if `x` is a number without floating point data. - -Number is rounded with `math.floor` and compared with original number. - -## `pos-int?` -Function signature: - -``` -(pos-int? [x]) -``` - -Test if `x` is a positive integer. - -## `neg-int?` -Function signature: - -``` -(neg-int? [x]) -``` - -Test if `x` is a negative integer. - -## `double?` -Function signature: - -``` -(double? [x]) -``` - -Test if `x` is a number with floating point data. - -## `empty?` -Function signature: - -``` -(empty? [x]) -``` - -Check if collection is empty. - -## `not-empty` -Function signature: - -``` -(not-empty [x]) -``` - -If `x` is empty, returns `nil`, otherwise `x`. - -## `vector` -Function signature: - -``` -(vector [& args]) -``` - -Constructs sequential table out of its arguments. - -Sets additional metadata for function `vector?` to work. - -### Examples - -``` fennel -(def :private v (vector 1 2 3 4)) -(assert-eq v [1 2 3 4]) -``` - -## `seq` -Function signature: - -``` -(seq [coll]) -``` - -Construct a sequence from the given collection `coll`. If `coll` is -an associative table, returns sequence of vectors with key and value. -If `col` is sequential table, returns its shallow copy. If `col` is -string, return sequential table of its codepoints. - -### Examples -Sequential tables are transformed to sequences: - -``` fennel -(seq [1 2 3 4]) ;; @seq(1 2 3 4) -``` - -Associative tables are transformed to format like this `[[key1 value1] -... [keyN valueN]]` and order is non-deterministic: - -``` fennel -(seq {:a 1 :b 2 :c 3}) ;; @seq([:b 2] [:a 1] [:c 3]) -``` - -## `first` -Function signature: - -``` -(first [coll]) -``` - -Return first element of a `coll`. Calls `seq` on its argument. - -## `rest` -Function signature: - -``` -(rest [coll]) -``` - -Returns a sequence of all elements of a `coll` but the first one. -Calls `seq` on its argument. - -## `last` -Function signature: - -``` -(last [coll]) -``` - -Returns the last element of a `coll`. Calls `seq` on its argument. - -## `butlast` -Function signature: - -``` -(butlast [coll]) -``` - -Returns everything but the last element of the `coll` as a new - sequence. Calls `seq` on its argument. - -## `conj` -Function signature: - -``` -(conj ([]) ([s]) ([s x]) ([s x & xs])) -``` - -Insert `x` as a last element of a table `tbl`. - -If `tbl` is a sequential table or empty table, inserts `x` and -optional `xs` as final element in the table. - -If `tbl` is an associative table, that satisfies `map?` test, -insert `[key value]` pair into the table. - -Mutates `tbl`. - -### Examples -Adding to sequential tables: - -``` fennel -(conj [] 1 2 3 4) -;; => [1 2 3 4] -(conj [1 2 3] 4 5) -;; => [1 2 3 4 5] -``` - -Adding to associative tables: - -``` fennel -(conj {:a 1} [:b 2] [:c 3]) -;; => {:a 1 :b 2 :c 3} -``` - -Note, that passing literal empty associative table `{}` will not work: - -``` fennel -(conj {} [:a 1] [:b 2]) -;; => [[:a 1] [:b 2]] -(conj (hash-map) [:a 1] [:b 2]) -;; => {:a 1 :b 2} -``` - -See `hash-map` for creating empty associative tables. - -## `disj` -Function signature: - -``` -(disj ([Set]) ([Set key]) ([Set key & keys])) -``` - -Returns a new set type, that does not contain the -specified `key` or `keys`. - -## `cons` -Function signature: - -``` -(cons [head tail]) -``` - -Construct a cons cell. -Prepends new `head` to a `tail`, which must be either a table, -sequence, or nil. - -### Examples - -``` fennel -(assert-eq [0 1] (cons 0 [1])) -(assert-eq (list 0 1 2 3) (cons 0 (cons 1 (list 2 3)))) -``` - -## `concat` -Function signature: - -``` -(concat [& colls]) -``` - -Return a lazy sequence of concatenated `colls`. - -## `reduce` -Function signature: - -``` -(reduce ([f coll]) ([f val coll])) -``` - -`f` should be a function of 2 arguments. If `val` is not supplied, -returns the result of applying `f` to the first 2 items in `coll`, -then applying `f` to that result and the 3rd item, etc. If `coll` -contains no items, f must accept no arguments as well, and reduce -returns the result of calling `f` with no arguments. If `coll` has -only 1 item, it is returned and `f` is not called. If `val` is -supplied, returns the result of applying `f` to `val` and the first -item in `coll`, then applying `f` to that result and the 2nd item, -etc. If `coll` contains no items, returns `val` and `f` is not -called. Early termination is supported via `reduced`. - -### Examples - -``` fennel -(defn- add - ([] 0) - ([a] a) - ([a b] (+ a b)) - ([a b & cs] (apply add (+ a b) cs))) -;; no initial value -(assert-eq 10 (reduce add [1 2 3 4])) -;; initial value -(assert-eq 10 (reduce add 1 [2 3 4])) -;; empty collection - function is called with 0 args -(assert-eq 0 (reduce add [])) -(assert-eq 10.3 (reduce math.floor 10.3 [])) -;; collection with a single element doesn't call a function unless the -;; initial value is supplied -(assert-eq 10.3 (reduce math.floor [10.3])) -(assert-eq 7 (reduce add 3 [4])) -``` - -## `reduced` -Function signature: - -``` -(reduced [value]) -``` - -Terminates the `reduce` early with a given `value`. - -### Examples - -``` fennel -(assert-eq :NaN - (reduce (fn [acc x] - (if (not= :number (type x)) - (reduced :NaN) - (+ acc x))) - [1 2 :3 4 5])) -``` - -## `reduce-kv` -Function signature: - -``` -(reduce-kv [f val s]) -``` - -Reduces an associative table using function `f` and initial value `val`. - -`f` should be a function of 3 arguments. Returns the result of -applying `f` to `val`, the first key and the first value in `tbl`, -then applying `f` to that result and the 2nd key and value, etc. If -`tbl` contains no entries, returns `val` and `f` is not called. Note -that `reduce-kv` is supported on sequential tables and strings, where -the keys will be the ordinals. - -Early termination is possible with the use of `reduced` -function. - -### Examples -Reduce associative table by adding values from all keys: - -``` fennel -(local t {:a1 1 - :b1 2 - :a2 2 - :b2 3}) - -(reduce-kv #(+ $1 $3) 0 t) -;; => 8 -``` - -Reduce table by adding values from keys that start with letter `a`: - -``` fennel -(local t {:a1 1 - :b1 2 - :a2 2 - :b2 3}) - -(reduce-kv (fn [res k v] (if (= (string.sub k 1 1) :a) (+ res v) res)) - 0 t) -;; => 3 -``` - -## `mapv` -Function signature: - -``` -(mapv ([f coll]) ([f coll & colls])) -``` - -Returns a vector consisting of the result of applying `f` to the -set of first items of each `coll`, followed by applying `f` to the set -of second items in each coll, until any one of the `colls` is -exhausted. Any remaining items in other collections are ignored. -Function `f` should accept number-of-colls arguments. - -## `filter` -Function signature: - -``` -(filter ([pred]) ([pred coll])) -``` - -Returns a lazy sequence of the items in `coll` for which -`pred` returns logical true. Returns a transducer when no collection -is provided. - -## `every?` -Function signature: - -``` -(every? [pred coll]) -``` - -Test if every item in `coll` satisfies the `pred`. - -## `some` -Function signature: - -``` -(some [pred coll]) -``` - -Test if any item in `coll` satisfies the `pred`. - -## `not-any?` -Function signature: - -``` -(not-any? [pred coll]) -``` - -Test if no item in `coll` satisfy the `pred`. - -## `range` -Function signature: - -``` -(range ([]) ([upper]) ([lower upper]) ([lower upper step])) -``` - -Returns lazy sequence of numbers from `lower` to `upper` with optional -`step`. - -## `reverse` -Function signature: - -``` -(reverse [coll]) -``` - -Returns a lazy sequence with same items as in `coll` but in reverse order. - -## `take` -Function signature: - -``` -(take ([n]) ([n coll])) -``` - -Returns a lazy sequence of the first `n` items in `coll`, or all items if -there are fewer than `n`. - -## `nthrest` -Function signature: - -``` -(nthrest [coll n]) -``` - -Returns the nth rest of `coll`, `coll` when `n` is 0. - -### Examples - -``` fennel -(assert-eq (nthrest [1 2 3 4] 3) [4]) -(assert-eq (nthrest [1 2 3 4] 2) [3 4]) -(assert-eq (nthrest [1 2 3 4] 1) [2 3 4]) -(assert-eq (nthrest [1 2 3 4] 0) [1 2 3 4]) -``` - -## `partition` -Function signature: - -``` -(partition ([n coll]) ([n step coll]) ([n step pad coll])) -``` - -Given a collection `coll`, returns a lazy sequence of lists of `n` -items each, at offsets `step` apart. If `step` is not supplied, -defaults to `n`, i.e. the partitions do not overlap. If a `pad` -collection is supplied, use its elements as necessary to complete last -partition up to `n` items. In case there are not enough padding -elements, return a partition with less than `n` items. - -## `identity` -Function signature: - -``` -(identity [x]) -``` - -Returns its argument. - -## `comp` -Function signature: - -``` -(comp ([]) ([f]) ([f g]) ([f g & fs])) -``` - -Compose functions. - -## `complement` -Function signature: - -``` -(complement [f]) -``` - -Takes a function `f` and returns the function that takes the same -amount of arguments as `f`, has the same effect, and returns the -opposite truth value. - -## `constantly` -Function signature: - -``` -(constantly [x]) -``` - -Returns a function that takes any number of arguments and returns `x`. - -## `memoize` -Function signature: - -``` -(memoize [f]) -``` - -Returns a memoized version of a referentially transparent function. -The memoized version of the function keeps a cache of the mapping from -arguments to results and, when calls with the same arguments are -repeated often, has higher performance at the expense of higher memory -use. - -## `assoc` -Function signature: - -``` -(assoc ([tbl]) ([tbl k v]) ([tbl k v & kvs])) -``` - -Associate `val` under a `key`. -Accepts extra keys and values. - -### Examples - -``` fennel -(assert-eq {:a 1 :b 2} (assoc {:a 1} :b 2)) -(assert-eq {:a 1 :b 2} (assoc {:a 1 :b 1} :b 2)) -(assert-eq {:a 1 :b 2 :c 3} (assoc {:a 1 :b 1} :b 2 :c 3)) -``` - -## `hash-map` -Function signature: - -``` -(hash-map [& kvs]) -``` - -Create associative table from `kvs` represented as sequence of keys -and values - -## `get` -Function signature: - -``` -(get ([tbl key]) ([tbl key not-found])) -``` - -Get value from the table by accessing it with a `key`. -Accepts additional `not-found` as a marker to return if value wasn't -found in the table. - -## `get-in` -Function signature: - -``` -(get-in ([tbl keys]) ([tbl keys not-found])) -``` - -Get value from nested set of tables by providing key sequence. -Accepts additional `not-found` as a marker to return if value wasn't -found in the table. - -## `keys` -Function signature: - -``` -(keys [coll]) -``` - -Returns a sequence of the map's keys, in the same order as `seq`. - -## `vals` -Function signature: - -``` -(vals [coll]) -``` - -Returns a sequence of the table's values, in the same order as `seq`. - -## `find` -Function signature: - -``` -(find [coll key]) -``` - -Returns the map entry for `key`, or `nil` if key is not present in -`coll`. - -## `dissoc` -Function signature: - -``` -(dissoc ([tbl]) ([tbl key]) ([tbl key & keys])) -``` - -Remove `key` from table `tbl`. Optionally takes more `keys`. - -## `remove-method` -Function signature: - -``` -(remove-method [multimethod dispatch-value]) -``` - -Remove method from `multimethod` for given `dispatch-value`. - -## `remove-all-methods` -Function signature: - -``` -(remove-all-methods [multimethod]) -``` - -Removes all methods of `multimethod` - -## `methods` -Function signature: - -``` -(methods [multimethod]) -``` - -Given a `multimethod`, returns a map of dispatch values -> dispatch fns - -## `get-method` -Function signature: - -``` -(get-method [multimethod dispatch-value]) -``` - -Given a `multimethod` and a `dispatch-value`, returns the dispatch -`fn` that would apply to that value, or `nil` if none apply and no -default. - -## `hash-set` -Function signature: - -``` -(hash-set [& xs]) -``` - -Create hash set. - -Set is a collection of unique elements, which sore purpose is only to -tell you if something is in the set or not. - -## `assoc!` -Function signature: - -``` -(assoc! [map k & ks]) -``` - -Remove `k`from transient map, and return `map`. - -## `assoc-in` -Function signature: - -``` -(assoc-in [tbl key-seq val]) -``` - -Associate `val` into set of immutable nested tables `t`, via given `key-seq`. -Returns a new immutable table. Returns a new immutable table. - -### Examples - -Replace value under nested keys: - -``` fennel -(assert-eq - {:a {:b {:c 1}}} - (assoc-in {:a {:b {:c 0}}} [:a :b :c] 1)) -``` - -Create new entries as you go: - -``` fennel -(assert-eq - {:a {:b {:c 1}} :e 2} - (assoc-in {:e 2} [:a :b :c] 1)) -``` - -## `cat` -Function signature: - -``` -(cat [rf]) -``` - -A transducer which concatenates the contents of each input, which must be a - collection, into the reduction. Accepts the reducing function `rf`. - -## `class` -Function signature: - -``` -(class [x]) -``` - -Return cljlib type of the `x`, or lua type. - -## `completing` -Function signature: - -``` -(completing ([f]) ([f cf])) -``` - -Takes a reducing function `f` of 2 args and returns a function -suitable for transduce by adding an arity-1 signature that calls -`cf` (default - `identity`) on the result argument. - -## `conj!` -Function signature: - -``` -(conj! ([]) ([coll]) ([coll x])) -``` - -Adds `x` to the transient collection, and return `coll`. - -## `contains?` -Function signature: - -``` -(contains? [coll elt]) -``` - -Test if `elt` is in the `coll`. It may be a linear search depending -on the type of the collection. - -## `count` -Function signature: - -``` -(count [s]) -``` - -Count amount of elements in the sequence. - -## `cycle` -Function signature: - -``` -(cycle [coll]) -``` - -Create a lazy infinite sequence of repetitions of the items in the -`coll`. - -## `dedupe` -Function signature: - -``` -(dedupe ([]) ([coll])) -``` - -Returns a lazy sequence removing consecutive duplicates in coll. -Returns a transducer when no collection is provided. - -## `deref` -Function signature: - -``` -(deref [x]) -``` - -Dereference an object. - -## `disj!` -Function signature: - -``` -(disj! ([Set]) ([Set key & ks])) -``` - -disj[oin]. Returns a transient set of the same type, that does not -contain `key`. - -## `dissoc!` -Function signature: - -``` -(dissoc! [map k & ks]) -``` - -Remove `k`from transient map, and return `map`. - -## `distinct` -Function signature: - -``` -(distinct ([]) ([coll])) -``` - -Returns a lazy sequence of the elements of the `coll` without -duplicates. Comparison is done by equality. Returns a transducer when -no collection is provided. - -## `doall` -Function signature: - -``` -(doall [seq]) -``` - -Realize whole lazy sequence `seq`. - -Walks whole sequence, realizing each cell. Use at your own risk on -infinite sequences. - -## `dorun` -Function signature: - -``` -(dorun [seq]) -``` - -Realize whole sequence `seq` for side effects. - -Walks whole sequence, realizing each cell. Use at your own risk on -infinite sequences. - -## `drop` -Function signature: - -``` -(drop ([n]) ([n coll])) -``` - -Drop `n` elements from collection `coll`, returning a lazy sequence -of remaining elements. Returns a transducer when no collection is -provided. - -## `drop-last` -Function signature: - -``` -(drop-last ([]) ([coll]) ([n coll])) -``` - -Return a lazy sequence from `coll` without last `n` elements. - -## `drop-while` -Function signature: - -``` -(drop-while ([pred]) ([pred coll])) -``` - -Drop the elements from the collection `coll` until `pred` returns logical -false for any of the elemnts. Returns a lazy sequence. Returns a -transducer when no collection is provided. - -## `empty` -Function signature: - -``` -(empty [x]) -``` - -Get an empty variant of a given collection. - -## `ensure-reduced` -Function signature: - -``` -(ensure-reduced [x]) -``` - -If x is already reduced?, returns it, else returns (reduced x) - -## `filterv` -Function signature: - -``` -(filterv [pred coll]) -``` - -Returns a vector of the items in `coll` for which -`pred` returns logical true. - -## `frequencies` -Function signature: - -``` -(frequencies [t]) -``` - -Return a table of unique entries from table `t` associated to amount -of their appearances. - -### Examples - -Count each entry of a random letter: - -``` fennel -(let [fruits [:banana :banana :apple :strawberry :apple :banana]] - (assert-eq (frequencies fruits) - {:banana 3 - :apple 2 - :strawberry 1})) -``` - -## `group-by` -Function signature: - -``` -(group-by [f t]) -``` - -Group table items in an associative table under the keys that are -results of calling `f` on each element of sequential table `t`. -Elements that the function call resulted in `nil` returned in a -separate table. - -### Examples - -Group rows by their date: - -``` fennel -(local rows - [{:date "2007-03-03" :product "pineapple"} - {:date "2007-03-04" :product "pizza"} - {:date "2007-03-04" :product "pineapple pizza"} - {:date "2007-03-05" :product "bananas"}]) - -(assert-eq (group-by #(. $ :date) rows) - {"2007-03-03" - [{:date "2007-03-03" :product "pineapple"}] - "2007-03-04" - [{:date "2007-03-04" :product "pizza"} - {:date "2007-03-04" :product "pineapple pizza"}] - "2007-03-05" - [{:date "2007-03-05" :product "bananas"}]}) -``` - -## `halt-when` -Function signature: - -``` -(halt-when ([pred]) ([pred retf])) -``` - -Returns a transducer that ends transduction when `pred` returns `true` -for an input. When `retf` is supplied it must be a `fn` of 2 arguments -- it will be passed the (completed) result so far and the input that -triggered the predicate, and its return value (if it does not throw an -exception) will be the return value of the transducer. If `retf` is -not supplied, the input that triggered the predicate will be -returned. If the predicate never returns `true` the transduction is -unaffected. - -## `interleave` -Function signature: - -``` -(interleave ([]) ([s]) ([s1 s2]) ([s1 s2 & ss])) -``` - -Returns a lazy sequence of the first item in each sequence, then the -second one, until any sequence exhausts. - -## `interpose` -Function signature: - -``` -(interpose ([sep]) ([separator coll])) -``` - -Returns a lazy sequence of the elements of `coll` separated by -`separator`. Returns a transducer when no collection is provided. - -## `into` -Function signature: - -``` -(into ([]) ([to]) ([to from]) ([to xform from])) -``` - -Returns a new coll consisting of `to` with all of the items of `from` -conjoined. A transducer `xform` may be supplied. - -### Examples - -Insert items of one collection into another collection: - -```fennel -(assert-eq [1 2 3 :a :b :c] (into [1 2 3] "abc")) -(assert-eq {:a 2 :b 3} (into {:a 1} {:a 2 :b 3})) -``` - -Transform a hash-map into a sequence of key-value pairs: - -``` fennel -(assert-eq [[:a 1]] (into (vector) {:a 1})) -``` - -You can also construct a hash-map from a sequence of key-value pairs: - -``` fennel -(assert-eq {:a 1 :b 2 :c 3} - (into (hash-map) [[:a 1] [:b 2] [:c 3]])) -``` - -## `iterate` -Function signature: - -``` -(iterate [f x]) -``` - -Returns an infinete lazy sequence of x, (f x), (f (f x)) etc. - -## `keep` -Function signature: - -``` -(keep ([f]) ([f coll])) -``` - -Returns a lazy sequence of the non-nil results of calling `f` on the -items of the `coll`. Returns a transducer when no collection is -provided. - -## `keep-indexed` -Function signature: - -``` -(keep-indexed ([f]) ([f coll])) -``` - -Returns a lazy sequence of the non-nil results of (f index item) in -the `coll`. Note, this means false return values will be included. -`f` must be free of side effects. Returns a transducer when no -collection is provided. - -## `lazy-seq` -Function signature: - -``` -(lazy-seq [f]) -``` - -Create lazy sequence from the result of calling a function `f`. -Delays execution of `f` until sequence is consumed. `f` must return a -sequence or a vector. - -## `line-seq` -Function signature: - -``` -(line-seq [file]) -``` - -Accepts a `file` handle, and creates a lazy sequence of lines using -`lines` metamethod. - -### Examples - -Lazy sequence of file lines may seem similar to an iterator over a -file, but the main difference is that sequence can be shared onve -realized, and iterator can't. Lazy sequence can be consumed in -iterator style with the `doseq` macro. - -Bear in mind, that since the sequence is lazy it should be realized or -truncated before the file is closed: - -``` fennel -(let [lines (with-open [f (io.open "init.fnl" :r)] - (line-seq f))] - ;; this will error because only first line was realized, but the - ;; file was closed before the rest of lines were cached - (assert-not (pcall next lines))) -``` - -Sequence is realized with `doall` before file was closed and can be shared: - -``` fennel -(let [lines (with-open [f (io.open "init.fnl" :r)] - (doall (line-seq f)))] - (assert-is (pcall next lines))) -``` - -Infinite files can't be fully realized, but can be partially realized -with `take`: - -``` fennel -(let [lines (with-open [f (io.open "/dev/urandom" :r)] - (doall (take 3 (line-seq f))))] - (assert-is (pcall next lines))) -``` - -## `list` -Function signature: - -``` -(list ...) -``` - -Create eager sequence of provided values. - -### Examples - -``` fennel -(local l (list 1 2 3 4 5)) -(assert-eq [1 2 3 4 5] l) -``` - -## `list*` -Function signature: - -``` -(list* [& args]) -``` - -Creates a new sequence containing the items prepended to the rest, -the last of which will be treated as a sequence. - -### Examples - -``` fennel -(local l (list* 1 2 3 [4 5])) -(assert-eq [1 2 3 4 5] l) -``` - -## `map` -Function signature: - -``` -(map ([f]) ([f coll]) ([f coll & colls])) -``` - -Returns a lazy sequence consisting of the result of applying `f` to -the set of first items of each `coll`, followed by applying `f` to the -set of second items in each `coll`, until any one of the `colls` is -exhausted. Any remaining items in other `colls` are ignored. Function -`f` should accept number-of-colls arguments. Returns a transducer when -no collection is provided. - -### Examples - -``` fennel -(map #(+ $ 1) [1 2 3]) ;; => @seq(2 3 4) -(map #(+ $1 $2) [1 2 3] [4 5 6]) ;; => @seq(5 7 9) -(def :private res (map #(+ $ 1) [:a :b :c])) ;; will raise an error only when realized -``` - -## `map-indexed` -Function signature: - -``` -(map-indexed ([f]) ([f coll])) -``` - -Returns a lazy sequence consisting of the result of applying `f` to 1 -and the first item of `coll`, followed by applying `f` to 2 and the -second item in `coll`, etc., until `coll` is exhausted. Returns a -transducer when no collection is provided. - -## `mapcat` -Function signature: - -``` -(mapcat ([f]) ([f & colls])) -``` - -Apply `concat` to the result of calling `map` with `f` and -collections `colls`. Returns a transducer when no collection is -provided. - -## `merge` -Function signature: - -``` -(merge [& maps]) -``` - -Merge `maps` rght to left into a single hash-map. - -## `next` -Function signature: - -``` -(next [s]) -``` - -Return the tail of a sequence. - -If the sequence is empty, returns nil. - -## `nth` -Function signature: - -``` -(nth ([coll i]) ([coll i not-found])) -``` - -Returns the value at the `index`. `get` returns `nil` if `index` out -of bounds, `nth` raises an error unless `not-found` is supplied. -`nth` also works for strings and sequences. - -## `nthnext` -Function signature: - -``` -(nthnext [coll n]) -``` - -Returns the nth next of `coll`, (seq coll) when `n` is 0. - -## `partition-all` -Function signature: - -``` -(partition-all ([n]) ([n coll]) ([n step coll])) -``` - -Given a collection `coll`, returns a lazy sequence of lists like -`partition`, but may include partitions with fewer than n items at the -end. Accepts addiitonal `step` argument, similarly to `partition`. -Returns a transducer, if collection is not supplied. - -## `partition-by` -Function signature: - -``` -(partition-by ([f]) ([f coll])) -``` - -Applies `f` to each value in `coll`, splitting it each time `f` -returns a new value. Returns a lazy seq of partitions. Returns a -transducer, if collection is not supplied. - -## `persistent!` -Function signature: - -``` -(persistent! [coll]) -``` - -Returns a new, persistent version of the transient collection. The -transient collection cannot be used after this call, any such use will -raise an error. - -## `pop` -Function signature: - -``` -(pop [coll]) -``` - -If `coll` is a list returns a new list without the first -item. If `coll` is a vector, returns a new vector without the last -item. If the collection is empty, raises an error. Not the same as -`next` or `butlast`. - -## `pop!` -Function signature: - -``` -(pop! [coll]) -``` - -Removes the last item from a transient vector. If the collection is -empty, raises an error Returns coll - -## `random-sample` -Function signature: - -``` -(random-sample ([prob]) ([prob coll])) -``` - -Returns items from `coll` with random probability of `prob` (0.0 - -1.0). Returns a transducer when no collection is provided. - -## `realized?` -Function signature: - -``` -(realized? [s]) -``` - -Check if sequence's first element is realized. - -## `reduced?` -Function signature: - -``` -(reduced? [x]) -``` - -Returns true if `x` is the result of a call to reduced - -## `reductions` -Function signature: - -``` -(reductions ([f coll]) ([f init coll])) -``` - -Returns a lazy seq of the intermediate values of the reduction (as -per reduce) of `coll` by `f`, starting with `init`. - -## `remove` -Function signature: - -``` -(remove ([pred]) ([pred coll])) -``` - -Returns a lazy sequence of the items in the `coll` without elements -for wich `pred` returns logical true. Returns a transducer when no -collection is provided. - -## `repeat` -Function signature: - -``` -(repeat [x]) -``` - -Takes a value `x` and returns an infinite lazy sequence of this value. - -### Examples - -``` fennel -(assert-eq 20 (reduce add (take 10 (repeat 2)))) -``` - -## `repeatedly` -Function signature: - -``` -(repeatedly [f & args]) -``` - -Takes a function `f` and returns an infinite lazy sequence of -function applications. Rest arguments are passed to the function. - -## `replace` -Function signature: - -``` -(replace ([smap]) ([smap coll])) -``` - -Given a map of replacement pairs and a vector/collection `coll`, -returns a vector/seq with any elements `=` a key in `smap` replaced -with the corresponding `val` in `smap`. Returns a transducer when no -collection is provided. - -## `rseq` -Function signature: - -``` -(rseq [rev]) -``` - -Returns, in possibly-constant time, a seq of the items in `rev` in reverse order. -Input must be traversable with `ipairs`. Doesn't work in constant -time if `rev` implements a linear-time `__len` metamethod, or invoking -Lua `#` operator on `rev` takes linar time. If `t` is empty returns -`nil`. - -### Examples - -``` fennel -(def :private v [1 2 3]) -(def :private r (rseq v)) - -(assert-eq (reverse v) r) -``` - -## `seq?` -Function signature: - -``` -(seq? [x]) -``` - -Check if object is a sequence. - -## `sequence` -Function signature: - -``` -(sequence ([coll]) ([xform coll]) ([xform coll & colls])) -``` - -Coerces coll to a (possibly empty) sequence, if it is not already -one. Will not force a lazy seq. `(sequence nil)` yields an empty list, -When a transducer `xform` is supplied, returns a lazy sequence of -applications of the transform to the items in `coll`, i.e. to the set -of first items of each `coll`, followed by the set of second items in -each `coll`, until any one of the `colls` is exhausted. Any remaining -items in other `colls` are ignored. The transform should accept -number-of-colls arguments - -## `some?` -Function signature: - -``` -(some? [x]) -``` - -Returns true if x is not nil, false otherwise. - -## `sort` -Function signature: - -``` -(sort ([coll]) ([comparator coll])) -``` - -Returns a sorted sequence of the items in `coll`. If no `comparator` -is supplied, uses `<`. - -## `split-at` -Function signature: - -``` -(split-at [n coll]) -``` - -Return a table with sequence `coll` being split at `n` - -## `split-with` -Function signature: - -``` -(split-with [pred coll]) -``` - -Return a table with sequence `coll` being split with `pred` - -## `take-last` -Function signature: - -``` -(take-last [n coll]) -``` - -Return a sequence of last `n` elements of the `coll`. - -## `take-nth` -Function signature: - -``` -(take-nth ([n]) ([n coll])) -``` - -Return a lazy sequence of every `n` item in `coll`. Returns a -transducer when no collection is provided. - -## `take-while` -Function signature: - -``` -(take-while ([pred]) ([pred coll])) -``` - -Take the elements from the collection `coll` until `pred` returns logical -false for any of the elemnts. Returns a lazy sequence. Returns a -transducer when no collection is provided. - -## `transduce` -Function signature: - -``` -(transduce ([xform f coll]) ([xform f init coll])) -``` - -`reduce` with a transformation of `f` (`xform`). If `init` is not -supplied, `f` will be called to produce it. `f` should be a reducing -step function that accepts both 1 and 2 arguments, if it accepts only -2 you can add the arity-1 with `completing`. Returns the result of -applying (the transformed) `xform` to `init` and the first item in -`coll`, then applying `xform` to that result and the 2nd item, etc. If -`coll` contains no items, returns `init` and `f` is not called. Note -that certain transforms may inject or skip items. - -## `transient` -Function signature: - -``` -(transient [coll]) -``` - -Returns a new, transient version of the collection. - -## `tree-seq` -Function signature: - -``` -(tree-seq [branch? children root]) -``` - -Returns a lazy sequence of the nodes in a tree, via a depth-first walk. - -`branch?` must be a function of one arg that returns true if passed a -node that can have children (but may not). `children` must be a -function of one arg that returns a sequence of the children. Will -only be called on nodes for which `branch?` returns true. `root` is -the root node of the tree. - -### Examples - -For the given tree `["A" ["B" ["D"] ["E"]] ["C" ["F"]]]`: - - A - / \ - B C - / \ \ - D E F - -Calling `tree-seq` with `next` as the `branch?` and `rest` as the -`children` returns a flat representation of a tree: - -``` fennel -(assert-eq (map first (tree-seq next rest ["A" ["B" ["D"] ["E"]] ["C" ["F"]]])) - ["A" "B" "D" "E" "C" "F"]) -``` - -## `unreduced` -Function signature: - -``` -(unreduced [x]) -``` - -If `x` is `reduced?`, returns `(deref x)`, else returns `x`. - -## `update` -Function signature: - -``` -(update [tbl key f]) -``` - -Update table value stored under `key` by calling a function `f` on -that value. `f` must take one argument, which will be a value stored -under the key in the table. - -### Examples - -Same as `assoc` but accepts function to produce new value based on key value. - -``` fennel -(assert-eq - {:data "THIS SHOULD BE UPPERCASE"} - (update {:data "this should be uppercase"} :data string.upper)) -``` - -## `update-in` -Function signature: - -``` -(update-in [tbl key-seq f]) -``` - -Update table value stored under set of immutable nested tables, via -given `key-seq` by calling a function `f` on the value stored under the -last key. `f` must take one argument, which will be a value stored -under the key in the table. Returns a new immutable table. - -### Examples - -Same as `assoc-in` but accepts function to produce new value based on key value. - -``` fennel -(fn capitalize-words [s] - (pick-values 1 - (s:gsub "(%a)([%w_`]*)" #(.. ($1:upper) ($2:lower))))) - -(assert-eq - {:user {:name "John Doe"}} - (update-in {:user {:name "john doe"}} [:user :name] capitalize-words)) -``` - -## `vec` -Function signature: - -``` -(vec [coll]) -``` - -Coerce collection `coll` to a vector. - -## `zipmap` -Function signature: - -``` -(zipmap [keys vals]) -``` - -Return an associative table with the `keys` mapped to the -corresponding `vals`. - - ---- - -Copyright (C) 2020-2021 Andrey Listopadov - -License: [MIT](https://gitlab.com/andreyorst/fennel-cljlib/-/raw/master/LICENSE) - - - -- cgit v1.2.3