From d02b3b0fcc8cb2a596cb94645d574e9d9d48798f Mon Sep 17 00:00:00 2001
From: Dmitriy Pleshevskiy <dmitriy@pleshevski.ru>
Date: Fri, 17 May 2024 18:10:01 +0300
Subject: [PATCH] doc: update readme

---
 README.md | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 204 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b5fbd63..a3871bd 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,9 @@ Add `nix2lua` as input to your `flake.nix`
 >
 > ```nix
 > toLua { foo = "bar"; }
+> # { foo = "bar" }
 > toLua [ 10 "foo" [ "bar" ] ]
+> #`{ 10, "foo", { "bar" } }
 > ```
 
 `LuaNil`
@@ -52,18 +54,20 @@ Add `nix2lua` as input to your `flake.nix`
 >
 > ```nix
 > toLua LuaNil
+> # nil
 > ```
 
-`LuaRaw expr`
+`raw expr`
 
 > Creates a type that instructs `toLua` not to change the passed expression
 > `expr`.
 >
 > ```nix
-> toLua (mkLuaRaw "require('bar').baz")
+> toLua (raw "require('bar').baz")
+> # require('bar').baz
 > ```
 
-`mkNamedField name expr`
+`namedField name expr` (alias: `nf`)
 
 > Creates a type that represents a named field in the Lua table. This type
 > cannot exist outside a list or set.
@@ -73,8 +77,204 @@ Add `nix2lua` as input to your `flake.nix`
 > ```nix
 > toLua [
 >   "foo"
->   (mkNamedField "bar" "baz")
+>   (namedField "bar" "baz")
 > ]
+> # { "foo", bar = "baz" }
+> ```
+
+`join sep expr`
+
+> Join expressions with a separator
+>
+> ```nix
+> toLua (join "=" ["vim.opt.line" true])
+> # vim.opt.line = true
+> ```
+
+`concat expr`
+
+> Joins expressions with an empty string separator
+>
+> This is alias for `join ""`
+>
+> ```nix
+> toLua (concat ["hello" "world"])
+> # helloworld
+> ```
+
+`pipe expr`
+
+> Joins expressions with a '.' (dot) separator.
+> If list of expressions contains a string it will
+> convert to the raw.
+>
+> ```nix
+> toLua (pipe ["vim" "opt" "line"]);
+> # vim.opt.line
+> ```
+> ```nix
+> toLua (pipe ["luasnip" (call0 "setup")]);
+> # luasnip.setup()
+> ```
+
+`pipe1 lhs rhs`
+
+> Useful alias for pipe that allow only two arguments.
+>
+> ```nix
+> toLua (pipe1 "luasnip" (call0 "setup"));
+> # luasnip.setup()
+> ```
+
+`spaceBetween expr`
+
+> Join expressions with a space separator. You can use it to separate
+> all expressions in the Lua configuration.
+>
+> This is alias for `join " "`
+>
+> ```nix
+> toLua (spaceBetween [
+>   (set "vim.opt.number" true)
+>   (set "vim.opt.relatednumber" true)
+> ])
+> # vim.opt.number = true vim.opt.relatednumber = true
+> ```
+
+`call fnName args`
+
+> Util to call a Lua function with arguments.
+> 
+> If `args` is list that each list item render as function argument.
+> Otherwise, it will be rendered as first argument.
+>
+> ```nix
+> toLua (call "setup" [ "foo" "bar" ]);
+> # setup("foo", "bar")
+> ```
+> ```nix
+> toLua (call "setup" { foo = "bar" });
+> # or: toLua (call "setup" [{ foo = "bar" }]);
+> # setup({ foo = "bar" })
+> ```
+
+`call0 fnName`
+
+> Call a Lua function without arguments.
+>
+> This is alias for `call fnName []`.
+>
+> ```nix
+> toLua (call0 "setup")
+> # setup()
+> ```
+
+`call1 fnName arg`
+
+> Call a Lua function with one argument.
+> This is useful when a Lua function has only one argument of type list,
+> and we want to avoid using an inner list.
+>
+> This is alias for `call fnName [arg]`.
+>
+> ```nix
+> toLua (call1 "setup" [ "foo" "bar" ])
+> # setup({ "foo", "bar" })
+> ```
+
+`require name`
+
+> Call a require function to import module with `name`.
+>
+> This is alias for `call "require" name`.
+> ```nix
+> toLua (require "luasnip")
+> # require("luasnip")
+> ```
+
+`op operation lhs rhs`
+
+> Make Lua basic operation.
+>
+> ```nix
+> toLua (op "+" 1 2)
+> # (1 + 2)
+> ```
+>
+> There are all aliases for basic Lua operations:
+>
+> ```
+> add = op "+";
+> sub = op "-";
+> mul = op "*";
+> div = op "/";
+> mod = op "%";
+> exp = op "^";
+>
+> eq = op "==";
+> ne = op "~=";
+> gt = op ">";
+> lt = op "<";
+> gte = op ">=";
+> lte = op "<=";
+>
+> and = op kw_and;
+> or = op kw_or;
+> not = expr: spaceBetween [ kw_not expr ];
+> ```
+
+`set varName expr`
+
+> Set an expression to a Lua variable.
+>
+> ```nix
+> toLua (set "vim.opt.number" true);
+> # vim.opt.number = true
+> ```
+
+`func fnName params body`
+
+> Define a function with specific name, parameters and body.
+>
+> ```nix
+> toLua (func "foo" ["bar"] (pipe1 "bar" (call0 "baz"));
+> # function foo(bar) bar.baz() end
+> ```
+>
+> Useful aliases:
+> ```
+> func0 = fnName: func fnName [ ];
+> ```
+
+`lambda params body`
+
+> Define a lambda function with specific parameters and body.
+> Useful to use Lua function inline.
+>
+> ```nix
+> toLua (call "setup" {
+>   on_attach = lambda ["baz"] (pipe1 "baz" (call0 "bar"))
+> });
+> # setup { on_attach = function (baz) baz.bar() end }
+> ```
+>
+> Useful aliases:
+> ```
+> lambda0 = lambda [ ];
+> ```
+
+`local expr`
+
+> A modifier to define a variable or a function in local scope.
+>
+> ```nix
+> toLua (local (set "luasnip" (require "luasnip")));
+> # local set luasnip = require("luasnip")
+> ```
+
+> ```nix
+> toLua (local (func "foo" ["bar"] (pipe1 "bar" (call0 "baz")));
+> # local function foo(bar) bar.baz() end
 > ```
 
 # License