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 in the current session. Use :ref:`funcsave <cmd-funcsave>` to remove the saved copy.

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

- ``--no-details`` turns off function path reporting, so just the definition will be printed.

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

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

See more
--------

For more explanation of how functions fit into fish, see :ref:`Functions <syntax-function>`.
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
doc_src: Continue the slog through the letter F. We are using only :: in a synopsis for fishscript examples given of the command being documented. 2021-12-18 07:16:47 +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
funcsave: add documentation for feature added in 3a402b19b 2022-01-03 23:03:29 +08:00			- ``-e`` or ``--erase`` causes the specified functions to be erased. This also means that it is prevented from autoloading in the current session. Use :ref:`funcsave <cmd-funcsave>` to remove the saved copy.
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.`

functions: Add "--no-details" flag and use it in funced This inhibits the function path comment which is annoying in `funced`. Fixes #7879. 2021-03-30 22:51:27 +08:00			- ``--no-details`` turns off function path reporting, so just the definition will be printed.

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			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
docs: Links for the function-related commands 2021-05-08 18:12:56 +08:00			`See more`
			`--------`

			For more explanation of how functions fit into fish, see :ref:`Functions <syntax-function>`.