From b485daa987dc7e280d02883829b231ea7706ade8 Mon Sep 17 00:00:00 2001 From: Fabian Homborg Date: Thu, 23 Jul 2020 17:47:18 +0200 Subject: [PATCH] docs: Rewrite "Functions" section More examples, links to funced/funcsave, autoloading, wrappers [ci skip] --- doc_src/index.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/doc_src/index.rst b/doc_src/index.rst index b3909e042..26c138f17 100644 --- a/doc_src/index.rst +++ b/doc_src/index.rst @@ -356,15 +356,36 @@ These listed jobs can be removed with the :ref:`disown ` command. Functions --------- -Functions are programs written in the fish syntax. They group together one or more commands and their arguments using a single name. It can also be used to start a specific command with additional arguments. +Functions are programs written in the fish syntax. They group together various commands and their arguments using a single name. -For example, the following is a function definition that calls the command ``ls`` with the argument ``-l`` to print a detailed listing of the contents of the current directory:: +For example, here's a simple function to list directories:: function ll ls -l $argv end -The first line tells fish that a function by the name of ``ll`` is to be defined. To use it, simply write ``ll`` on the commandline. The second line tells fish that the command ``ls -l $argv`` should be called when ``ll`` is invoked. ``$argv`` is a list variable, which always contains all arguments sent to the function. In the example above, these are simply passed on to the ``ls`` command. For more information on functions, see the documentation for the :ref:`function ` builtin. +The first line tells fish to define a function by the name of ``ll``, so it can be used by simply writing ``ll`` on the commandline. The second line tells fish that the command ``ls -l $argv`` should be called when ``ll`` is invoked. ``$argv`` is a list variable, which always contains all arguments sent to the function. In the example above, these are simply passed on to the ``ls`` command. The ``end`` on the third line ends the definition. + +Calling this as ``ll /tmp/`` will end up running ``ls -l /tmp/``, which will list the contents of /tmp. + +This is a kind of function known as a :ref:`wrapper ` or "alias". + +Fish's prompt is also defined in a function, called :ref:`fish_prompt `. It is run when the prompt is about to be displayed and its output forms the prompt:: + + function fish_prompt + # A simple prompt. Displays the current directory (which fish stores in the $PWD variable) + # and then a user symbol - a '►' for a normal user and a '#' for root. + set -l user_char '►' + if fish_is_root_user + set user_char '#' + end + + echo (set_color yellow)$PWD (set_color purple)$user_char + end + +To edit a function, you can use :ref:`funced `, and to save a function :ref:`funcsave `. This will store it in a function file that fish will :ref:`autoload ` when needed. + +For more information on functions, see the documentation for the :ref:`function ` builtin. .. _syntax-function-wrappers: