mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-26 12:53:13 +00:00
06400b83b1
Add the --wraps option to 'complete' and 'function'. This allows a command to (recursively) inherit the completions of a wrapped command. Fixes #393. When evaluating a completion, we inspect the entire "wrap chain" for a command, i.e. we follow the sequence of wrapping until we either hit a loop (which we silently ignore) or the end of the chain. We then evaluate completions as if the wrapping command were substituted with the wrapped command. Currently this only works for commands, i.e. 'complete --command gco --wraps git\ checkout' won't work (that would seem to encroaching on abbreviations anyways). It might be useful to show an error message for that case. The commandline builtin reflects the commandline with the wrapped command substituted in, so e.g. git completions (which inspect the command line) will just work. This sort of command line munging is also performed by 'complete -C' so it's not totally without precedent. 'alias will also now mark its generated function as wrapping the 'target.
62 lines
3.4 KiB
Text
62 lines
3.4 KiB
Text
\section function function - create a function
|
|
|
|
\subsection function-synopsis Synopsis
|
|
<code>function [OPTIONS] NAME; BODY; end </code>
|
|
|
|
\subsection function-description Description
|
|
|
|
\c function creates a new function \c NAME with the body <code>BODY</code>.
|
|
|
|
A function is a list of commands that will be executed when the name of the
|
|
function is given as a command.
|
|
|
|
The following options are available:
|
|
|
|
- <code>-a NAMES</code> or <code>--argument-names NAMES</code> assigns the value of successive command-line arguments to the names given in NAMES.
|
|
- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description.
|
|
- <code>-w WRAPPED_COMMAND</code> or \c --wraps=WRAPPED_COMMAND causes the function to inherit completions from the given wrapped command. See the documentation for \c complete for more information.
|
|
- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
|
|
- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
|
|
- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits.
|
|
- <code>-s</code> or <code>--on-signal SIGSPEC</code> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
|
|
- \c -S or \c --no-scope-shadowing 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 is independent of the calling function.
|
|
- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value.
|
|
|
|
If the user enters any additional arguments after the function, they
|
|
are inserted into the environment <a href="index.html#variables-arrays">variable array</a>
|
|
<code>$argv</code>. If the \c --argument-names option is provided, the arguments are
|
|
also assigned to names specified in that option.
|
|
|
|
By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the <a href="#emit">emit</a> builtin. Fish generates the following named events:
|
|
|
|
- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed.
|
|
- \c fish_command_not_found, which is emitted whenever a command lookup failed.
|
|
|
|
\subsection function-example Example
|
|
|
|
<pre>
|
|
function ll
|
|
ls -l $argv
|
|
end
|
|
</pre>
|
|
|
|
will run the \c ls command, using the \c -l option, while passing on any additional files and switches to \c ls.
|
|
|
|
<pre>
|
|
function mkdir -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
|
|
end
|
|
end
|
|
end
|
|
</pre>
|
|
|
|
will run the mkdir command, and if it is successful, change the
|
|
current working directory to the one just created.
|
|
|