fish-shell/doc_src/functions.txt

\section functions functions - print or erase functions

\subsection functions-synopsis Synopsis
\fish{synopsis}
functions [ -a | --all ] [ -n | --names ]
functions [ -D | --details ] [ -v ] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [ -e | -q ] FUNCTIONS...
\endfish

\subsection functions-description Description

`functions` prints or erases functions.

The following options are available:

- `-a` or `--all` lists all functions, even those whose name starts with an underscore.

- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.

- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.

- `-e` or `--erase` causes the specified functions to be erased.

- `-D` or `--details` reports the path name where each function is defined or could be autoloaded, `stdin` if the function was defined interactively or on the command line or by reading stdin, and `n/a` if the function isn't available. If the `--verbose` option is also specified then five lines are written:

    -# the pathname as already described,
    -# `autoloaded`, `not-autoloaded` or `n/a`,
    -# the line number within the file or zero if not applicable,
    -# `scope-shadowing` if the function shadows the vars in the calling function (the normal case if it wasn't defined with `--no-scope-shadowing`), else `no-scope-shadowing`, or `n/a` if the function isn't defined,
    -# the function description minimally escaped so it is a single line or `n/a` if the function isn't defined.

You should not assume that only five lines will be written since we may add additional information to the output in the future.

- `-n` or `--names` lists the names of all defined functions.

- `-q` or `--query` tests if the specified functions exist.

- `-v` or `--verbose` will make some output more verbose.

- `-H` or `--handlers` will show all event handlers.

- `-t` or `--handlers-type TYPE` will show all event handlers matching the given type

The default behavior of `functions`, when called with no arguments, is to print the names of all defined functions. Unless the `-a` option is given, no functions starting with underscores are not included in the output.

If any non-option parameters are given, the definition of the specified functions are printed.

Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.

Copying a function using `-c` copies only the body of the function, and does not attach any event notifications from the original function.

Only one function's description can be changed in a single invocation of `functions -d`.

The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option.


\subsection functions-example Examples
\fish
functions -n
# Displays a list of currently-defined functions

functions -c foo bar
# Copies the 'foo' function to a new function called 'bar'

functions -e bar
# Erases the function `bar`
\endfish
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 13:31:55 +00:00			`\section functions functions - print or erase functions`

Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			`\subsection functions-synopsis Synopsis`
Simplify styling 2014-08-01 12:25:41 +00:00			`\fish{synopsis}`
Consistency fixes 2014-08-26 18:19:24 +00:00			`functions [ -a \| --all ] [ -n \| --names ]`
rename --metadata to --details Discussion in issue #3295 resulted in a decisions to rename the functions --metadata flag to --details. This also fixes a bug in the definition of the short flags for the `functions` command. The `-e` flag does not take an argument and therefore should not be defined as `e:`. Notice that the long form, `--erase`, specifies `no_argument`. This discrepency happened to work due to a quirk of how the flag parsing loop was written. 2017-05-01 02:53:13 +00:00			`functions [ -D \| --details ] [ -v ] FUNCTION`
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 07:56:01 +00:00			`functions -c OLDNAME NEWNAME`
			`functions -d DESCRIPTION FUNCTION`
Consistency fixes 2014-08-26 18:19:24 +00:00			`functions [ -e \| -q ] FUNCTIONS...`
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			`\endfish`
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 13:31:55 +00:00
			`\subsection functions-description Description`

Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			`functions` prints or erases functions.
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 13:31:55 +00:00
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 07:56:01 +00:00			`The following options are available:`

implement means to learn about a functions source This implements a way to use the `functions` command to perform introspection to learn about the characteristics of a function. Such as where it came from. Fixes #3295 2017-01-10 06:49:33 +00:00			- `-a` or `--all` lists all functions, even those whose name starts with an underscore.
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			- `-e` or `--erase` causes the specified functions to be erased.
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00
rename --metadata to --details Discussion in issue #3295 resulted in a decisions to rename the functions --metadata flag to --details. This also fixes a bug in the definition of the short flags for the `functions` command. The `-e` flag does not take an argument and therefore should not be defined as `e:`. Notice that the long form, `--erase`, specifies `no_argument`. This discrepency happened to work due to a quirk of how the flag parsing loop was written. 2017-05-01 02:53:13 +00:00			- `-D` or `--details` reports the path name where each function is defined or could be autoloaded, `stdin` if the function was defined interactively or on the command line or by reading stdin, and `n/a` if the function isn't available. If the `--verbose` option is also specified then five lines are written:
implement means to learn about a functions source This implements a way to use the `functions` command to perform introspection to learn about the characteristics of a function. Such as where it came from. Fixes #3295 2017-01-10 06:49:33 +00:00
			`-# the pathname as already described,`
			-# `autoloaded`, `not-autoloaded` or `n/a`,
			`-# the line number within the file or zero if not applicable,`
add description to `functions -m -v` output Fixes #597 2017-03-14 00:22:33 +00:00			-# `scope-shadowing` if the function shadows the vars in the calling function (the normal case if it wasn't defined with `--no-scope-shadowing`), else `no-scope-shadowing`, or `n/a` if the function isn't defined,
			-# the function description minimally escaped so it is a single line or `n/a` if the function isn't defined.
implement means to learn about a functions source This implements a way to use the `functions` command to perform introspection to learn about the characteristics of a function. Such as where it came from. Fixes #3295 2017-01-10 06:49:33 +00:00
add description to `functions -m -v` output Fixes #597 2017-03-14 00:22:33 +00:00			`You should not assume that only five lines will be written since we may add additional information to the output in the future.`
implement means to learn about a functions source This implements a way to use the `functions` command to perform introspection to learn about the characteristics of a function. Such as where it came from. Fixes #3295 2017-01-10 06:49:33 +00:00
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			- `-n` or `--names` lists the names of all defined functions.
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 02:37:32 +00:00			- `-q` or `--query` tests if the specified functions exist.
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 07:56:01 +00:00
implement means to learn about a functions source This implements a way to use the `functions` command to perform introspection to learn about the characteristics of a function. Such as where it came from. Fixes #3295 2017-01-10 06:49:33 +00:00			- `-v` or `--verbose` will make some output more verbose.

Clean up and document functions --handlers 2018-03-10 10:08:33 +00:00			- `-H` or `--handlers` will show all event handlers.

			- `-t` or `--handlers-type TYPE` will show all event handlers matching the given type

Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00			The default behavior of `functions`, when called with no arguments, is to print the names of all defined functions. Unless the `-a` option is given, no functions starting with underscores are not included in the output.

			`If any non-option parameters are given, the definition of the specified functions are printed.`
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 13:31:55 +00:00
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00			Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 13:31:55 +00:00
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00			Copying a function using `-c` copies only the body of the function, and does not attach any event notifications from the original function.
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 13:31:55 +00:00
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00			Only one function's description can be changed in a single invocation of `functions -d`.
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 07:56:01 +00:00
Make line length, wrapping and spacing consistent 2014-08-19 12:41:23 +00:00			The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option.
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 07:56:01 +00:00

			`\subsection functions-example Examples`
Various additions and fixes 2014-08-26 23:30:08 +00:00			`\fish`
			`functions -n`
			`# Displays a list of currently-defined functions`
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 07:56:01 +00:00
Various additions and fixes 2014-08-26 23:30:08 +00:00			`functions -c foo bar`
			`# Copies the 'foo' function to a new function called 'bar'`
added '-c' option to the functions.txt docs. 2010-09-12 10:29:34 +00:00
Various additions and fixes 2014-08-26 23:30:08 +00:00			`functions -e bar`
			# Erases the function `bar`
			`\endfish`