From 5753537138f6a0c71ddb6a8d9770b7cb13c1bd3f Mon Sep 17 00:00:00 2001 From: Andrey Orst Date: Mon, 16 Nov 2020 20:00:47 +0300 Subject: feature(doc): update documentation --- cljlib.fnl | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) (limited to 'cljlib.fnl') diff --git a/cljlib.fnl b/cljlib.fnl index d96d8da..a305e0a 100644 --- a/cljlib.fnl +++ b/cljlib.fnl @@ -1,6 +1,41 @@ -(local core {:_DESCRIPTION "Fennel-cljlib - functions from Clojure's core.clj implemented on top of Fennel." - :_VERSION "0.1.0" - :_COPYRIGHT "Copyright (C) 2020 Andrey Orst"}) +(local core {:_VERSION "0.1.0" + :_LICENSE "[MIT](https://gitlab.com/andreyorst/fennel-cljlib/-/raw/master/LICENSE)" + :_COPYRIGHT "Copyright (C) 2020 Andrey Orst" + :_DESCRIPTION "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, 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](./cljlib-macros.md), that provides additional facilites like +`fn*` or `defmulti` which extend the language allowing writing code +that looks and works mostly like Clojure. + +Each function in this library is created with `fn*`, which is a +special macros 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 choosed 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)."}) (local insert table.insert) (local unpack (or table.unpack _G.unpack)) -- cgit v1.2.3