lib: standardize use of lib and self

flake-modules/lib.nix

@@ -15,7 +15,7 @@
         # NOTE: this is the publicly documented flake output we've had for a while
         check = import ../lib/tests.nix { inherit lib pkgs; };
         # NOTE: user-facing so we must include the legacy `pkgs` argument
-        helpers = import ../lib { inherit lib pkgs; };
+        helpers = (import ../lib { inherit lib pkgs; }).public;
       }
     )
   );

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,15 +38,24 @@ 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 { };
 
+    # Our public API
+    # NOTE: internal attrs should be removed here
+    public = builtins.removeAttrs self [
+      "extendedLib"
+      "types" # Causes issues if someone does `with lib.nixvim;`
+      "public"
+    ];
+
     # Handle builders, which has some deprecated stuff that depends on `pkgs`
     builders = builders // deprecatedBuilders;
     inherit (self.builders)

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,18 +1,17 @@
 # Extends nixpkg's lib with our functions, as expected by our modules
 {
-  call,
   lib,
-  self,
+  self ? import ./. { inherit lib; },
 }:
 lib.extend (
   final: prev: {
     # Include our custom lib
-    nixvim = self;
+    nixvim = self.public;
 
     # Merge in our maintainers
     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,9 +31,9 @@ in
     lib.evalModules {
       modules = [ ../modules/top-level ] ++ modules;
       specialArgs = {
-        inherit lib;
+        lib = self.extendedLib;
         # TODO: deprecate `helpers`
-        helpers = self;
+        helpers = self.public;
       } // 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;
     };
 }