lib: standardize use of lib and self

- Drop `helpers` in internal useage
- Access nixvim's lib via `self`
- Access the (un-extended) lib via `lib`
- Build nixvim's types internally, before later merging into `lib.types`

While I like the idea of having `lib.nixvim` access internally within
our lib, keeping our lib (`self`) separate from the extended lib will be
better in the long-term.

Author: MattSturgeon

lib/autocmd-helpers.nix

@@ -1,4 +1,7 @@
-{ lib, helpers }:
+{
+  lib,
+  self,
+}:
 let
   inherit (lib) types;
 in
@@ -14,34 +17,34 @@ rec {
   };
 
   autoCmdOptions = {
-    event = helpers.mkNullOrOption (with types; either str (listOf str)) ''
+    event = self.mkNullOrOption (with types; either str (listOf str)) ''
       The event or events to register this autocommand.
     '';
 
-    group = helpers.mkNullOrOption (with types; either str int) ''
+    group = self.mkNullOrOption (with types; either str int) ''
       The autocommand group name or id to match against.
     '';
 
-    pattern = helpers.mkNullOrOption (with types; either str (listOf str)) ''
+    pattern = self.mkNullOrOption (with types; either str (listOf str)) ''
       Pattern or patterns to match literally against.
     '';
 
-    buffer = helpers.mkNullOrOption types.int ''
+    buffer = self.mkNullOrOption types.int ''
       Buffer number for buffer local autocommands |autocmd-buflocal|.
       Cannot be used with `pattern`.
     '';
 
     # Introduced early October 2023.
     # TODO remove in early December 2023.
-    description = helpers.mkNullOrOption types.str ''
+    description = self.mkNullOrOption types.str ''
       DEPRECATED, please use `desc`.
     '';
 
-    desc = helpers.mkNullOrOption types.str ''
+    desc = self.mkNullOrOption types.str ''
       A textual description of this autocommand.
     '';
 
-    callback = helpers.mkNullOrOption (with types; either str rawLua) ''
+    callback = self.mkNullOrOption (with types; either str self.types.rawLua) ''
       A function or a string.
       - if a string, the name of a Vimscript function to call when this autocommand is triggered.
       - Otherwise, a Lua function which is called when this autocommand is triggered.
@@ -65,13 +68,13 @@ rec {
         }
     '';
 
-    command = helpers.defaultNullOpts.mkStr "" ''
+    command = self.defaultNullOpts.mkStr "" ''
       Vim command to execute on event. Cannot be used with `callback`.
     '';
 
-    once = helpers.defaultNullOpts.mkBool false "Run the autocommand only once.";
+    once = self.defaultNullOpts.mkBool false "Run the autocommand only once.";
 
-    nested = helpers.defaultNullOpts.mkBool false "Run nested autocommands.";
+    nested = self.defaultNullOpts.mkBool false "Run nested autocommands.";
   };
 
   autoCmdOption = types.submodule { options = autoCmdOptions; };

lib/builders.nix

@@ -1,6 +1,6 @@
 { lib }:
-# NOTE: use local recursion instead of accessing `lib.nixvim.builders`.
-# The latter isn't a fixed shape since it may get the deprecated functions meregd in,
+# NOTE: use local recursion instead of accessing `self.builders`.
+# The latter isn't a fixed shape since it may get the deprecated functions merged in,
 # which would lead to infinite recursion.
 lib.fix (builders: {
   # Curry a nixpkgs instance into the *With functions below, dropping the `With` suffix
@@ -147,7 +147,7 @@ lib.fix (builders: {
       prev:
       {
         nativeBuildInputs = prev.nativeBuildInputs or [ ] ++ [
-          (lib.nixvim.builders.byteCompileLuaHookWith pkgs)
+          (builders.byteCompileLuaHookWith pkgs)
         ];
       }
       // lib.optionalAttrs (prev ? buildCommand) {

lib/default.nix

@@ -10,9 +10,12 @@ lib.fix (
   let
     # Used when importing parts of helpers
     call = lib.callPackageWith {
-      inherit call pkgs self;
-      helpers = self; # TODO: stop using `helpers` in the subsections
-      lib = self.extendedLib;
+      inherit
+        call
+        lib
+        pkgs
+        self
+        ;
     };
 
     # Define this outside of the attrs to avoid infinite recursion,
@@ -35,12 +38,13 @@ lib.fix (
   {
     autocmd = call ./autocmd-helpers.nix { };
     deprecation = call ./deprecation.nix { };
-    extendedLib = call ./extend-lib.nix { inherit lib; };
+    extendedLib = call ./extend-lib.nix { }; # TODO: provide an overlay instead
     keymaps = call ./keymap-helpers.nix { };
     lua = call ./to-lua.nix { };
     modules = call ./modules.nix { };
     neovim-plugin = call ./neovim-plugin.nix { };
     options = call ./options.nix { };
+    types = call ./types.nix { }; # NOTE: you should usually prefer the extended `lib.types`
     utils = call ./utils.nix { inherit _nixvimTests; };
     vim-plugin = call ./vim-plugin.nix { };
 

lib/deprecation.nix

@@ -1,4 +1,7 @@
-{ lib }:
+{
+  lib,
+  self,
+}:
 rec {
   # Get a (sub)option by walking the path,
   # checking for submodules along the way
@@ -54,7 +57,7 @@ rec {
       let
         option = lib.toList option';
         oldPath = oldPrefix ++ option;
-        newPath = newPrefix ++ map lib.nixvim.toSnakeCase option;
+        newPath = newPrefix ++ map self.toSnakeCase option;
       in
       lib.mkRenamedOptionModule oldPath newPath
     );

lib/extend-lib.nix

@@ -1,8 +1,7 @@
 # Extends nixpkg's lib with our functions, as expected by our modules
 {
-  call,
   lib,
-  self,
+  self ? import ./. { inherit lib; },
 }:
 lib.extend (
   final: prev: {
@@ -13,6 +12,6 @@ lib.extend (
     maintainers = prev.maintainers // import ./maintainers.nix;
 
     # Merge in our custom types
-    types = prev.types // call ./types.nix { };
+    types = prev.types // self.types;
   }
 )

lib/keymap-helpers.nix

@@ -1,27 +1,30 @@
-{ lib, helpers }:
+{
+  lib,
+  self,
+}:
 let
   inherit (lib) optionalAttrs isAttrs types;
 in
 rec {
   # These are the configuration options that change the behavior of each mapping.
   mapConfigOptions = {
-    silent = helpers.defaultNullOpts.mkBool false "Whether this mapping should be silent. Equivalent to adding `<silent>` to a map.";
+    silent = self.defaultNullOpts.mkBool false "Whether this mapping should be silent. Equivalent to adding `<silent>` to a map.";
 
-    nowait = helpers.defaultNullOpts.mkBool false "Whether to wait for extra input on ambiguous mappings. Equivalent to adding `<nowait>` to a map.";
+    nowait = self.defaultNullOpts.mkBool false "Whether to wait for extra input on ambiguous mappings. Equivalent to adding `<nowait>` to a map.";
 
-    script = helpers.defaultNullOpts.mkBool false "Equivalent to adding `<script>` to a map.";
+    script = self.defaultNullOpts.mkBool false "Equivalent to adding `<script>` to a map.";
 
-    expr = helpers.defaultNullOpts.mkBool false "Means that the action is actually an expression. Equivalent to adding `<expr>` to a map.";
+    expr = self.defaultNullOpts.mkBool false "Means that the action is actually an expression. Equivalent to adding `<expr>` to a map.";
 
-    unique = helpers.defaultNullOpts.mkBool false "Whether to fail if the map is already defined. Equivalent to adding `<unique>` to a map.";
+    unique = self.defaultNullOpts.mkBool false "Whether to fail if the map is already defined. Equivalent to adding `<unique>` to a map.";
 
-    noremap = helpers.defaultNullOpts.mkBool true "Whether to use the `noremap` variant of the command, ignoring any custom mappings on the defined action. It is highly advised to keep this on, which is the default.";
+    noremap = self.defaultNullOpts.mkBool true "Whether to use the `noremap` variant of the command, ignoring any custom mappings on the defined action. It is highly advised to keep this on, which is the default.";
 
-    remap = helpers.defaultNullOpts.mkBool false "Make the mapping recursive. Inverses `noremap`.";
+    remap = self.defaultNullOpts.mkBool false "Make the mapping recursive. Inverses `noremap`.";
 
-    desc = helpers.mkNullOrOption lib.types.str "A textual description of this keybind, to be shown in which-key, if you have it.";
+    desc = self.mkNullOrOption lib.types.str "A textual description of this keybind, to be shown in which-key, if you have it.";
 
-    buffer = helpers.defaultNullOpts.mkBool false "Make the mapping buffer-local. Equivalent to adding `<buffer>` to a map.";
+    buffer = self.defaultNullOpts.mkBool false "Make the mapping buffer-local. Equivalent to adding `<buffer>` to a map.";
   };
 
   modes = {
@@ -118,9 +121,9 @@ rec {
           // (optionalAttrs (isAttrs action || action) {
             action = lib.mkOption (
               {
-                type = types.maybeRaw types.str;
+                type = self.types.maybeRaw types.str;
                 description = "The action to execute.";
-                apply = v: if options.lua.isDefined or false && config.lua then helpers.mkRaw v else v;
+                apply = v: if options.lua.isDefined or false && config.lua then self.mkRaw v else v;
               }
               // (optionalAttrs (isAttrs action) action)
               // (optionalAttrs (defaults ? action) { default = defaults.action; })

lib/modules.nix

@@ -31,7 +31,7 @@ in
     lib.evalModules {
       modules = [ ../modules/top-level ] ++ modules;
       specialArgs = {
-        inherit lib;
+        lib = self.extendedLib;
         # TODO: deprecate `helpers`
         helpers = self;
       } // extraSpecialArgs;

lib/neovim-plugin.nix

@@ -1,4 +1,7 @@
-{ lib, helpers }:
+{
+  lib,
+  self,
+}:
 {
   # TODO: DEPRECATED: use the `settings` option instead
   extraOptionsOptions = {
@@ -68,7 +71,7 @@
 
           setupCode = ''
             require('${luaName}')${setup}(${
-              lib.optionalString (cfg ? settings) (helpers.toLuaObject cfg.settings)
+              lib.optionalString (cfg ? settings) (self.toLuaObject cfg.settings)
             })
           '';
 
@@ -106,15 +109,15 @@
                   };
             }
             // lib.optionalAttrs hasSettings {
-              settings = helpers.mkSettingsOption {
+              settings = self.mkSettingsOption {
                 description = settingsDescription;
                 options = settingsOptions;
                 example = settingsExample;
               };
             }
             // lib.optionalAttrs hasConfigAttrs {
               luaConfig = lib.mkOption {
-                type = lib.types.pluginLuaConfig;
+                type = self.types.pluginLuaConfig;
                 default = { };
                 description = "The plugin's lua configuration";
               };
@@ -162,6 +165,6 @@
         ++ (lib.optional deprecateExtraOptions (
           lib.mkRenamedOptionModule (basePluginPath ++ [ "extraOptions" ]) settingsPath
         ))
-        ++ (lib.nixvim.mkSettingsRenamedOptionModules basePluginPath settingsPath optionsRenamedToSettings);
+        ++ self.mkSettingsRenamedOptionModules basePluginPath settingsPath optionsRenamedToSettings;
     };
 }

lib/options.nix

@@ -1,6 +1,10 @@
-{ lib, helpers }:
+{
+  lib,
+  self,
+}:
 let
   inherit (lib) types;
+  types' = self.types;
 
   removed = lib.mapAttrs (name: msg: throw "${name} is removed. ${msg}") {
     # Removed 2024-09-05
@@ -87,16 +91,16 @@ rec {
     );
   mkCompositeOption = description: options: mkCompositeOption' { inherit description options; };
 
-  mkNullOrStr' = args: mkNullOrOption' (args // { type = with types; maybeRaw str; });
+  mkNullOrStr' = args: mkNullOrOption' (args // { type = types'.maybeRaw types.str; });
   mkNullOrStr = description: mkNullOrStr' { inherit description; };
 
   mkNullOrLua' =
     args:
     mkNullOrOption' (
       args
       // {
-        type = types.strLua;
-        apply = helpers.mkRaw;
+        type = types'.strLua;
+        apply = self.mkRaw;
       }
     );
   mkNullOrLua = description: mkNullOrLua' { inherit description; };
@@ -106,8 +110,8 @@ rec {
     mkNullOrOption' (
       args
       // {
-        type = types.strLuaFn;
-        apply = helpers.mkRaw;
+        type = types'.strLuaFn;
+        apply = self.mkRaw;
       }
     );
   mkNullOrLuaFn = description: mkNullOrLua' { inherit description; };
@@ -117,8 +121,8 @@ rec {
     mkNullOrOption' (
       args
       // {
-        type = with types; either strLua type;
-        apply = v: if lib.isString v then helpers.mkRaw v else v;
+        type = types.either types'.strLua type;
+        apply = v: if lib.isString v then self.mkRaw v else v;
       }
     );
   mkNullOrStrLuaOr = type: description: mkNullOrStrLuaOr' { inherit type description; };
@@ -128,8 +132,8 @@ rec {
     mkNullOrOption' (
       args
       // {
-        type = with types; either strLuaFn type;
-        apply = v: if lib.isString v then helpers.mkRaw v else v;
+        type = types.either types'.strLuaFn type;
+        apply = v: if lib.isString v then self.mkRaw v else v;
       }
     );
   mkNullOrStrLuaFnOr = type: description: mkNullOrStrLuaFnOr' { inherit type description; };
@@ -149,14 +153,14 @@ rec {
     in
     rec {
       # TODO: removed 2024-06-14; remove stub 2024-09-01
-      mkDesc = abort "mkDesc has been removed. Use the `pluginDefault` argument or `helpers.pluginDefaultText`.";
+      mkDesc = abort "mkDesc has been removed. Use the `pluginDefault` argument or `self.pluginDefaultText`.";
 
       mkNullable' = args: mkNullOrOption' (processDefaultNullArgs args);
       mkNullable =
         type: pluginDefault: description:
         mkNullable' { inherit type pluginDefault description; };
 
-      mkNullableWithRaw' = { type, ... }@args: mkNullable' (args // { type = types.maybeRaw type; });
+      mkNullableWithRaw' = { type, ... }@args: mkNullable' (args // { type = types'.maybeRaw type; });
       mkNullableWithRaw =
         type: pluginDefault: description:
         mkNullableWithRaw' { inherit type pluginDefault description; };
@@ -188,7 +192,7 @@ rec {
       mkUnsignedInt' = args: mkNullableWithRaw' (args // { type = types.ints.unsigned; });
       mkUnsignedInt = pluginDefault: description: mkUnsignedInt' { inherit pluginDefault description; };
       mkFlagInt = pluginDefault: description: mkFlagInt' { inherit pluginDefault description; };
-      mkFlagInt' = args: mkNullableWithRaw' (args // { type = types.intFlag; });
+      mkFlagInt' = args: mkNullableWithRaw' (args // { type = types'.intFlag; });
       mkBool' = args: mkNullableWithRaw' (args // { type = types.bool; });
       mkBool = pluginDefault: description: mkBool' { inherit pluginDefault description; };
       mkStr' = args: mkNullableWithRaw' (args // { type = types.str; });
@@ -198,13 +202,13 @@ rec {
       mkAttributeSet = pluginDefault: description: mkAttributeSet' { inherit pluginDefault description; };
 
       mkListOf' =
-        { type, ... }@args: mkNullable' (args // { type = with types; listOf (maybeRaw type); });
+        { type, ... }@args: mkNullable' (args // { type = types.listOf (types'.maybeRaw type); });
       mkListOf =
         type: pluginDefault: description:
         mkListOf' { inherit type pluginDefault description; };
 
       mkAttrsOf' =
-        { type, ... }@args: mkNullable' (args // { type = with types; attrsOf (maybeRaw type); });
+        { type, ... }@args: mkNullable' (args // { type = types.attrsOf (types'.maybeRaw type); });
       mkAttrsOf =
         type: pluginDefault: description:
         mkAttrsOf' { inherit type pluginDefault description; };
@@ -274,10 +278,7 @@ rec {
               ]);
             apply = lib.mapNullable (
               value:
-              if lib.isInt value then
-                value
-              else
-                helpers.mkRaw "vim.diagnostic.severity.${lib.strings.toUpper value}"
+              if lib.isInt value then value else self.mkRaw "vim.diagnostic.severity.${lib.strings.toUpper value}"
             );
           }
         );
@@ -288,10 +289,9 @@ rec {
         mkNullOrOption' (
           args
           // {
-            type = with types; either ints.unsigned logLevel;
+            type = with types; either ints.unsigned types'.logLevel;
             apply = lib.mapNullable (
-              value:
-              if lib.isInt value then value else helpers.mkRaw "vim.log.levels.${lib.strings.toUpper value}"
+              value: if lib.isInt value then value else self.mkRaw "vim.log.levels.${lib.strings.toUpper value}"
             );
           }
         );