fish-shell/sphinx_doc_src/cmds/functions.rst

.. _cmd-functions:

functions - print or erase functions
====================================

Synopsis
--------

functions [ -a | --all ] [ -n | --names ]
functions [ -D | --details ] [ -v ] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [ -e | -q ] FUNCTIONS...


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. This also means that it is prevented from autoloading.

- ``-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.


Examples
--------


::

    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``
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 17:05:09 +08:00			`.. _cmd-functions:`

Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00			`functions - print or erase functions`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`====================================`
Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`functions [ -a \| --all ] [ -n \| --names ]`
			`functions [ -D \| --details ] [ -v ] FUNCTION`
			`functions -c OLDNAME NEWNAME`
			`functions -d DESCRIPTION FUNCTION`
			`functions [ -e \| -q ] FUNCTIONS...`
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Description`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			``functions`` prints or erases functions.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`The following options are available:`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-a`` or ``--all`` lists all functions, even those whose name starts with an underscore.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-c OLDNAME NEWNAME`` or ``--copy OLDNAME NEWNAME`` creates a new function named NEWNAME, using the definition of the OLDNAME function.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-d DESCRIPTION`` or ``--description=DESCRIPTION`` changes the description of this function.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Prevent not-yet-loaded functions from loaded when erased (#5951) * Prevent not-yet-loaded functions from loaded when erased Today, `functions --erase $function` does nothing if the function hasn't been autoloaded yet. E.g. run, in an interactive session > functions --erase ls > type ls and be amazed that it still shows our default `ls --color=auto` wrapper function. This seems counter-intuitive - removing a function ought to remove it, whether it had been executed before or not. * doc/changelog 2019-06-22 17:08:36 +08:00			- ``-e`` or ``--erase`` causes the specified functions to be erased. This also means that it is prevented from autoloading.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08: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:
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs: Remove `-#` formatting That was supposed to be displayed like a list item, but it's displayed verbatim in the html output at least, so it looks weird. [ci skip] 2019-06-05 04:07:06 +08:00			`- 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.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`You should not assume that only five lines will be written since we may add additional information to the output in the future.`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-n`` or ``--names`` lists the names of all defined functions.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-q`` or ``--query`` tests if the specified functions exist.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-v`` or ``--verbose`` will make some output more verbose.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-H`` or ``--handlers`` will show all event handlers.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-t`` or ``--handlers-type TYPE`` will show all event handlers matching the given type
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08: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.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`If any non-option parameters are given, the definition of the specified functions are printed.`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08: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.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			Copying a function using ``-c`` copies only the body of the function, and does not attach any event notifications from the original function.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			Only one function's description can be changed in a single invocation of ``functions -d``.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08: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.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00

Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Examples`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00

Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00			`::`

			`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`
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			# Erases the function ``bar``
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00