nix2lua/README.md

# nix2lua

This is a small but functional library that converts your nix configurations
into Lua format.

This library was initially designed for my personal
[Neovim flake](https://git.pleshevski.ru/mynix/neovim).

# Installation

Add `nix2lua` as input to your `flake.nix`

```nix
{
  inputs.nix2lua.url = "git+https://git.pleshevski.ru/mynix/nix2lua";
  
  outputs = { nix2lua }:
    let
      luaTable = nix2lua.lib.toLua {
        foo = "bar";

        nvimTree.settings = {
          open_on_setup = true;
          renderer = {
            group_empty = true;
            full_name = true;
          };
        };
      };
    in luaTable;
}
```

# References

`toLua expr`

> Returns a string containing Lua representation of `expr`. Strings, integers,
> floats, boolean, lists and sets are mapped to their Lua equivalents.
>
> Null will be skipped. This is useful when you want to use an optional value.
> To render `nil` you should use the `LuaNil` function.
>
> ```nix
> toLua { foo = "bar"; }
> # { foo = "bar" }
> toLua [ 10 "foo" [ "bar" ] ]
> #`{ 10, "foo", { "bar" } }
> ```

`LuaNil`

> Creates a type that will be mapped by the `toLua` as `nil`
>
> ```nix
> toLua LuaNil
> # nil
> ```

`raw expr`

> Creates a type that instructs `toLua` not to change the passed expression
> `expr`.
>
> ```nix
> toLua (raw "require('bar').baz")
> # require('bar').baz
> ```

`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.
>
> This is useful to create table with some named fields.
>
> ```nix
> toLua [
>   "foo"
>   (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

GNU General Public License v3.0 or later

See [COPYING](./COPYING) to see the full text.