From 7f3fe5caa5dcebff3fbf1b4d9e02e6c9335313e9 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 21 Aug 2025 09:20:05 +0300 Subject: [PATCH 1/2] docs/hacking: describe `toLuaObject` syntax for mixed tables Signed-off-by: NotAShelf Change-Id: I6a6a696449aab94c06827ea4b1d6e6042cc97ee6 --- docs/manual/hacking/additional-plugins.md | 26 +++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/manual/hacking/additional-plugins.md b/docs/manual/hacking/additional-plugins.md index 1f7ba778..5b092f5c 100644 --- a/docs/manual/hacking/additional-plugins.md +++ b/docs/manual/hacking/additional-plugins.md @@ -165,15 +165,33 @@ own fields! ## Details of toLuaObject {#sec-details-of-toluaobject} -As you've seen above, `toLuaObject` is used to convert our nix attrSet -`cfg.setupOpts`, into a lua table. Here are some rules of the conversion: +As you've seen above, `toLuaObject` is used to convert our `cfg.setupOpts`, a +Nix attribute set, into Lua tables across the codebase. Here are some rules of +the conversion: -1. Nix `null` converts to lua `nil` -2. Number and strings convert to their lua counterparts +1. Nix `null` converts to Lua `nil` + - `foo = null;` -> `foo = nil` +2. Number and strings convert to their Lua counterparts 3. Nix attribute sets (`{}`) and lists (`[]`) convert into Lua dictionaries and tables respectively. Here is an example of Nix -> Lua conversion. - `{foo = "bar"}` -> `{["foo"] = "bar"}` - `["foo" "bar"]` -> `{"foo", "bar"}` + - You may also write **mixed tables** using `toLuaObject`, using a special + syntax to describe a key's position in the table. Let's say you want to get + something like `{"foo", bar = "baz"}` expressed in Lua using Nix. The + appropriate Nix syntax to express mixed tables is as follows: + + ```nix + # Notice the position indicator, "@1" + { "@1" = "foo"; bar = "baz"; }; + ``` + + This will result in a mixed Lua table that is as follows: + + ```lua + {"foo", bar = "baz"} + ``` + 4. You can write raw Lua code using `lib.generators.mkLuaInline`. This function is part of nixpkgs, and is accessible without relying on **nvf**'s extended library. From 2853877219bc41b4605d8e7ad4605b866c248c27 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 21 Aug 2025 09:44:46 +0300 Subject: [PATCH 2/2] docs/configuring: add modules section Signed-off-by: NotAShelf Change-Id: I6a6a6964f2e65a11acab2a2f7413a5f94bff3815 --- docs/manual/configuring.md | 27 ++++++++++---- docs/manual/configuring/modules.md | 58 ++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 7 deletions(-) create mode 100644 docs/manual/configuring/modules.md diff --git a/docs/manual/configuring.md b/docs/manual/configuring.md index 95195f78..8293806f 100644 --- a/docs/manual/configuring.md +++ b/docs/manual/configuring.md @@ -1,21 +1,34 @@ # Configuring nvf {#ch-configuring} + + [helpful tips section]: #ch-helpful-tips -nvf allows for _very_ extensive configuration in Neovim through the Nix module -interface. The below chapters describe several of the options exposed in nvf for -your convenience. You might also be interested in the [helpful tips section] for -more advanced or unusual configuration options supported by nvf. + -Note that this section does not cover module _options_. For an overview of all -module options provided by nvf, please visit the [appendix](/nvf/options.html) +nvf allows for _very_ extensive configuration for your Neovim setups through a +Nix module interface. This interface allows you to express almost everything +using a single DSL, Nix. The below chapters describe several of the options +exposed in nvf for your convenience. You might also be interested in the +[helpful tips section] for more advanced or unusual configuration options +supported by nvf such as Nix/Lua hybrid setups. + +::: {.note} + +This section does not cover module _options_. For an overview of all module +options provided by nvf, please visit the [appendix](/nvf/options.html) + +::: ```{=include=} chapters configuring/custom-package.md configuring/custom-plugins.md configuring/overriding-plugins.md + +configuring/modules.md configuring/languages.md +configuring/autocmds.md + configuring/dags.md configuring/dag-entries.md -configuring/autocmds.md ``` diff --git a/docs/manual/configuring/modules.md b/docs/manual/configuring/modules.md new file mode 100644 index 00000000..5a75ee92 --- /dev/null +++ b/docs/manual/configuring/modules.md @@ -0,0 +1,58 @@ +## Using the Module Interface {#ch-module-interface} + +Before describing the module interface, it is worth nothing that NVF is a hybrid +wrapper. It does not lock you into one of Lua or Nix, and both languages are +considered first-class citizens for configuring your editor. However, Nix is the +primarily supported language for NVF. While [DAGs](#ch-using-dags) allow for the +surgical insertion of Lua code into your configuration, in most cases you will +be more interested in using or extending the Nix-based module system. + +### {#ch-using-modules} + +Up until v0.6, most modules exposed all supported plugin options as individual +module options. With the release of v0.6, almost every module has been converted +to a new `setupOpts` format that provides complete user freedom over a plugin's +`setup({})` function. + +The anatomy of a typical **plugin** module consists of two primary options: + +`vim...enable` and `vim...setupOpts`. The +first option is disabled by default, and dictates whether the plugin is enabled. +If set to `true`, the plugin will be enabled and added to your Neovim's runtime +path. The second is an attribute set (`{}`) that will be converted to the +plugin's setup table. From Lua-based setups you may be used to something like +this: + +```lua +require("nvim-autopairs").setup({ + check_ts = true, + disable_filetype = { "TelescopePrompt", "vim" } +}) +``` + +This is the typical setup table. It is sometimes expressed slightly differently +(e.g., the table might be stored as a variable) but the gist is that you pass a +table to the `setup()` function. The principle of `setupOpts` is the same. It +converts a Nix attribute set to a Lua table using the `toLuaObject` function +located in nvf's extended library. The same configuration would be expressed in +Nix as follows: + +```nix +{ + setupOpts = { + check_ts = true; # boolean + disable_filetype = ["TelescopePrompt" "vim"]; # Lua table + }; +} +``` + + + +The `setupOpts` option is freeform, so anything you put in it will be converted +to its Lua equivalent and will appear in your built `init.lua`. You can find +details about `toLuaObject` [here](#sec-details-of-toluaobject). The top-level +DAG entries in **nvf** are documented in the [DAG entries](#ch-dag-entries) +section. You can read more about DAGs in the [using DAGs](#ch-using-dags) +section. + +