fish: add functions to fish module

restructure shellFunctions to use a submodule

Author: preprocessor

nixos/modules/programs/fish.nix

@@ -21,15 +21,63 @@ let
 
   fishFunctions = lib.mapAttrs' (
     name: value:
+    assert !(lib.hasInfix " " name) || throw "Function names cannot have spaces: '${name}'";
+    assert
+      !(lib.elem name [
+        "["
+        "_"
+        "and"
+        "argparse"
+        "begin"
+        "break"
+        "builtin"
+        "case"
+        "command"
+        "continue"
+        "else"
+        "end"
+        "eval"
+        "exec"
+        "for"
+        "function"
+        "if"
+        "not"
+        "or"
+        "read"
+        "return"
+        "set"
+        "status"
+        "string"
+        "switch"
+        "test"
+        "time"
+        "while"
+      ])
+      || throw "Cannot set function name to reserved name: '${name}'";
     let
-      fileName = lib.elemAt (lib.splitString " " name) 0;
-      body = if lib.isPath value then lib.readFile value else value;
+      optStr = n: lib.optionalString (n != null);
+      optPair = n: v: optStr n ''--${v}="${n}"'';
+
+      modifiers =
+        with value;
+        lib.join " " [
+          (lib.optionalString noScopeShadowing "--no-scope-shadowing")
+          (optPair description "description")
+          (optPair wraps "wraps")
+          (optPair onVariable "on-variable")
+          (optPair onJobExit "on-job-exit")
+          (optPair onProcessExit "on-process-exit")
+          (optPair onSignal "on-signal")
+          (optPair inheritVariable "inherit-variable")
+          (optStr onEvent (lib.concatMapStringsSep " " (ev: "--on-event=${ev}") onEvent))
+          (optStr argumentNames "--argument-names=${toString argumentNames}")
+        ];
     in
     {
-      name = "fish/functions/${fileName}.fish";
-      value.source = indentFishFile "${fileName}.fish" ''
-        function ${name}
-          ${lib.removeSuffix "\n" body}
+      name = "fish/functions/${name}.fish";
+      value.source = indentFishFile "${name}.fish" ''
+        function ${name}${modifiers}
+          ${lib.removeSuffix "\n" value.body}
         end
       '';
     }
@@ -148,26 +196,141 @@ in
       };
 
       shellFunctions = lib.mkOption {
-        default = { };
-        type = with lib.types; attrsOf (either str path);
         description = ''
-          Set of custom fish functions.
+          The function name. Function names cannot be reserved words or have spaces. These are elements of fish
+          syntax or builtin commands which are essential for the operations of the shell. Current reserved
+          words are [, _, and, argparse, begin, break, builtin, case, command, continue, else, end, eval, exec, for, function, if, not, or, read, return, set, status, string, switch, test, time, and while.
+
+          See the documentation for [fish functions](https://fishshell.com/docs/current/cmds/function.html) for further information
         '';
-        example = lib.literalExpression ''
-          "ll" = "ls -l $argv";
-          "mcd -d 'Create a directory and set CWD'" = '''
-            command mkdir $argv
-            if test $status = 0
-              switch $argv[(count $argv)]
-                case '-*'
-
-                case '*'
-                  cd $argv[(count $argv)]
-                  return
+        example = {
+          ll.body = "ls -l $argv";
+          mcd = {
+            description = "Create a directory and set CWD";
+            body = ''
+              command mkdir $argv
+              if test $status = 0
+                switch $argv[(count $argv)]
+                  case '-*'
+
+                  case '*'
+                    cd $argv[(count $argv)]
+                    return
+                end
               end
-            end
-          ''';
-        '';
+            '';
+          };
+        };
+        type = lib.types.attrsOf (
+          lib.types.submodule {
+            options = {
+              body = lib.mkOption {
+                type = lib.types.str;
+                description = ''
+                  The function body. You may provide a path or a string containing the fish function body.
+                '';
+              };
+
+              argumentNames = lib.mkOption {
+                type = with lib.types; nullOr (listOf str);
+                description = ''
+                  Assigns the value of successive command-line arguments to the values in names.
+                  These are the same arguments given in [argv](https://fishshell.com/docs/current/language.html#envvar-argv), and are still available there
+                  (unless --inherit-variable argv was used or one of the given NAMES is argv).
+                  See also [Argument Handling](https://fishshell.com/docs/current/language.html#variables-argv).
+                '';
+              };
+
+              description = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  A description of what the function does, suitable as a completion description.
+                '';
+              };
+
+              wraps = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  Inherit completions from the given wraps value. This is used to say that this function completes
+                  like that command, for example if you’re creating an alias. See the documentation for [complete](https://fishshell.com/docs/current/cmds/complete.html) for more information.
+
+                  If the wrapped command is the same as the function name, this will be ignored.
+                '';
+              };
+
+              onEvent = lib.mkOption {
+                type = with lib.types; nullOr (listOf str);
+                description = ''
+                  Run this function when one of the specified named event is emitted. fish internally generates named
+                  events, for example, when showing the prompt. Custom events can be emitted using the [emit](https://fishshell.com/docs/current/cmds/emit.html) command.
+                '';
+              };
+
+              onVariable = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  Run this function when the variable name changes value. Note that fish makes no guarantees on any
+                  particular timing or even that the function will be run for every single set. Rather it will be run
+                  when the variable has been set at least once, possibly skipping some values or being run when the
+                  variable has been set to the same value (except for universal variables set in other shells - only
+                  changes in the value will be picked up for those)
+                '';
+              };
+
+              onJobExit = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  Run this function when the job containing a child process with the given process ID exits. Instead of
+                  a PID, the string ‘caller’ can be specified. This is only allowed when in a command substitution, and
+                  will result in the handler being triggered by the exit of the job which created this command
+                  substitution. This will not trigger for disowned jobs.
+                '';
+              };
+
+              onProcessExit = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  Run this function when the fish child process with the specified PID exits. Instead of a PID, for
+                  backward compatibility, “%self” can be specified as an alias for $fish_pid, and the function will be
+                  run when the current fish instance exits. This will not trigger for [disowned](https://fishshell.com/docs/current/cmds/disown.html) jobs.
+                '';
+              };
+
+              onSignal = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  Run this function when the signal is delivered. The signal can be a signal number, or the signal name,
+                  such as SIGHUP (or just HUP). Note that the signal must have been delivered to fish; for example,
+                  ctrl-c sends SIGINT to the foreground process group, which will not be fish if you are running another
+                  command at the time. Observing a signal will prevent fish from exiting in response to that signal.
+                '';
+              };
+
+              noScopeShadowing = lib.mkOption {
+                type = lib.types.bool;
+                default = false;
+                description = ''
+                  Allows the function to access the variables of calling functions. Normally, any variables inside the
+                  function that have the same name as variables from the calling function are “shadowed”, and their
+                  contents are independent of the calling function.
+                '';
+              };
+
+              inheritVariable = lib.mkOption {
+                type = with lib.types; nullOr str;
+                description = ''
+                  Snapshots the value of the given variable and defines a local variable with that same name and value
+                  when the function is defined. This is similar to a closure in other languages like Python but a bit
+                  different. Note the word “snapshot” in the first sentence. If you change the value of the variable
+                  after defining the function, even if you do so in the same scope (typically another function) the new
+                  value will not be used by the function you just created using this option. See the function notify
+                  example below for how this might be used.
+                '';
+              };
+            };
+
+          }
+        );
       };
 
       shellInit = lib.mkOption {