diff options
| -rw-r--r-- | doc/cljlib.md | 54 | ||||
| -rw-r--r-- | doc/macros.md | 89 | ||||
| -rw-r--r-- | init.fnl | 54 | ||||
| -rw-r--r-- | macros.fnl | 82 | ||||
| -rw-r--r-- | tests/test.fnl | 24 |
5 files changed, 137 insertions, 166 deletions
diff --git a/doc/cljlib.md b/doc/cljlib.md index 54d8294..e54bcae 100644 --- a/doc/cljlib.md +++ b/doc/cljlib.md @@ -823,6 +823,7 @@ Map [`mul`](#mul) over two tables: Basic `zipmap` implementation: ``` fennel +(import-macros {: into} :macros) (fn zipmap [keys vals] (into {} (mapv vector keys vals))) @@ -1078,17 +1079,17 @@ Ordered sets are created by passing any amount of elements desired to be in the set: ``` fennel ->> (ordered-set) -@set{} ->> (ordered-set :a :c :b) -@set{:a :c :b} +(ordered-set) +;; => @set{} +(ordered-set :a :c :b) +;; => @set{:a :c :b} ``` Duplicate items are not added: ``` fennel ->> (ordered-set :a :c :a :a :a :a :c :b) -@set{:a :c :b} +(ordered-set :a :c :a :a :a :a :c :b) +;; => @set{:a :c :b} ``` #### Check if set contains desired value: @@ -1096,34 +1097,34 @@ Sets are functions of their keys, so simply calling a set with a desired key will either return the key, or `nil`: ``` fennel ->> (local oset (ordered-set [:a :b :c] [:c :d :e] :e :f)) ->> (oset [:a :b :c]) -["a" "b" "c"] ->> (. oset :e) -"e" ->> (oset [:a :b :f]) -nil +(local oset (ordered-set [:a :b :c] [:c :d :e] :e :f)) +(oset [:a :b :c]) +;; => ["a" "b" "c"] +(. oset :e) +;; "e" +(oset [:a :b :f]) +;; => nil ``` #### Add items to existing set: To add element to the set use [`conj`](#conj) or `tset` ``` fennel ->> (local oset (ordered-set :a :b :c)) ->> (conj oset :d :e) -@set{:a :b :c :d :e} +(local oset (ordered-set :a :b :c)) +(conj oset :d :e) +;; => @set{:a :b :c :d :e} ``` ##### Remove items from the set: To add element to the set use [`disj`](#disj) or `tset` ``` fennel ->> (local oset (ordered-set :a :b :c)) ->> (disj oset :b) -@set{:a :c} ->> (tset oset :a nil) ->> oset -@set{:c} +(local oset (ordered-set :a :b :c)) +(disj oset :b) +;; => @set{:a :c} +(tset oset :a nil) +oset +;; => @set{:c} ``` #### Equality semantics @@ -1132,12 +1133,9 @@ and are compared for having the same keys without particular order and same size: ``` fennel ->> (= (ordered-set :a :b) (ordered-set :b :a)) -true ->> (= (ordered-set :a :b) (ordered-set :b :a :c)) -false ->> (= (ordered-set :a :b) (hash-set :a :b)) -true +(assert (= (ordered-set :a :b) (ordered-set :b :a))) +(assert (not= (ordered-set :a :b) (ordered-set :b :a :c))) +(assert (= (ordered-set :a :b) (hash-set :a :b))) ``` ## `hash-set` diff --git a/doc/macros.md b/doc/macros.md index e9cc517..1841b14 100644 --- a/doc/macros.md +++ b/doc/macros.md @@ -18,7 +18,6 @@ Macros for Cljlib that implement various facilities from Clojure. - [`when-let`](#when-let) - [`if-some`](#if-some) - [`when-some`](#when-some) -- [`deep-tostring`](#deep-tostring) ## `fn*` Function signature: @@ -52,7 +51,7 @@ other one or more arguments: ([] nil) ([x & xs] (print x) - (f (unpack xs)))) + (f ((or table.unpack _G.unpack) xs)))) ``` Note, that this function is recursive, and calls itself with less and @@ -126,7 +125,7 @@ namespace tables: (fn* ns.strings.join ([s1 s2] (.. s1 s2)) ([s1 s2 & strings] - (join (join s1 s2) (unpack strings)))) ;; call `join` resolves to ns.strings.join + (join (join s1 s2) ((or table.unpack _G.unpack) strings)))) ;; call `join` resolves to ns.strings.join (fn* ns.tables.join ([t1 t2] @@ -135,14 +134,8 @@ namespace tables: (each [_ v (ipairs t2)] (table.insert res v)) res)) ([t1 t2 & tables] - (join (join t1 t2) (unpack tables)))) ;; call to `join` resolves to ns.tables.join -``` + (join (join t1 t2) ((or table.unpack _G.unpack) tables)))) ;; call to `join` resolves to ns.tables.join -Note that this creates a collision and local `join` overrides `join` -from `ns.strings`, so the latter must be fully qualified -`ns.strings.join` when called outside of the function: - -``` fennel (ns.strings.join "a" "b" "c") ;; => abc (join ["a"] ["b"] ["c"] ["d" "e"]) @@ -151,6 +144,10 @@ from `ns.strings`, so the latter must be fully qualified ;; {} ``` +Note that this creates a collision and local `join` overrides `join` +from `ns.strings`, so the latter must be fully qualified +`ns.strings.join` when called outside of the function. + ## `try` Function signature: @@ -193,29 +190,30 @@ Catch all errors, ignore those and return fallback value: Catch error and do cleanup: ``` fennel ->> (let [tbl []] - (try - (table.insert tbl "a") - (table.insert tbl "b" "c") - (catch _ - (each [k _ (pairs tbl)] - (tset tbl k nil)))) - tbl) -{} +(let [tbl []] + (try + (table.insert tbl "a") + (table.insert tbl "b" "c") + (catch _ + (each [k _ (pairs tbl)] + (tset tbl k nil)))) + tbl) +;; => {} ``` Always run some side effect action: ``` fennel ->> (local res (try 10 (finally (print "side-effect!"))) -side-effect! -nil ->> rese0 ->> (local res (try (error 10) (catch 10 nil) (finally (print "side-effect!"))) -side-effect! -nil ->> res -nil +(local res (try 10 (finally (print "side-effect!")))) +;; => side-effect! +;; => nil +res +;; => 10 +(local res (try (error 10) (catch 10 nil) (finally (print "side-effect!")))) +;; => side-effect! +;; => nil +res +;; => nil ``` @@ -247,7 +245,6 @@ supported, which is `:mutable`, which allows mutating variable with ``` fennel ;; Bad, will override existing documentation for 299792458 (if any) (def {:doc "speed of light in m/s"} c 299792458) -(set c 0) ;; => error, can't mutate `c` (def :mutable address "Lua St.") ;; same as (def {:mutable true} address "Lua St.") (set address "Lisp St.") ;; can mutate `address` @@ -357,19 +354,16 @@ tables to Lua's one: (.. "{" (table.concat res ", ") "}"))) (defmethod to-lua-str :string [x] (.. "\"" x "\"")) (defmethod to-lua-str :default [x] (tostring x)) -``` - -And if we call it on some table, we'll get a valid Lua table: -``` fennel (print (to-lua-str {:a {:b 10}})) -;; prints {["a"] = {["b"] = 10}} +;; => {["a"] = {["b"] = 10}} (print (to-lua-str [:a :b :c [:d {:e :f}]])) -;; prints {[1] = "a", [2] = "b", [3] = "c", [4] = {[1] = "d", [2] = {["e"] = "f"}}} +;; => {[1] = "a", [2] = "b", [3] = "c", [4] = {[1] = "d", [2] = {["e"] = "f"}}} ``` -Which we can then reformat as we want and use in Lua if we want. +And if we call it on some table, we'll get a valid Lua table, which we +can then reformat as we want and use in Lua if we want. ## `into` Function signature: @@ -479,12 +473,12 @@ Attach metadata to a value. When metadata feature is not enabled, returns the value without additional metadata. ``` fennel ->> (local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z))) - {:fnl/arglist ["x" "y" "z" "..."] - :fnl/docstring "sum first three values"})) ->> (doc foo) -(foo x y z ...) - sum first three values +(local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z))) + {:fnl/arglist ["x" "y" "z" "..."] + :fnl/docstring "sum first three values"})) +;; (doc foo) +;; => (foo x y z ...) +;; => sum first three values ``` ## `meta` @@ -500,7 +494,7 @@ feature is not enabled returns `nil`. ### Example ``` fennel ->> (meta (with-meta {} {:meta "data"})) +(meta (with-meta {} {:meta "data"})) ;; => {:meta "data"} ``` @@ -567,15 +561,6 @@ Function signature: If test is non-`nil`, evaluates `body` in implicit `do`. -## `deep-tostring` -Function signature: - -``` -(deep-tostring data key?) -``` - -**Undocumented** - --- @@ -750,6 +750,7 @@ Map [`mul`](#mul) over two tables: Basic `zipmap` implementation: ``` fennel +(import-macros {: into} :macros) (fn zipmap [keys vals] (into {} (mapv vector keys vals))) @@ -1192,17 +1193,17 @@ Ordered sets are created by passing any amount of elements desired to be in the set: ``` fennel ->> (ordered-set) -@set{} ->> (ordered-set :a :c :b) -@set{:a :c :b} +(ordered-set) +;; => @set{} +(ordered-set :a :c :b) +;; => @set{:a :c :b} ``` Duplicate items are not added: ``` fennel ->> (ordered-set :a :c :a :a :a :a :c :b) -@set{:a :c :b} +(ordered-set :a :c :a :a :a :a :c :b) +;; => @set{:a :c :b} ``` ## Check if set contains desired value: @@ -1210,34 +1211,34 @@ Sets are functions of their keys, so simply calling a set with a desired key will either return the key, or `nil`: ``` fennel ->> (local oset (ordered-set [:a :b :c] [:c :d :e] :e :f)) ->> (oset [:a :b :c]) -[\"a\" \"b\" \"c\"] ->> (. oset :e) -\"e\" ->> (oset [:a :b :f]) -nil +(local oset (ordered-set [:a :b :c] [:c :d :e] :e :f)) +(oset [:a :b :c]) +;; => [\"a\" \"b\" \"c\"] +(. oset :e) +;; \"e\" +(oset [:a :b :f]) +;; => nil ``` ## Add items to existing set: To add element to the set use [`conj`](#conj) or `tset` ``` fennel ->> (local oset (ordered-set :a :b :c)) ->> (conj oset :d :e) -@set{:a :b :c :d :e} +(local oset (ordered-set :a :b :c)) +(conj oset :d :e) +;; => @set{:a :b :c :d :e} ``` ### Remove items from the set: To add element to the set use [`disj`](#disj) or `tset` ``` fennel ->> (local oset (ordered-set :a :b :c)) ->> (disj oset :b) -@set{:a :c} ->> (tset oset :a nil) ->> oset -@set{:c} +(local oset (ordered-set :a :b :c)) +(disj oset :b) +;; => @set{:a :c} +(tset oset :a nil) +oset +;; => @set{:c} ``` ## Equality semantics @@ -1246,12 +1247,9 @@ and are compared for having the same keys without particular order and same size: ``` fennel ->> (= (ordered-set :a :b) (ordered-set :b :a)) -true ->> (= (ordered-set :a :b) (ordered-set :b :a :c)) -false ->> (= (ordered-set :a :b) (hash-set :a :b)) -true +(assert (= (ordered-set :a :b) (ordered-set :b :a))) +(assert (not= (ordered-set :a :b) (ordered-set :b :a :c))) +(assert (= (ordered-set :a :b) (hash-set :a :b))) ```" [& xs] (let [Set (setmetatable {} {:__index deep-index}) @@ -163,7 +163,7 @@ feature is not enabled returns `nil`. # Example ``` fennel ->> (meta (with-meta {} {:meta \"data\"})) +(meta (with-meta {} {:meta \"data\"})) ;; => {:meta \"data\"} ``` @@ -196,12 +196,12 @@ this stuff will only work if you use `require-macros` instead of returns the value without additional metadata. ``` fennel ->> (local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z))) - {:fnl/arglist [\"x\" \"y\" \"z\" \"...\"] - :fnl/docstring \"sum first three values\"})) ->> (doc foo) -(foo x y z ...) - sum first three values +(local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z))) + {:fnl/arglist [\"x\" \"y\" \"z\" \"...\"] + :fnl/docstring \"sum first three values\"})) +;; (doc foo) +;; => (foo x y z ...) +;; => sum first three values ```" (if (not meta-enabled) value `(let [value# ,value @@ -420,7 +420,7 @@ other one or more arguments: ([] nil) ([x & xs] (print x) - (f (unpack xs)))) + (f ((or table.unpack _G.unpack) xs)))) ``` Note, that this function is recursive, and calls itself with less and @@ -494,7 +494,7 @@ namespace tables: (fn* ns.strings.join ([s1 s2] (.. s1 s2)) ([s1 s2 & strings] - (join (join s1 s2) (unpack strings)))) ;; call `join` resolves to ns.strings.join + (join (join s1 s2) ((or table.unpack _G.unpack) strings)))) ;; call `join` resolves to ns.strings.join (fn* ns.tables.join ([t1 t2] @@ -503,21 +503,19 @@ namespace tables: (each [_ v (ipairs t2)] (table.insert res v)) res)) ([t1 t2 & tables] - (join (join t1 t2) (unpack tables)))) ;; call to `join` resolves to ns.tables.join -``` - -Note that this creates a collision and local `join` overrides `join` -from `ns.strings`, so the latter must be fully qualified -`ns.strings.join` when called outside of the function: + (join (join t1 t2) ((or table.unpack _G.unpack) tables)))) ;; call to `join` resolves to ns.tables.join -``` fennel (ns.strings.join \"a\" \"b\" \"c\") ;; => abc (join [\"a\"] [\"b\"] [\"c\"] [\"d\" \"e\"]) ;; => [\"a\" \"b\" \"c\" \"d\" \"e\"] (join \"a\" \"b\" \"c\") ;; {} -```" +``` + +Note that this creates a collision and local `join` overrides `join` +from `ns.strings`, so the latter must be fully qualified +`ns.strings.join` when called outside of the function." (assert-compile (not (string? name)) "fn* expects symbol, vector, or list as first argument" name) (let [docstring (if (string? doc?) doc? nil) (name-wo-namespace namespaced?) (multisym->sym name) @@ -933,19 +931,16 @@ tables to Lua's one: (.. \"{\" (table.concat res \", \") \"}\"))) (defmethod to-lua-str :string [x] (.. \"\\\"\" x \"\\\"\")) (defmethod to-lua-str :default [x] (tostring x)) -``` -And if we call it on some table, we'll get a valid Lua table: - -``` fennel (print (to-lua-str {:a {:b 10}})) -;; prints {[\"a\"] = {[\"b\"] = 10}} +;; => {[\"a\"] = {[\"b\"] = 10}} (print (to-lua-str [:a :b :c [:d {:e :f}]])) -;; prints {[1] = \"a\", [2] = \"b\", [3] = \"c\", [4] = {[1] = \"d\", [2] = {[\"e\"] = \"f\"}}} +;; => {[1] = \"a\", [2] = \"b\", [3] = \"c\", [4] = {[1] = \"d\", [2] = {[\"e\"] = \"f\"}}} ``` -Which we can then reformat as we want and use in Lua if we want."}) +And if we call it on some table, we'll get a valid Lua table, which we +can then reformat as we want and use in Lua if we want."}) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; def and defonce ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -990,7 +985,6 @@ supported, which is `:mutable`, which allows mutating variable with ``` fennel ;; Bad, will override existing documentation for 299792458 (if any) (def {:doc \"speed of light in m/s\"} c 299792458) -(set c 0) ;; => error, can't mutate `c` (def :mutable address \"Lua St.\") ;; same as (def {:mutable true} address \"Lua St.\") (set address \"Lisp St.\") ;; can mutate `address` @@ -1129,30 +1123,30 @@ Catch all errors, ignore those and return fallback value: Catch error and do cleanup: ``` fennel ->> (let [tbl []] - (try - (table.insert tbl \"a\") - (table.insert tbl \"b\" \"c\") - (catch _ - (each [k _ (pairs tbl)] - (tset tbl k nil)))) - tbl) -{} +(let [tbl []] + (try + (table.insert tbl \"a\") + (table.insert tbl \"b\" \"c\") + (catch _ + (each [k _ (pairs tbl)] + (tset tbl k nil)))) + tbl) +;; => {} ``` Always run some side effect action: ``` fennel ->> (local res (try 10 (finally (print \"side-effect!\"))) -side-effect! -nil ->> res -10 ->> (local res (try (error 10) (catch 10 nil) (finally (print \"side-effect!\"))) -side-effect! -nil ->> res -nil +(local res (try 10 (finally (print \"side-effect!\")))) +;; => side-effect! +;; => nil +res +;; => 10 +(local res (try (error 10) (catch 10 nil) (finally (print \"side-effect!\")))) +;; => side-effect! +;; => nil +res +;; => nil ``` "}) diff --git a/tests/test.fnl b/tests/test.fnl index 143b749..f1d6371 100644 --- a/tests/test.fnl +++ b/tests/test.fnl @@ -42,23 +42,19 @@ Generates formatted message if `msg` is not set to other message. Compare two expressions: ``` fennel ->> (assert-eq 1 (+1 1)) -runtime error: equality assertion failed - Left: 1 - Right: 3 +;; (assert-eq 1 (+1 1)) +;; => runtime error: equality assertion failed +;; => Left: 1 +;; => Right: 3 ``` Deep compare values: ``` fennel ->> (assert-eq [1 {[2 3] [4 5 6]}] [1 {[2 3] [4 5]}]) -runtime error: equality assertion failed - Left: [1 { - [2 3] [4 5 6] - }] - Right: [1 { - [2 3] [4 5] - }] +;; (assert-eq [1 {[2 3] [4 5 6]}] [1 {[2 3] [4 5]}]) +;; => runtime error: equality assertion failed +;; => Left: [1 {[2 3] [4 5 6]}] +;; => Right: [1 {[2 3] [4 5]}] ```" `(let [left# ,expr1 right# ,expr2 @@ -89,8 +85,8 @@ runtime error: equality assertion failed verbose message if `msg` is not set. ``` fennel ->> (assert-is (= 1 2 3)) -runtime error: assertion failed for (= 1 2 3) +;; (assert-is (= 1 2 3)) +;; => runtime error: assertion failed for (= 1 2 3) ```" `(assert ,expr (.. "assertion failed for " |