Add lib.showOptionParent

lib/default.nix

@@ -94,8 +94,9 @@ let
     inherit (self.lists) singleton forEach map foldr fold foldl foldl' imap0 imap1
       filter ifilter0 concatMap flatten remove findSingle findFirst any all count
       optional optionals toList range replicate partition zipListsWith zipLists
-      reverseList listDfs toposort sort sortOn naturalSort compareLists take
-      drop sublist last init crossLists unique allUnique intersectLists
+      reverseList listDfs toposort sort sortOn naturalSort compareLists
+      take drop dropEnd sublist last init
+      crossLists unique allUnique intersectLists
       subtractLists mutuallyExclusive groupBy groupBy' concatLists genList
       length head tail elem elemAt isList;
     inherit (self.strings) concatStrings concatMapStrings concatImapStrings
@@ -150,7 +151,7 @@ let
       getValues getFiles
       optionAttrSetToDocList optionAttrSetToDocList'
       scrubOptionValue literalExpression literalExample
-      showOption showOptionWithDefLocs showFiles
+      showOption showOptionParent showOptionWithDefLocs showFiles
       unknownModule mkOption mkPackageOption mkPackageOptionMD
       literalMD;
     inherit (self.types) isType setType defaultTypeMerge defaultFunctor

lib/lists.nix

@@ -6,6 +6,7 @@ let
   inherit (lib.strings) toInt;
   inherit (lib.trivial) compare min id warn pipe;
   inherit (lib.attrsets) mapAttrs;
+  inherit (lib) max;
 in
 rec {
 
@@ -1484,6 +1485,46 @@ rec {
     count:
     list: sublist count (length list) list;
 
+  /**
+    Remove the last (at most) N elements of a list.
+
+
+    # Inputs
+
+    `count`
+
+    : Number of elements to drop
+
+    `list`
+
+    : Input list
+
+    # Type
+
+    ```
+    dropEnd :: Int -> [a] -> [a]
+    ```
+
+    # Examples
+
+    :::{.example}
+    ## `lib.lists.dropEnd` usage example
+
+    ```nix
+      dropEnd 2 [ "a" "b" "c" "d" ]
+      => [ "a" "b" ]
+      dropEnd 2 [ ]
+      => [ ]
+    ```
+    :::
+
+   */
+  dropEnd =
+    n: xs:
+      take
+        (max 0 (length xs - n))
+        xs;
+
   /**
     Whether the first list is a prefix of the second list.
 

lib/options.nix

@@ -432,6 +432,40 @@ rec {
         then part
         else lib.strings.escapeNixIdentifier part;
     in (concatStringsSep ".") (map escapeOptionPart parts);
+
+  /**
+    Show the option path, except for the last `n` elements.
+
+    This can be used to refer to groups of options in documentation.
+
+    # Inputs
+
+    - `opt`: The option path.
+
+    - `n`: The number of elements to exclude from the end.
+
+    # Example
+
+    ```nix
+    showOptionParent config.services.foo.settings.bar 1
+    => "services.foo.settings"
+    ```
+
+    ```nix
+    mkOption {
+      type = types.str;
+      description = "The settings file for foo.";
+      default = tomlFormat.generate "foo.toml" opt.settings.value;
+      defaultText = lib.literalMD ''
+        Generated TOML file based on `${showOptionParent opt.settings.bar 1}`
+      '';
+    }
+    ```
+
+   */
+  showOptionParent = opt: n:
+    showOption (lib.dropEnd n opt);
+
   showFiles = files: concatStringsSep " and " (map (f: "`${f}'") files);
 
   showDefs = defs: concatMapStrings (def:

lib/tests/misc.nix

@@ -854,6 +854,30 @@ runTests {
     ([ 1 2 3 ] == (take 4 [  1 2 3 ]))
   ];
 
+  testDrop = let inherit (lib) drop; in testAllTrue [
+    # list index -1 is out of bounds
+    # ([ 1 2 3 ] == (drop (-1) [  1 2 3 ]))
+    (drop 0 [ 1 2 3 ] == [ 1 2 3 ])
+    (drop 1 [ 1 2 3 ] == [ 2 3 ])
+    (drop 2 [ 1 2 3 ] == [ 3 ])
+    (drop 3 [ 1 2 3 ] == [ ])
+    (drop 4 [ 1 2 3 ] == [ ])
+    (drop 0 [ ] == [ ])
+    (drop 1 [ ] == [ ])
+  ];
+
+  testDropEnd = let inherit (lib) dropEnd; in testAllTrue [
+    (dropEnd 0 [ 1 2 3 ] == [ 1 2 3 ])
+    (dropEnd 1 [ 1 2 3 ] == [ 1 2 ])
+    (dropEnd 2 [ 1 2 3 ] == [ 1 ])
+    (dropEnd 3 [ 1 2 3 ] == [ ])
+    (dropEnd 4 [ 1 2 3 ] == [ ])
+    (dropEnd 0 [ ] == [ ])
+    (dropEnd 1 [ ] == [ ])
+    (dropEnd (-1) [ 1 2 3 ] == [ 1 2 3 ])
+    (dropEnd (-1) [ ] == [ ])
+  ];
+
   testListHasPrefixExample1 = {
     expr = lists.hasPrefix [ 1 2 ] [ 1 2 3 4 ];
     expected = true;

lib/tests/modules.sh

@@ -139,6 +139,8 @@ checkConfigOutput '^true$' config.assertion ./gvariant.nix
 
 checkConfigOutput '"ok"' config.result ./specialArgs-lib.nix
 
+checkConfigOutput '"ok"' config.result ./misc.nix
+
 # https://github.com/NixOS/nixpkgs/pull/131205
 # We currently throw this error already in `config`, but throwing in `config.wrong1` would be acceptable.
 checkConfigError 'It seems as if you.re trying to declare an option by placing it into .config. rather than .options.' config.wrong1 ./error-mkOption-in-config.nix

lib/tests/modules/misc.nix

@@ -0,0 +1,16 @@
+{ config, lib, options, ... }:
+
+{
+  options = {
+    result = lib.mkOption { };
+  };
+
+  config.result =
+    assert options._module.args.loc == [ "_module" "args" ];
+    assert lib.showOption options._module.args.loc == "_module.args";
+    assert lib.showOptionParent options._module.args.loc 1 == "_module";
+    assert lib.showOptionParent options._module.args.loc 2 == "";
+    assert lib.showOptionParent options._module.args.loc 3 == "";
+    "ok";
+
+}