fish-shell/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 the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading stdin, ``-`` if the function was created via :ref:`source <cmd-source>`, and ``n/a`` if the function isn't available. (Functions created via :ref:`alias <cmd-alias>` will return ``-``, because ``alias`` uses ``source`` internally.) 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 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
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`::`
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`functions [ -a \| --all ] [ -n \| --names ]`
			`functions [ -D \| --details ] [ -v ] FUNCTION`
			`functions -c OLDNAME NEWNAME`
			`functions -d DESCRIPTION FUNCTION`
			`functions [ -e \| -q ] FUNCTIONS...`
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
doc: add links to 'source' command from 'eval' and 'functions' 2020-03-21 04:10:46 +08:00			- ``-D`` or ``--details`` reports the path name where the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading stdin, ``-`` if the function was created via :ref:`source <cmd-source>`, and ``n/a`` if the function isn't available. (Functions created via :ref:`alias <cmd-alias>` will return ``-``, because ``alias`` uses ``source`` internally.) 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
correct description of -a param regarding _(\w*) removed the word "not" to resolve an (unintended) negation of negation. 2020-09-08 23:35:42 +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 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