github-mirror/fish-shell
github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2025-03-15 23:22:53 +08:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Merge branch 'master' into te-refactor

Browse Source
This commit is contained in:
Fabian Homborg 2022-03-13 11:24:31 +01:00 committed by GitHub
commit 972752aa1c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
341 changed files with 4906 additions and 2210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.editorconfig
View File

@ -20,3 +20,9 @@ indent_size = 2
[Dockerfile]
indent_size = 2
[share/{completions,functions}/**.fish]
max_line_length = none
[COMMIT_EDITMSG]
max_line_length = 80

51
CHANGELOG.rst
View File

@ -1,9 +1,5 @@
fish 3.4.0 (released ???)
=========================
..
Ignore for 3.4.0 changelog: 1363 3625 3954 6477 7602 8059 8077 8079 8084 8096 8118 8127 8128 8130 8137 8139 8146 8151 8153 8161 8170 8176 8183 8184 8191 8192 8195 8202 8204 8205 8206 8219 8221 8222 8224 8227 8228 8229 8230 8231 8235 8236 8237 8238 8239 8241 8243 8249 8252 8253 8256 8257 8260 8268 8270 8271 8277 8280 8285 8287 8289 8295 8299 8305 8306 8308 8310 8311 8314 8321 8323 8326 8327 8334 8335 8337 8338 8344 8353 8358 8365 8367 8368 8380 8381 8385 8391 8394 8403 8406 8409 8410 8419 8429 8430 8433 8438 8439 8441 8444 8446 8449 8456 8457 8471 8472 8476 8477 8478 8479 8480 8487 8492 8495 8497 8500 8511 8518 8521 8522 8526 8527 8528 8548 8549 8559 8575 8584 8587 8588 8570 8591 8596 8597 8601 8608 8612 8613 8615 8623
fish 3.4.0 (released March 12, 2022)
====================================
Notable improvements and fixes
------------------------------
@ -21,7 +17,7 @@ Notable improvements and fixes
# this will still split on newlines only.
- Complementing the ``prompt`` command in 3.3.0, ``fish_config`` gained a ``theme`` subcommand to show and pick from the sample themes (meaning color schemes) directly in the terminal, instead of having to open a Web browser. For example ``fish_config theme choose Nord`` loads the Nord theme in the current session (:issue:`8132`). The current theme can be saved with ``fish_config theme dump``, and custom themes can be added by saving them in ``~/.config/fish/themes/``.
- ``set`` and ``read`` learned a new option ``--function`` to set a variable in the function's top scope. This should be a more familiar way of scoping variables and avoids issues with ``--local``, which is actually block-scoped (:issue:`565`, :issue:`8145`)::
- ``set`` and ``read`` learned a new option, ``--function``, to set a variable in the function's top scope. This should be a more familiar way of scoping variables and avoids issues with ``--local``, which is actually block-scoped (:issue:`565`, :issue:`8145`)::
function demonstration
if true
@ -39,6 +35,7 @@ Notable improvements and fixes
- Performance improvements to globbing, especially on systems using glibc. In some cases (large directories with files with many numbers in the names) this almost halves the time taken to expand the glob.
- Autosuggestions can now be turned off by setting ``$fish_autosuggestion_enabled`` to 0, and (almost) all highlighting can be turned off by choosing the new "None" theme. The exception is necessary colors, like those which distinguish autosuggestions from the actual command line. (:issue:`8376`)
- The ``fish_git_prompt`` function, which is included in the default prompts, now overrides ``git`` to avoid running commands set by per-repository configuration. This avoids a potential security issue in some circumstances, and has been assigned CVE-2022-20001 (:issue:`8589`).
Deprecations and removed features
---------------------------------
@ -49,6 +46,10 @@ Deprecations and removed features
# with both ampersand-nobg-in-token and qmark-noglob, this argument has no special characters anymore
> open https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be
As a reminder, feature flags can be set on startup with ``fish --features ampersand-nobg-in-token,qmark-noglob`` or with a universal variable called ``fish_features``::
> set -Ua fish_features ampersand-nobg-in-token
- ``$status`` is now forbidden as a command, to prevent a surprisingly common error among new users: Running ``if $status`` (:issue:`8171`). This applies *only* to ``$status``, other variables are still allowed.
- ``set --query`` now returns an exit status of 255 if given no variable names. This means ``if set -q $foo`` will not enter the if-block if ``$foo`` is empty or unset. To restore the previous behavior, use ``if not set -q foo; or set -q $foo`` - but this is unlikely to be desireable (:issue:`8214`).
- ``_`` is now a reserved keyword (:issue:`8342`).
@ -68,6 +69,7 @@ Scripting improvements
- ``$fish_user_paths`` is now automatically deduplicated to fix a common user error of appending to it in config.fish when it is universal (:issue:`8117`). :ref:`fish_add_path <cmd-fish_add_path>` remains the recommended way to add to $PATH.
- ``return`` can now be used outside functions. In scripts, it does the same thing as ``exit``. In interactive mode,it sets ``$status`` without exiting (:issue:`8148`).
- An oversight prevented all syntax checks from running on commands given to ``fish -c`` (:issue:`8171`). This includes checks such as ``exec`` not being allowed in a pipeline, and ``$$`` not being a valid variable. Generally, another error was generated anyway.
- ``math`` now allows you to use underscores as visual separators when writing numbers - for example, ``math 1_000 + 2_000`` returns ``3000`` (:issue:`8496`).
- ``fish_indent`` now correctly reformats tokens that end with a backslash followed by a newline (:issue:`8197`).
- ``commandline`` gained an ``--is-valid`` option to check if the command line is syntactically valid and complete. This allows basic implementation of transient prompts (:issue:`8142`).
- ``commandline`` gained a ``--paging-full-mode`` option to check if the pager is showing all the possible lines (no "7 more rows" message) (:issue:`8485`).
@ -84,10 +86,14 @@ Scripting improvements
- ``set --query`` can now query whether a variable is a path variable via ``--path`` or ``--unpath`` (:issue:`8494`).
- Tilde characters (``~``) produced by custom completions are no longer escaped when applied to the command line, making it easier to use the output of a recursive ``complete -C`` in completion scripts (:issue:`4570`).
- ``set --show`` reports when a variable is read-only (:issue:`8179`).
- Erasing ``$fish_emoji_width`` will reset fish to the default emoji width (:issue:`8274`).
- Erasing ``$fish_emoji_width`` will reset fish to the default guessed emoji width (:issue:`8274`).
- The ``la`` function no longer lists entries for "." and "..", matching other systems defaults (:issue:`8519`).
- ``abbr -q`` returns the correct exit status when given multiple abbreviation names as arguments (:issue:`8431`).
- ``command -v`` returns an exit status of 127 instead of 1 if no command was found (:issue:`8547`).
- ``argparse`` with ``--ignore-unknown`` no longer breaks with multiple unknown options in a short option group (:issue:`8637`).
- Comments inside command substitutions or brackets now correctly ignore parentheses, quotes, and brackets (:issue:`7866`, :issue:`8022`, :issue:`8695`).
- ``complete -C`` supports a new ``--escape`` option, which turns on escaping in returned completion strings (:issue:`3469`).
- Invalid byte or unicode escapes like ``\Utest`` or ``\xNotHex`` are now a tokenizer error instead of causing the token to be truncated (:issue:`8545`).
Interactive improvements
------------------------
@ -114,6 +120,9 @@ Interactive improvements
- The clipboard bindings ignore X-based clipboard programs if the ``DISPLAY`` environment variable is not set, which helps prefer the Windows clipboard when it is available (such as on WSL).
- ``funcsave`` will remove a saved copy of a function that has been erased with ``functions --erase``.
- The Web-based configuration tool gained a number of improvements, including the ability to set pager colors.
- The default ``fish_title`` prints a shorter title with shortened $PWD and no more redundant "fish" (:issue:`8641`).
- Holding down an arrow key won't freeze the terminal with long periods of flashing (:issue:`8610`).
- Multi-char bindings are no longer interrupted if a signal handler enqueues an event. (:issue:`8628`).
New or improved bindings
^^^^^^^^^^^^^^^^^^^^^^^^
@ -134,6 +143,7 @@ Completions
- Apple's ``shortcuts``
- ``argparse`` (:issue:`8434`)
- ``asd`` (:issue:`8759`)
- ``az`` (:issue:`8141`)
- ``black`` (:issue:`8123`)
- ``clasp`` (:issue:`8373`)
@ -145,27 +155,33 @@ Completions
- ``exif`` (:issue:`8246`)
- ``findstr`` (:issue:`8481`)
- ``git-sizer`` (:issue:`8156`)
- ``gnome-extensions`` (:issue:`8732`)
- ``gping`` (:issue:`8181`)
- ``isatty`` (:issue:`8609`)
- ``istioctl`` (:issue:`8343`)
- ``kmutil``
- ``mono`` (:issue:`8415`)
- ``kubectl`` (:issue:`8734`)
- ``matlab`` (:issue:`8505`)
- ``mono`` (:issue:`8415`) and related tools ``csharp``, ``gacutil``, ``gendarme``, ``ikdasm``, ``ilasm``, ``mkbundle``, ``monodis``, ``monop``, ``sqlsharp`` and ``xsp`` (:issue:`8452`)
- Angular's ``ng`` (:issue:`8111`)
- ``nodeenv`` (:issue:`8533`)
- ``octave`` (:issue:`8505`)
- ``pabcnet_clear`` (:issue:`8421`)
- ``qmk`` (:issue:`8180`)
- ``rakudo`` (:issue:`8113`)
- ``rc-status`` (:issue:`8757`)
- ``roswell`` (:issue:`8330`)
- ``sbcl`` (:issue:`8330`)
- ``starship`` (:issue:`8520`)
- ``topgrade`` (:issue:`8651`)
- ``wine``, ``wineboot`` and ``winemaker`` (:issue:`8411`)
- Windows Subsystem for Linux (WSL)'s ``wslpath`` (:issue:`8364`)
- Windows' ``color`` (:issue:`8483`)
- Windows' ``color`` (:issue:`8483`), ``attrib``, ``attributes``, ``choice``, ``clean``, ``cleanmgr``, ``cmd``, ``cmdkey``, ``comp``, ``forfiles``, ``powershell``, ``reg``, ``schtasks``, ``setx`` (:issue:`8486`)
- ``zef`` (:issue:`8114`)
- Improvements to many completions, especially for ``git`` aliases (:issue:`8129`) and subcommands (:issue:`8134`).
- Add missing completions for the ``-p`` option of ``xbps-query``.
- The ``fish_is_nth_token`` function, which is particularly useful in completions for identifying the token number within the command line, replaces various internal functions to do the same (:issue:`8008`).
- Improvements to many completions, especially for ``git`` aliases (:issue:`8129`), subcommands (:issue:`8134`) and submodules (:issue:`8716`).
- Many adjustments to complete correct options for system utilities on BSD and macOS.
- When evaluating custom completions, the command line state no longer includes variable overrides (``var=val``). This unbreaks completions that read ``commandline -op``.
Improved terminal support
^^^^^^^^^^^^^^^^^^^^^^^^^
@ -181,18 +197,19 @@ Improved terminal support
Other improvements
------------------
- Fish's test suite now uses ``ctest``, and has become much faster to run. It is now also possible to run only specific tests. (:issue:`7851`)
- Fish's test suite now uses ``ctest``, and has become much faster to run. It is now also possible to run only specific tests with targets named ``test_$filename`` - ``make test_set.fish`` only runs the set.fish test. (:issue:`7851`)
- The HTML version of the documentation now includes copy buttons for code examples (:issue:`8218`).
- The HTML version of the documentation and the web-based configuration tool now pick more modern system fonts instead of falling back to Arial and something like Courier New most of the time (:issue:`8632`).
- The Debian & Ubuntu package linked from fishshell.com is now a single package, rather than split into ``fish`` and ``fish-common`` (:issue:`7845`).
- The macOS installer does not assert that Rosetta is required to install fish (:issue:`8566`).
- The macOS installer does not assert that Rosetta is required to install fish on machines with Apple Silicon (:issue:`8566`).
- The macOS installer now cleans up previous .pkg installations when upgrading. (:issue:`2963`).
For distributors
----------------
- The minimum version of CMake required to build fish is now 3.5.0.
- The CMake installation supports absolute paths for ``CMAKE_INSTALL_DATADIR`` (:issue:`8150`).
- Building using NetBSD curses works on any platform (:issue:`8087`).
- The build system does not choose a different linker (:issue:`8152`).
- The build system now uses the default linker instead of forcing use of the gold or lld linker (:issue:`8152`).
--------------
@ -3334,3 +3351,5 @@ to call ttyname() on OS X.
We’ve got some work to do to be as lean as bash, but we’re on the right
track.
.. vim: ft=rst : tw=0 :

2
build_tools/make_pkg.sh
View File

@ -35,6 +35,6 @@ MAC_PRODUCTSIGN_ID=${MAC_PRODUCTSIGN_ID:--}
productsign --sign "${MAC_PRODUCTSIGN_ID}" "$OUTPUT_PATH/fish-$VERSION.pkg" "$OUTPUT_PATH/fish-$VERSION-signed.pkg" && mv "$OUTPUT_PATH/fish-$VERSION-signed.pkg" "$OUTPUT_PATH/fish-$VERSION.pkg"
# Make the app
{ cd "$PKGDIR/build" && make signed_fish_macapp && zip -r "$OUTPUT_PATH/fish-$VERSION.app.zip" fish.app; }
{ cd "$PKGDIR/build" && make -j 12 signed_fish_macapp && zip -r "$OUTPUT_PATH/fish-$VERSION.app.zip" fish.app; }
rm -r "$PKGDIR"

6
build_tools/osx_distribution.xml
View File

@ -1,11 +1,11 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<installer-gui-script minSpecVersion="1">
<title>fish shell</title>
<welcome file="welcome.rtf"/>
<welcome file="welcome.html" mime-type="text/html"/>
<background file="terminal_logo.png" scaling="proportional" alignment="bottomleft"/>
<pkg-ref id="com.ridiculousfish.fish-shell-pkg"/>
<options hostArchitectures="arm64,x86_64" />
<options customize="never" require-scripts="false"/>
<options hostArchitectures="arm64,x86_64" rootVolumeOnly="true"/>
<options customize="never" require-scripts="true"/>
<choices-outline>
<line choice="default">
<line choice="com.ridiculousfish.fish-shell-pkg"/>

29
build_tools/osx_package_resources/welcome.html Normal file
View File

@ -0,0 +1,29 @@
<html>
<head>
<style>
body {
font-family: system-ui, -apple-system, "Helvetica Neue", sans-serif;
font-size: 10pt;
}
code, tt {
font-family: ui-monospace, Menlo, monospace;
}
</style>
</head>
<body>
<p>
<strong>fish</strong> is a smart and user-friendly command line shell. For more information, visit <a href="https://fishshell.com">fishshell.com</a>.
</p>
<p>
<strong>fish</strong> will be installed into <tt>/usr/local/</tt>, and its path will be added to <wbr><tt>/etc/shells</tt> if necessary.
</p>
<p>
Your default shell will <em>not</em> be changed. To make <strong>fish</strong> your login shell after the installation, run:
</p>
<p>
<code>chsh -s /usr/local/bin/fish</code>
</p>
<p>Enjoy! Bugs can be reported on <a href="https://github.org/fish-shell/fish-shell/">GitHub</a>.</p>
</body>
</html>

26
build_tools/osx_package_resources/welcome.rtf
View File

@ -1,26 +0,0 @@
{\rtf1\ansi\ansicpg1252\cocoartf1485\cocoasubrtf410
{\fonttbl\f0\fnil\fcharset0 HelveticaNeue;\f1\fnil\fcharset0 Menlo-Regular;}
{\colortbl;\red255\green255\blue255;}
{\*\expandedcolortbl;\csgenericrgb\c100000\c100000\c100000;}
{\info
{\author dlkfjslfjsfdlkfk}}\margl1440\margr1440\vieww10800\viewh8400\viewkind0
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural\partightenfactor0
\f0\fs30 \cf0 Fish is a smart and user friendly command line shell. For more information, visit {\field{\*\fldinst{HYPERLINK "https://fishshell.com"}}{\fldrslt https://fishshell.com}}\
\
fish will be installed into
\f1\fs26 /usr/local/
\f0\fs30 , and fish will be added to
\f1\fs26 /etc/shells
\f0\fs30 if necessary.\
\
Your default shell will
\i not
\i0 be changed. To make fish your default, run:\
\
\f1 chsh -s /usr/local/bin/fish
\f0 \
\
Enjoy!\
}

2
build_tools/osx_package_scripts/postinstall
View File

@ -1,3 +1,3 @@
#!/bin/sh -x
./add-shell /usr/local/bin/fish > /tmp/fish_postinstall_output.log
./add-shell ${DSTVOLUME}usr/local/bin/fish

7
build_tools/osx_package_scripts/preinstall Executable file
View File

@ -0,0 +1,7 @@
#!/bin/sh -x
echo "Removing any previous installation"
pkgutil --pkg-info ${INSTALL_PKG_SESSION_ID} && pkgutil --only-files --files ${INSTALL_PKG_SESSION_ID} | while read installed
do rm -v ${DSTVOLUME}${installed}
done
echo "... removed"

7
cmake/ConfigureChecks.cmake
View File

@ -115,7 +115,14 @@ check_struct_has_member("struct stat" st_mtim.tv_nsec "sys/stat.h" HAVE_STRUCT_S
LANGUAGE CXX)
check_include_file_cxx(sys/ioctl.h HAVE_SYS_IOCTL_H)
check_include_file_cxx(sys/select.h HAVE_SYS_SELECT_H)
# glibc 2.30 deprecated <sys/sysctl.h> because that's what glibc does.
# Checking for that here rather than hardcoding a check on the glibc
# version in the C++ sources at point of use makes more sense.
SET(OLD_CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Werror")
check_include_files("sys/types.h;sys/sysctl.h" HAVE_SYS_SYSCTL_H)
SET(CMAKE_C_FLAGS "${OLD_CMAKE_C_FLAGS}")
check_cxx_symbol_exists(eventfd sys/eventfd.h HAVE_EVENTFD)
check_cxx_symbol_exists(pipe2 unistd.h HAVE_PIPE2)

5
cmake/Docs.cmake
View File

@ -9,7 +9,6 @@ include(FeatureSummary)
set(SPHINX_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc_src")
set(SPHINX_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/user_doc")
set(SPHINX_BUILD_DIR "${SPHINX_ROOT_DIR}/build")
set(SPHINX_CACHE_DIR "${SPHINX_ROOT_DIR}/doctrees")
set(SPHINX_HTML_DIR "${SPHINX_ROOT_DIR}/html")
set(SPHINX_MANPAGE_DIR "${SPHINX_ROOT_DIR}/man")
@ -22,7 +21,7 @@ add_custom_target(sphinx-docs
-j auto
-q -b html
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
-d "${SPHINX_ROOT_DIR}/.doctrees-html"
"${SPHINX_SRC_DIR}"
"${SPHINX_HTML_DIR}"
DEPENDS ${SPHINX_SRC_DIR}/fish_indent_lexer.py fish_indent
@ -35,7 +34,7 @@ add_custom_target(sphinx-manpages
-j auto
-q -b man
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
-d "${SPHINX_ROOT_DIR}/.doctrees-man"
"${SPHINX_SRC_DIR}"
# TODO: This only works if we only have section 1 manpages.
"${SPHINX_MANPAGE_DIR}/man1"

4
doc_src/cmds/_.rst
View File

@ -6,7 +6,9 @@ _ - call fish's translations
Synopsis
--------
``_`` *STRING*
.. synopsis::
_ STRING
Description
-----------

21
doc_src/cmds/abbr.rst
View File

@ -6,12 +6,14 @@ abbr - manage fish abbreviations
Synopsis
--------
| ``abbr`` --add [*SCOPE*] *WORD* *EXPANSION*
| ``abbr`` --erase *WORD* ...
| ``abbr`` --rename [*SCOPE*] *OLD_WORD* *NEW_WORD*
| ``abbr`` --show
| ``abbr`` --list
| ``abbr`` --query *WORD* ...
.. synopsis::
abbr --add [SCOPE] WORD EXPANSION
abbr --erase WORD ...
abbr --rename [SCOPE] OLD_WORD NEW_WORD
abbr --show
abbr --list
abbr --query WORD ...
Description
-----------
@ -38,13 +40,16 @@ The following options are available:
**-l** or **--list**
Lists all abbreviated words
**-e** *WORD* or **--erase** *WORD*...
**-e** *WORD* or **--erase** *WORD* ...
Erase the given abbreviations
**-q** or **--query**
Return 0 (true) if one of the *WORD* is an abbreviation.
In addition, when adding or renaming abbreviations:
**-h** or **--help**
Displays help about using this command.
In addition, when adding or renaming abbreviations, one of the following **SCOPE** options can be used:
**-g** or **--global**
Use a global variable

18
doc_src/cmds/alias.rst
View File

@ -6,9 +6,11 @@ alias - create a function
Synopsis
--------
| ``alias``
| ``alias`` [*OPTIONS*] *NAME* *DEFINITION*
| ``alias`` [*OPTIONS*] *NAME*=*DEFINITION*
.. synopsis::
alias
alias [--save] NAME DEFINITION
alias [--save] NAME=DEFINITION
Description
@ -19,15 +21,17 @@ Description
``fish`` marks functions that have been created by ``alias`` by including the command used to create them in the function description. You can list ``alias``-created functions by running ``alias`` without arguments. They must be erased using ``functions -e``.
- ``NAME`` is the name of the alias
- ``DEFINITION`` is the actual command to execute. The string ``$argv`` will be appended.
- ``DEFINITION`` is the actual command to execute. ``alias`` automatically appends ``$argv``, so that all parameters used with the alias are passed to the actual command.
You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to ``alias`` just like at the command line, *even inside quoted parts*.
The following options are available:
- **-h** or **--help** displays help about using this command.
**-h** or **--help**
Displays help about using this command.
- **-s** or **--save** Automatically save the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
**-s** or **--save**
Saves the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
Example
-------
@ -51,6 +55,6 @@ The following code will create ``rmi``, which runs ``rm`` with additional argume
See more
--------
1. The :ref:`function <cmd-function>` builtin this builds on.
1. The :ref:`function <cmd-function>` command this builds on.
2. :ref:`Functions <syntax-function>`.
3. :ref:`Function wrappers <syntax-function-wrappers>`.

9
doc_src/cmds/and.rst
View File

@ -1,12 +1,14 @@
.. _cmd-and:
and - conditionally execute a command
=========================================
=====================================
Synopsis
--------
PREVIOUS; **and** *COMMAND*
.. synopsis::
PREVIOUS; and COMMAND
Description
-----------
@ -17,6 +19,8 @@ Description
``and`` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
The **-h** or **--help** option displays help about using this command.
Example
-------
@ -30,3 +34,4 @@ See Also
--------
- :ref:`or <cmd-or>` command
- :ref:`not <cmd-not>` command

45
doc_src/cmds/argparse.rst
View File

@ -6,13 +6,15 @@ argparse - parse options passed to a fish script or function
Synopsis
--------
``argparse`` [*OPTIONS*] *OPTION_SPEC*... -- [*ARG*...]
.. synopsis::
argparse [OPTIONS] OPTION_SPEC ... -- [ARG ...]
Description
-----------
This command makes it easy for fish scripts and functions to handle arguments like how fish builtin commands handle their arguments. You pass arguments that define the known options, followed by a literal **--**, then the arguments to be parsed (which might also include a literal **--**). ``argparse`` then sets variables to indicate the passed options with their values, and sets $argv (and always $argv) to the remaining arguments. More on this in the :ref:`usage <cmd-argparse-usage>` section below.
This command makes it easy for fish scripts and functions to handle arguments. You pass arguments that define the known options, followed by a literal **--**, then the arguments to be parsed (which might also include a literal **--**). ``argparse`` then sets variables to indicate the passed options with their values, and sets ``$argv`` to the remaining arguments. See the :ref:`usage <cmd-argparse-usage>` section below.
Each option specification (``OPTION_SPEC``) is written in the :ref:`domain specific language <cmd-argparse-option-specification>` described below. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed.
@ -23,22 +25,28 @@ The variables will be set with local scope (i.e., as if the script had done ``se
Options
-------
The following ``argparse`` options are available. They must appear before all OPTION_SPECs:
The following ``argparse`` options are available. They must appear before all *OPTION_SPEC*\ s:
**-n** or **--name**
the command name for use in error messages. By default the current function name will be used, or ``argparse`` if run outside of a function.
The command name for use in error messages. By default the current function name will be used, or ``argparse`` if run outside of a function.
**-x** or **--exclusive** should be followed by a comma separated list of short or long options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options.
**-x** or **--exclusive** *OPTIONS*
A comma separated list of options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options.
- **-N** or **--min-args** is followed by an integer that defines the minimum number of acceptable non-option arguments. The default is zero.
**-N** or **--min-args** *NUMBER*
The minimum number of acceptable non-option arguments. The default is zero.
- **-X** or **--max-args** is followed by an integer that defines the maximum number of acceptable non-option arguments. The default is infinity.
**-X** or **--max-args** *NUMBER*
The maximum number of acceptable non-option arguments. The default is infinity.
- **-i** or **--ignore-unknown** ignores unknown options, keeping them and their arguments in $argv instead.
**-i** or **--ignore-unknown**
Ignores unknown options, keeping them and their arguments in $argv instead.
- **-s** or **--stop-nonopt** causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
**-s** or **--stop-nonopt**
Causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
- **-h** or **--help** displays help about using this command.
**-h** or **--help**
Displays help about using this command.
.. _cmd-argparse-usage:
@ -157,7 +165,7 @@ Fish ships with a ``_validate_int`` function that accepts a ``--min`` and ``--ma
Example OPTION_SPECs
--------------------
Some OPTION_SPEC examples:
Some *OPTION_SPEC* examples:
- ``h/help`` means that both ``-h`` and ``--help`` are valid. The flag is a boolean and can be used more than once. If either flag is used then ``_flag_h`` and ``_flag_help`` will be set to the count of how many times either flag was seen.
@ -184,3 +192,18 @@ Some OPTION_SPEC examples:
After parsing the arguments the ``argv`` variable is set with local scope to any values not already consumed during flag processing. If there are no unbound values the variable is set but ``count $argv`` will be zero.
If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.
Limitations
-----------
One limitation with **--ignore-unknown** is that, if an unknown option is given in a group with known options, the entire group will be kept in $argv. ``argparse`` will not do any permutations here.
For instance::
argparse --ignore-unknown h -- -ho
echo $_flag_h # is -h, because -h was given
echo $argv # is still -ho
This limitation may be lifted in future.
Additionally, it can only parse known options up to the first unknown option in the group - the unknown option could take options, so it isn't clear what any character after an unknown option means.

8
doc_src/cmds/begin.rst
View File

@ -6,19 +6,23 @@ begin - start a new block of code
Synopsis
--------
**begin**; [*COMMANDS* ...]; **end**
.. synopsis::
begin; [COMMANDS ...]; end
Description
-----------
``begin`` is used to create a new block of code.
A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like ``and``.
A block allows the introduction of a new :ref:`variable scope <variables-scope>`, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like ``and``.
The block is unconditionally executed. ``begin; ...; end`` is equivalent to ``if true; ...; end``.
``begin`` does not change the current exit status itself. After the block has completed, ``$status`` will be set to the status returned by the most recent command.
The **-h** or **--help** option displays help about using this command.
Example
-------

6
doc_src/cmds/bg.rst
View File

@ -6,7 +6,9 @@ bg - send jobs to background
Synopsis
--------
``bg`` [*PID* ...]
.. synopsis::
bg [PID ...]
Description
-----------
@ -22,6 +24,8 @@ When at least one of the arguments isn't a valid job specifier,
When all arguments are valid job specifiers, ``bg`` will background all matching jobs that exist.
The **-h** or **--help** option displays help about using this command.
Example
-------

33
doc_src/cmds/bind.rst
View File

@ -5,12 +5,14 @@ bind - handle fish key bindings
Synopsis
--------
| ``bind`` [(**-M** | **--mode**) *MODE*] [(*-m* | *--sets-mode*) **NEW_MODE**] [*--preset* | *--user*] [*-s* | *--silent*] [**-k** | **--key**] *SEQUENCE* *COMMAND* ...
| ``bind`` [**-M** | **--mode** *MODE*] [**-k** | **--key**] [**--preset**] [**--user**] *SEQUENCE*
| ``bind`` **-K** | **--key-names** [**-a** | **--all**] [**--preset**] [**--user**]
| ``bind`` **-f** | **--function-names**
| ``bind`` **-L** | **--list-modes**
| ``bind`` **-e** | **--erase** [**-M** | **--mode** *MODE*] [**--preset**] [**--user**] [**-a** | **--all**] | [**-k** | **--key**] *SEQUENCE* ...
.. synopsis::
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] [-k | --key] SEQUENCE COMMAND ...
bind [(-M | --mode) MODE] [-k | --key] [--preset] [--user] SEQUENCE
bind (-K | --key-names) [-a | --all] [--preset] [--user]
bind (-f | --function-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | [-k | --key] SEQUENCE ...
Description
-----------
@ -79,6 +81,9 @@ The following options are available:
All invocations except for inserting new bindings can operate on both levels at the same time (if both **--preset** and **--user** are given).
**--preset** should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
**-h** or **--help**
Displays help about using this command.
Special input functions
-----------------------
The following special input functions are available:
@ -87,10 +92,11 @@ The following special input functions are available:
only execute the next function if the previous succeeded (note: only some functions report success)
``accept-autosuggestion``
accept the current autosuggestion completely
accept the current autosuggestion
``backward-char``
moves one character to the left
move one character to the left.
If the completion pager is active, select the previous completion instead.
``backward-bigword``
move one whitespace-delimited word to the left
@ -177,13 +183,15 @@ The following special input functions are available:
move one whitespace-delimited word to the right
``forward-char``
move one character to the right
move one character to the right; or if at the end of the commandline, accept the current autosuggestion.
If the completion pager is active, select the next completion instead.
``forward-single-char``
move one character to the right; if an autosuggestion is available, only take a single char from it
move one character to the right; or if at the end of the commandline, accept a single char from the current autosuggestion.
``forward-word``
move one word to the right
move one word to the right; or if at the end of the commandline, accept one word
from the current autosuggestion.
``history-search-backward``
search the history for the previous match
@ -228,7 +236,8 @@ The following special input functions are available:
move the next word to the killring
``nextd-or-forward-word``
if the commandline is empty, then move forward in the directory history, otherwise move one word to the right
if the commandline is empty, then move forward in the directory history, otherwise move one word to the right;
or if at the end of the commandline, accept one word from the current autosuggestion.
``or``
only execute the next function if the previous succeeded (note: only some functions report success)

18
doc_src/cmds/block.rst
View File

@ -6,7 +6,10 @@ block - temporarily block delivery of events
Synopsis
--------
**block** [*OPTIONS* ...]
.. synopsis::
block [(--local | --global)]
block --erase
Description
-----------
@ -19,16 +22,21 @@ The block can be removed. Any events which triggered while the block was in plac
Event blocks should not be confused with code blocks, which are created with ``begin``, ``if``, ``while`` or ``for``
The following parameters are available:
Without options, the ``block`` command acts with function scope.
The following options are available:
**-l** or **--local**
Release the block automatically at the end of the current innermost code block scope
Release the block automatically at the end of the current innermost code block scope.
**-g** or **--global**
Never automatically release the lock
Never automatically release the lock.
**-e** or **--erase**
Release global block
Release global block.
**-h** or **--help**
Displays help about using this command.
Example
-------

15
doc_src/cmds/break.rst
View File

@ -6,20 +6,21 @@ break - stop the current inner loop
Synopsis
--------
| loop_construct
| [*COMMANDS* ...]
| **break**
| [*COMMANDS* ...]
| end
.. synopsis::
LOOP_CONSTRUCT
[COMMANDS ...]
break
[COMMANDS ...]
end
Description
-----------
``break`` halts a currently running loop, such as a :ref:`switch <cmd-switch>`, :ref:`for <cmd-for>` or :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` block.
``break`` halts a currently running loop (*LOOP_CONSTRUCT*), such as a :ref:`switch <cmd-switch>`, :ref:`for <cmd-for>` or :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` block.
There are no parameters for ``break``.
Example
-------
The following code searches all .c files for "smurf", and halts at the first occurrence.

4
doc_src/cmds/breakpoint.rst
View File

@ -6,7 +6,9 @@ breakpoint - launch debug mode
Synopsis
--------
``breakpoint``
.. synopsis::
breakpoint
Description
-----------

21
doc_src/cmds/builtin.rst
View File

@ -6,20 +6,27 @@ builtin - run a builtin command
Synopsis
--------
| **builtin** [*OPTIONS* ...] *BUILTINNAME*
| **builtin** --query *BUILTINNAMES* ...
.. synopsis::
builtin [OPTIONS] BUILTINNAME
builtin --query BUILTINNAME ...
builtin --names
Description
-----------
``builtin`` forces the shell to use a builtin command, rather than a function or program.
``builtin`` forces the shell to use a builtin command named *BUILTIN*, rather than a function or external program.
The following parameters are available:
The following options are available:
**-n** or **--names**
List the names of all defined builtins
**-q** or **--query**
Tests if any of the specified builtin(s) exist
Lists the names of all defined builtins.
**-q** or **--query** *BUILTIN*
Tests if any of the specified builtins exist.
**-h** or **--help**
Displays help about using this command.
Example
-------

10
doc_src/cmds/case.rst
View File

@ -6,10 +6,12 @@ case - conditionally execute a block of commands
Synopsis
--------
| **switch** *VALUE*
| [**case** [*GLOB*...]
| [*COMMAND* ...]]
| **end**
.. synopsis::
switch VALUE
[case [GLOB ...]
[COMMAND ...]]
end
Description
-----------

8
doc_src/cmds/cd.rst
View File

@ -6,11 +6,13 @@ cd - change directory
Synopsis
--------
**cd** [*DIRECTORY*]
.. synopsis::
cd [DIRECTORY]
Description
-----------
**cd** changes the current working directory.
``cd`` changes the current working directory.
If *DIRECTORY* is given, it will become the new directory. If no parameter is given, the :envvar:`HOME` environment variable will be used.
@ -26,6 +28,8 @@ If you make those universal variables your **cd** history is shared among all fi
As a special case, ``cd .`` is equivalent to ``cd $PWD``, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated.
The **--help** or **-h** option displays help about using this command, and does not change the directory.
Examples
--------

10
doc_src/cmds/cdh.rst
View File

@ -6,7 +6,9 @@ cdh - change to a recently visited directory
Synopsis
--------
``cdh`` [*DIR*]
.. synopsis::
cdh [DIRECTORY]
Description
-----------
@ -14,11 +16,11 @@ Description
``cdh`` with no arguments presents a list of :ref:`recently visited directories <directory-history>`.
You can then select one of the entries by letter or number.
You can also press :kbd:`Tab` to use the completion pager to select an item from the list.
If you give it a single argument it is equivalent to ``cd DIR``.
If you give it a single argument it is equivalent to ``cd DIRECTORY``.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories.
The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
If you make those universal variables your ``cd`` history is shared among all fish instances.
The history is stored in the :envvar:`dirprev` and :envvar:`$dirnext` variables, which this command manipulates.
If you make those universal variables, your ``cd`` history is shared among all fish instances.
See Also
--------

7
doc_src/cmds/command.rst
View File

@ -6,7 +6,9 @@ command - run a program
Synopsis
--------
**command** [ **OPTIONS** ] [*COMMANDNAME* [ARG ...]]
.. synopsis::
command [OPTIONS] [COMMANDNAME [ARG ...]]
Description
-----------
@ -26,6 +28,9 @@ The following options are available:
**-v** (or **-s** or **--search**)
Prints the external command that would be executed, or prints nothing if no file with the specified name could be found in :envvar:`PATH`.
**-h** or **--help**
Displays help about using this command.
With the **-v** option, ``command`` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 127 if no commands could be found. **--quiet** used with **-v** prevents commands being printed, like ``type -q``.
Examples

7
doc_src/cmds/commandline.rst
View File

@ -6,7 +6,9 @@ commandline - set or get the current command line buffer
Synopsis
--------
``commandline`` [*OPTIONS*] [*CMD*]
.. synopsis::
commandline [OPTIONS] [CMD]
Description
-----------
@ -29,6 +31,9 @@ The following options are available:
This option cannot be combined with any other option.
See :ref:`bind <cmd-bind>` for a list of input functions.
**-h** or **--help**
Displays help about using this command.
The following options change the way ``commandline`` updates the command line buffer:
**-a** or **--append**

59
doc_src/cmds/complete.rst
View File

@ -6,8 +6,10 @@ complete - edit command specific tab-completions
Synopsis
--------
``complete`` **-c** | **--command** | **-p** | **--path** [*options*] *COMMAND*
``complete`` **-C** *STRING* | **--do-complete** *STRING*
.. synopsis::
complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS]
complete (-C | --do-complete) [--escape] STRING
Description
-----------
@ -17,35 +19,58 @@ Description
For an introduction to writing your own completions, see :ref:`Writing your own completions <completion-own>` in
the fish manual.
- ``-c COMMAND`` or ``--command COMMAND`` specifies that ``COMMAND`` is the name of the command. If there is no ``-c`` or ``-p``, one non-option argument will be used as the command.
The following options are available:
- ``-p COMMAND`` or ``--path COMMAND`` specifies that ``COMMAND`` is the absolute path of the command (optionally containing wildcards).
**-c** or **--command** *COMMAND*
Specifies that *COMMAND* is the name of the command. If there is no **-c** or **-p**, one non-option argument will be used as the command.
- ``-e`` or ``--erase`` deletes the specified completion.
**-p** or **--path** *COMMAND*
Specifies that *COMMAND* is the absolute path of the command (optionally containing wildcards).
- ``-s SHORT_OPTION`` or ``--short-option=SHORT_OPTION`` adds a short option to the completions list.
**-e** or **--erase**
Deletes the specified completion.
- ``-l LONG_OPTION`` or ``--long-option=LONG_OPTION`` adds a GNU style long option to the completions list.
**-s** or **--short-option** *SHORT_OPTION*
Adds a short option to the completions list.
- ``-o LONG_OPTION`` or ``--old-option=LONG_OPTION`` adds an old style long option to the completions list (See below for details).
**-l** or **--long-option** *LONG_OPTION*
Adds a GNU style long option to the completions list.
- ``-a ARGUMENTS`` or ``--arguments=ARGUMENTS`` adds the specified option arguments to the completions list.
**-o** or **--old-option** *LONG_OPTION*
Adds an old style long option to the completions list (see below for details).
- ``-k`` or ``--keep-order`` keeps the order of ``ARGUMENTS`` instead of sorting alphabetically. Multiple ``complete`` calls with ``-k`` result in arguments of the later ones displayed first.
**-a** or **--arguments** *ARGUMENTS*
Adds the specified option arguments to the completions list.
- ``-f`` or ``--no-files`` says that this completion may not be followed by a filename.
**-k** or **--keep-order**
Keeps the order of *ARGUMENTS* instead of sorting alphabetically. Multiple ``complete`` calls with **-k** result in arguments of the later ones displayed first.
- ``-F`` or ``--force-files`` says that this completion may be followed by a filename, even if another applicable ``complete`` specified ``--no-files``.
**-f** or **--no-files**
This completion may not be followed by a filename.
- ``-r`` or ``--require-parameter`` says that this completion must have an option argument, i.e. may not be followed by another option.
**-F** or **--force-files**
This completion may be followed by a filename, even if another applicable ``complete`` specified **--no-files**.
- ``-x`` or ``--exclusive`` is short for ``-r`` and ``-f``.
**-r** or **--require-parameter**
This completion must have an option argument, i.e. may not be followed by another option.
- ``-w WRAPPED_COMMAND`` or ``--wraps=WRAPPED_COMMAND`` causes the specified command to inherit completions from the wrapped command (See below for details).
**-x** or **--exclusive**
Short for **-r** and **-f**.
- ``-n CONDITION`` or ``--condition CONDITION`` specifies that this completion should only be used if the CONDITION (a shell command) returns 0. This makes it possible to specify completions that should only be used in some cases.
**-w** or **--wraps** *WRAPPED_COMMAND*
Causes the specified command to inherit completions from *WRAPPED_COMMAND* (see below for details).
- ``-C STRING`` or ``--do-complete=STRING`` makes complete try to find all possible completions for the specified string. If there is no STRING, the current commandline is used instead.
**-n** or **--condition** *CONDITION*
This completion should only be used if the *CONDITION* (a shell command) returns 0. This makes it possible to specify completions that should only be used in some cases.
**-C** or **--do-complete** *STRING*
Makes ``complete`` try to find all possible completions for the specified string. If there is no *STRING*, the current commandline is used instead.
**--escape**
When used with ``-C``, escape special characters in completions.
**-h** or **--help**
Displays help about using this command.
Command specific tab-completions in ``fish`` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as ``-h``, ``-help`` or ``--help``. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU getopt library. These styles are:

10
doc_src/cmds/contains.rst
View File

@ -6,7 +6,9 @@ contains - test if a word is present in a list
Synopsis
--------
``contains`` [**options**] *KEY* [*VALUES* ...]
.. synopsis::
contains [OPTIONS] KEY [VALUES ...]
Description
-----------
@ -16,7 +18,11 @@ If so, ``contains`` exits with code 0; if not, it exits with code 1.
The following options are available:
- **-i** or **--index** print the word index
**-i** or **--index**
Print the index (number of the element in the set) of the first matching element.
**-h** or **--help**
Displays help about using this command.
Note that ``contains`` interprets all arguments starting with a **-** as an option to ``contains``, until an **--** argument is reached.

4
doc_src/cmds/continue.rst
View File

@ -6,7 +6,9 @@ continue - skip the remainder of the current iteration of the current inner loop
Synopsis
--------
**LOOP_CONSTRUCT**; [*COMMANDS*...;] **continue**; [*COMMANDS*...;] **end**
.. synopsis::
LOOP_CONSTRUCT; [COMMANDS ...;] continue; [COMMANDS ...;] end
Description
-----------

8
doc_src/cmds/count.rst
View File

@ -6,9 +6,11 @@ count - count the number of elements of a list
Synopsis
--------
| ``count`` string1 string2...
| *command* | ``count``
| ``count`` [...] < *FILE*
.. synopsis::
count STRING1 STRING2 ...
COMMAND | count
count [...] < FILE
Description
-----------

4
doc_src/cmds/dirh.rst
View File

@ -6,7 +6,9 @@ dirh - print directory history
Synopsis
--------
``dirh``
.. synopsis::
dirh
Description
-----------

16
doc_src/cmds/dirs.rst
View File

@ -6,18 +6,26 @@ dirs - print directory stack
Synopsis
--------
``dirs`` [*-c*]
.. synopsis::
dirs [-c]
Description
-----------
``dirs`` prints the current :ref:`directory stack <directory-stack>`, as created by :ref:`pushd <cmd-pushd>` and modified by :ref:`popd <cmd-popd>`.
With "-c", it clears the directory stack instead.
The following options are available:
``dirs`` does not accept any parameters.
**-c**:
Clear the directory stack instead of printing it.
**-h** or **--help**
Displays help about using this command.
``dirs`` does not accept any arguments.
See Also
--------
- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
- the :ref:`cdh <cmd-cdh>` command, which provides a more intuitive way to navigate to recently visited directories.

6
doc_src/cmds/disown.rst
View File

@ -6,7 +6,9 @@ disown - remove a process from the list of jobs
Synopsis
--------
``disown`` [ **PID** ... ]
.. synopsis::
disown [PID ...]
Description
-----------
@ -21,6 +23,8 @@ If a job is stopped, it is sent a signal to continue running, and a warning is p
``disown`` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
The **--help** or **-h** option displays help about using this command.
Example
-------

16
doc_src/cmds/echo.rst
View File

@ -6,7 +6,9 @@ echo - display a line of text
Synopsis
--------
``echo`` [*options*] [*STRING*]
.. synopsis::
echo [OPTIONS] [STRING]
Description
-----------
@ -15,13 +17,17 @@ Description
The following options are available:
- ``-n``, Do not output a newline
- **-n**
Do not output a newline.
- ``-s``, Do not separate arguments with spaces
**-s**
Do not separate arguments with spaces.
- ``-E``, Disable interpretation of backslash escapes (default)
**-E**
Disable interpretation of backslash escapes (default).
- ``-e``, Enable interpretation of backslash escapes
**-e**
Enable interpretation of backslash escapes.
Unlike other shells, this echo accepts ``--`` to signal the end of the options.

4
doc_src/cmds/else.rst
View File

@ -6,7 +6,9 @@ else - execute command if a condition is not met
Synopsis
--------
**if** *CONDITION*; *COMMANDS_TRUE*...; [**else**; *COMMANDS_FALSE*...;] **end**
.. synopsis::
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
Description
-----------

5
doc_src/cmds/emit.rst
View File

@ -6,13 +6,16 @@ emit - emit a generic event
Synopsis
--------
``emit`` *EVENT_NAME* [*ARGUMENTS*...]
.. synopsis::
emit EVENT_NAME [ARGUMENTS ...]
Description
-----------
``emit`` emits, or fires, an event. Events are delivered to, or caught by, special functions called :ref:`event handlers <event>`. The arguments are passed to the event handlers as function arguments.
The **--help** or **-h** option displays help about using this command.
Example
-------

20
doc_src/cmds/end.rst
View File

@ -6,15 +6,19 @@ end - end a block of commands
Synopsis
--------
| **begin**
| [*COMMANDS*...]
| **end**
.. synopsis::
| **function** *NAME* [*OPTIONS*]; *COMMANDS*...; **end**
| **if** *CONDITION*; *COMMANDS_TRUE*...; [**else**; *COMMANDS_FALSE*...;] **end**
| **switch** *VALUE*; [**case** [*WILDCARD*...]; [*COMMANDS*...]; ...] **end**
| **while** *CONDITION*; *COMMANDS*...; **end**
| **for** *VARNAME* in [*VALUES*...]; **COMMANDS**...; **end**
begin
[COMMANDS ...]
end
.. synopsis::
function NAME [OPTIONS]; COMMANDS ...; end
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
switch VALUE; [case [WILDCARD ...]; [COMMANDS ...]; ...] end
while CONDITION; COMMANDS ...; end
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
-----------

4
doc_src/cmds/eval.rst
View File

@ -6,7 +6,9 @@ eval - evaluate the specified commands
Synopsis
--------
**eval** [*COMMANDS*...]
.. synopsis::
eval [COMMANDS ...]
Description
-----------

5
doc_src/cmds/exec.rst
View File

@ -6,13 +6,16 @@ exec - execute command in current process
Synopsis
--------
**exec** *COMMAND*
.. synopsis::
exec COMMAND
Description
-----------
``exec`` replaces the currently running shell with a new command. On successful completion, ``exec`` never returns. ``exec`` cannot be used inside a pipeline.
The **--help** or **-h** option displays help about using this command.
Example
-------

8
doc_src/cmds/exit.rst
View File

@ -7,12 +7,16 @@ exit - exit the shell
Synopsis
--------
**exit** [*code*]
.. synopsis::
exit [CODE]
Description
-----------
**exit** is a special builtin that causes the shell to exit. Either 255 or the *code* supplied is used, whichever is lesser.
**exit** is a special builtin that causes the shell to exit. Either 255 or the *CODE* supplied is used, whichever is lesser.
Otherwise, the exit status will be that of the last command executed.
If exit is called while sourcing a file (using the :ref:`source <cmd-source>` builtin) the rest of the file will be skipped, but the shell itself will not exit.
The **--help** or **-h** option displays help about using this command.

4
doc_src/cmds/false.rst
View File

@ -6,7 +6,9 @@ false - return an unsuccessful result
Synopsis
--------
**false**
.. synopsis::
false
Description
-----------

6
doc_src/cmds/fg.rst
View File

@ -6,7 +6,9 @@ fg - bring job to foreground
Synopsis
--------
``fg`` [*PID*]
.. synopsis::
fg [PID]
Description
-----------
@ -19,6 +21,8 @@ If ``PID`` is specified, the job containing a process with the specified process
For compatibility with other shells, job expansion syntax is supported for ``fg``. A *PID* of the format **%1** will foreground job 1.
Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
The **--help** or **-h** option displays help about using this command.
Example
-------

6
doc_src/cmds/fish.rst
View File

@ -7,8 +7,10 @@ fish - the friendly interactive shell
Synopsis
--------
| ``fish`` [*OPTIONS*] [*FILE* [ARGS ...]]
| ``fish`` [*OPTIONS*] [**-c** *COMMAND* [ARGS ...]]
.. synopsis::
fish [OPTIONS] [FILE [ARG ...]]
fish [OPTIONS] [-c COMMAND [ARG ...]]
Description
-----------

42
doc_src/cmds/fish_add_path.rst
View File

@ -7,8 +7,10 @@ fish_add_path - add to the path
Synopsis
--------
| ``fish_add_path`` *path*...
| ``fish_add_path`` [(*-g* | *--global*) | (*-U* | *--universal*) | (*-P* | *--path*)] [(*-m* | *--move*)] [(*-a* | *--append*) | (*-p* | *--prepend*)] [(*-v* | *--verbose*) | (*-n* | *--dry-run*)] *paths*...
.. synopsis::
fish_add_path path ...
fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] PATHS ...
Description
@ -22,21 +24,39 @@ Components are normalized by :ref:`realpath <cmd-realpath>`. Trailing slashes ar
Components are added in the order they are given, and they are prepended to the path unless ``--append`` is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths).
If no component is new, the variable ($fish_user_paths or $PATH) is not set again or otherwise modified, so variable handlers are not triggered.
If no component is new, the variable (:envvar:`fish_user_paths` or :envvar:`$PATH`) is not set again or otherwise modified, so variable handlers are not triggered.
If a component is not an existing directory, ``fish_add_path`` ignores it.
Options
-------
- ``-a`` or ``--append`` causes the components to be added to the *end* of the variable
- ``-p`` or ``--prepend`` causes the components to be added to the *front* of the variable (this is the default)
- ``-g`` or ``--global`` means to use a global $fish_user_paths
- ``-U`` or ``--universal`` means to use a universal $fish_user_paths - this is the default if it doesn't already exist
- ``-P`` or ``--path`` means to use $PATH directly
- ``-m`` or ``--move`` means to move already existing components to the place they would be added - by default they would be left in place and not added again
- ``-v`` or ``--verbose`` means to print the :ref:`set <cmd-set>` command used
- ``-n`` or ``--dry-run`` means to print the ``set`` command that would be used without executing it
**-a** or **--append**
Add components to the *end* of the variable.
**-p** or **--prepend**
Add components to the *front* of the variable (this is the default).
**-g** or **--global**
Use a global :envvar:`fish_user_paths`.
**-U** or **--universal**
Use a universal :envvar:`fish_user_paths` - this is the default if it doesn't already exist.
**-P** or **--path**
Manipulate :envvar:`PATH` directly.
**-m** or **--move**
Move already-existing components to the place they would be added - by default they would be left in place and not added again.
**-v** or **--verbose**
Print the :ref:`set <cmd-set>` command used.
**-n** or **--dry-run**
Print the ``set`` command that would be used without executing it.
**-h** or **--help**
Displays help about using this command.
If ``--move`` is used, it may of course lead to the path swapping order, so you should be careful doing that in config.fish.

5
doc_src/cmds/fish_breakpoint_prompt.rst
View File

@ -6,7 +6,10 @@ fish_breakpoint_prompt - define the prompt when stopped at a breakpoint
Synopsis
--------
**fish_breakpoint_prompt**
.. synopsis::
fish_breakpoint_prompt
::
function fish_breakpoint_prompt

8
doc_src/cmds/fish_command_not_found.rst
View File

@ -6,9 +6,11 @@ fish_command_not_found - what to do when a command wasn't found
Synopsis
--------
| **function** ``fish_command_not_found``
| ...
| **end**
.. synopsis::
function fish_command_not_found
...
end
Description

10
doc_src/cmds/fish_config.rst
View File

@ -6,9 +6,11 @@ fish_config - start the web-based configuration interface
Synopsis
--------
| ``fish_config`` [browse]
| ``fish_config`` **prompt** (choose | list | save | show)
| ``fish_config`` **theme** (choose | demo | dump | list | save | show)
.. synopsis::
fish_config [browse]
fish_config prompt (choose | list | save | show)
fish_config theme (choose | demo | dump | list | save | show)
Description
-----------
@ -41,6 +43,8 @@ Available subcommands for the ``theme`` command:
The themes are loaded from the theme directory shipped with fish or a ``themes`` directory in the fish configuration directory (typically ``~/.config/fish/themes``).
The **-h** or **--help** option displays help about using this command.
Example
-------

11
doc_src/cmds/fish_git_prompt.rst
View File

@ -6,12 +6,15 @@ fish_git_prompt - output git information for use in a prompt
Synopsis
--------
``fish_git_prompt``
.. synopsis::
fish_git_prompt
::
function fish_prompt
printf '%s' $PWD (fish_git_prompt) ' $ '
end
function fish_prompt
printf '%s' $PWD (fish_git_prompt) ' $ '
end
Description

5
doc_src/cmds/fish_greeting.rst
View File

@ -6,7 +6,10 @@ fish_greeting - display a welcome message in interactive shells
Synopsis
--------
**fish_greeting**
.. synopsis::
fish_greeting
::
function fish_greeting

7
doc_src/cmds/fish_hg_prompt.rst
View File

@ -6,7 +6,10 @@ fish_hg_prompt - output Mercurial information for use in a prompt
Synopsis
--------
**fish_hg_prompt**
.. synopsis::
fish_hg_prompt
::
function fish_prompt
@ -22,7 +25,7 @@ The fish_hg_prompt function displays information about the current Mercurial rep
By default, only the current branch is shown because ``hg status`` can be slow on a large repository. You can enable a more informative prompt by setting the variable ``$fish_prompt_hg_show_informative_status``, for example::
set --universal fish_prompt_hg_show_informative_status
set --universal fish_prompt_hg_show_informative_status
If you enabled the informative status, there are numerous customization options, which can be controlled with fish variables.

34
doc_src/cmds/fish_indent.rst
View File

@ -7,7 +7,9 @@ fish_indent - indenter and prettifier
Synopsis
--------
**fish_indent** [*OPTIONS*] [*FILE*...]
.. synopsis::
fish_indent [OPTIONS] [FILE ...]
Description
@ -17,20 +19,32 @@ Description
The following options are available:
- ``-w`` or ``--write`` indents a specified file and immediately writes to that file.
**-w** or **--write**
Indents a specified file and immediately writes to that file.
- ``-i`` or ``--no-indent`` do not indent commands; only reformat to one job per line.
**-i** or **--no-indent**
Do not indent commands; only reformat to one job per line.
- ``-c`` or ``--check`` do not indent, only return 0 if the code is already indented as fish_indent would, the number of failed files otherwise. Also print the failed filenames if not reading from stdin.
**-c** or **--check**
Do not indent, only return 0 if the code is already indented as fish_indent would, the number of failed files otherwise. Also print the failed filenames if not reading from standard input.
- ``-v`` or ``--version`` displays the current fish version and then exits.
**-v** or **--version**
Displays the current :program:`fish` version and then exits.
- ``--ansi`` colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as ``$fish_color_command``).
**--ansi**
Colorizes the output using ANSI escape sequences, appropriate for the current :envvar:`TERM`, using the colors defined in the environment (such as :envvar:`fish_color_command`).
- ``--html`` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``.
**--html**
Outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``.
- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` in :ref:`fish <cmd-fish>` (1) for details.
**-d** or **--debug=DEBUG_CATEGORIES**
Enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` in :ref:`fish <cmd-fish>` (1) for details.
- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr.
**-o** or **--debug-output=DEBUG_FILE**
Specify a file path to receive the debug output, including categories and ``fish_trace``. The default is standard error.
- ``--dump-parse-tree`` dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code.
**--dump-parse-tree**
Dumps information about the parsed statements to standard error. This is likely to be of interest only to people working on the fish source code.
**-h** or **--help**
Displays help about using this command.

4
doc_src/cmds/fish_is_root_user.rst
View File

@ -6,7 +6,9 @@ fish_is_root_user - check if the current user is root
Synopsis
--------
**fish_is_root_user**
.. synopsis::
fish_is_root_user
Description
-----------

22
doc_src/cmds/fish_key_reader.rst
View File

@ -6,29 +6,35 @@ fish_key_reader - explore what characters keyboard keys send
Synopsis
--------
**fish_key_reader** [*OPTIONS*]
.. synopsis::
fish_key_reader [OPTIONS]
Description
-----------
``fish_key_reader`` is used to explain how you would bind a certain key sequence. By default, it prints the :ref:`bind <cmd-bind>` command for one key sequence read interactively over standard input.
:program:`fish_key_reader` is used to explain how you would bind a certain key sequence. By default, it prints the :ref:`bind <cmd-bind>` command for one key sequence read interactively over standard input.
If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to stderr.
If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to standard error.
The following options are available:
- ``-c`` or ``--continuous`` begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
**-c** or **--continuous**
Begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
- ``-V`` or ``--verbose`` tells fish_key_reader to output timing information and explain the sequence in more detail.
**-V** or **--verbose**
Tells fish_key_reader to output timing information and explain the sequence in more detail.
- ``-h`` or ``--help`` prints usage information.
**-h** or **--help**
Displays help about using this command.
- ``-v`` or ``--version`` prints fish_key_reader's version and exits.
**-v** or **--version**
Displays the current :program:`fish` version and then exits.
Usage Notes
-----------
In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to standard error. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
``fish_key_reader`` intentionally disables handling of many signals. To terminate ``fish_key_reader`` in ``--continuous`` mode do:

5
doc_src/cmds/fish_mode_prompt.rst
View File

@ -6,7 +6,10 @@ fish_mode_prompt - define the appearance of the mode indicator
Synopsis
--------
**fish_mode_prompt**
.. synopsis::
fish_mode_prompt
::
function fish_mode_prompt

36
doc_src/cmds/fish_opt.rst
View File

@ -1,38 +1,48 @@
.. _cmd-fish_opt:
fish_opt - create an option spec for the argparse command
=========================================================
fish_opt - create an option specification for the argparse command
==================================================================
Synopsis
--------
| ``fish_opt`` [ **--help** ]
| ``fish_opt`` [ (**-slor**, **--multiple-vals=**) *optname*]
.. synopsis::
fish_opt [(-slor | --multiple-vals=) OPTNAME]
fish_opt --help
Description
-----------
This command provides a way to produce option specifications suitable for use with the :ref:`argparse <cmd-argparse>` command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides.
This command provides a way to produce option specifications suitable for use with the :ref:`argparse <cmd-argparse>` command. You can, of course, write the option specifications by hand without using this command. But you might prefer to use this for the clarity it provides.
The following ``argparse`` options are available:
- ``-s`` or ``--short`` takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
**-s** or **--short**
Takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
- ``-l`` or ``--long`` takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option spec.
**-l** or **--long**
Takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option specification.
- ``--long-only`` means the option spec being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., ``--short`` must be specified) but it cannot be used when parsing args using this option spec.
**--long-only**
The option being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., **--short** must be specified) but it cannot be used when parsing arguments using this option specification.
- ``-o`` or ``--optional-val`` means the option being defined can take a value but it is optional rather than required. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
**-o** or **--optional-val**
Tthe option being defined can take a value, but it is optional rather than required. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
- ``-r`` or ``--required-val`` means the option being defined requires a value. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
**-r** or **--required-val**
The option being defined requires a value. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
- ``--multiple-vals`` means the option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the args.
**--multiple-vals**
The option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the arguments.
- ``-h`` or ``--help`` displays help about using this command.
**-h** or **--help**
Displays help about using this command.
Examples
--------
Define a single option spec for the boolean help flag:
Define a single option specification for the boolean help flag:

5
doc_src/cmds/fish_prompt.rst
View File

@ -6,7 +6,10 @@ fish_prompt - define the appearance of the command line prompt
Synopsis
--------
``fish_prompt``
.. synopsis::
fish_prompt
::
function fish_prompt

5
doc_src/cmds/fish_status_to_signal.rst
View File

@ -6,7 +6,10 @@ fish_status_to_signal - convert exit codes to human-friendly signals
Synopsis
--------
``fish_status_to_signal`` *NUM*
.. synopsis::
fish_status_to_signal NUM
::
function fish_prompt

77
doc_src/cmds/fish_svn_prompt.rst
View File

@ -6,7 +6,10 @@ fish_svn_prompt - output Subversion information for use in a prompt
Synopsis
--------
``fish_svn_prompt``
.. synopsis::
fish_svn_prompt
::
function fish_prompt
@ -22,47 +25,47 @@ The fish_svn_prompt function displays information about the current Subversion r
There are numerous customization options, which can be controlled with fish variables.
- ``$__fish_svn_prompt_color_revision``
- :envvar:`__fish_svn_prompt_color_revision`
the colour of the revision number to display in the prompt
- ``$__fish_svn_prompt_char_separator``
- :envvar:`__fish_svn_prompt_char_separator`
the separator between status characters
A number of variables control the symbol ("display") and color ("color") for the different status indicators:
- ``$__fish_svn_prompt_char_added_display``
- ``$__fish_svn_prompt_char_added_color``
- ``$__fish_svn_prompt_char_conflicted_display``
- ``$__fish_svn_prompt_char_conflicted_color``
- ``$__fish_svn_prompt_char_deleted_display``
- ``$__fish_svn_prompt_char_deleted_color``
- ``$__fish_svn_prompt_char_ignored_display``
- ``$__fish_svn_prompt_char_ignored_color``
- ``$__fish_svn_prompt_char_modified_display``
- ``$__fish_svn_prompt_char_modified_color``
- ``$__fish_svn_prompt_char_replaced_display``
- ``$__fish_svn_prompt_char_replaced_color``
- ``$__fish_svn_prompt_char_unversioned_external_display``
- ``$__fish_svn_prompt_char_unversioned_external_color``
- ``$__fish_svn_prompt_char_unversioned_display``
- ``$__fish_svn_prompt_char_unversioned_color``
- ``$__fish_svn_prompt_char_missing_display``
- ``$__fish_svn_prompt_char_missing_color``
- ``$__fish_svn_prompt_char_versioned_obstructed_display``
- ``$__fish_svn_prompt_char_versioned_obstructed_color``
- ``$__fish_svn_prompt_char_locked_display``
- ``$__fish_svn_prompt_char_locked_color``
- ``$__fish_svn_prompt_char_scheduled_display``
- ``$__fish_svn_prompt_char_scheduled_color``
- ``$__fish_svn_prompt_char_switched_display``
- ``$__fish_svn_prompt_char_switched_color``
- ``$__fish_svn_prompt_char_token_present_display``
- ``$__fish_svn_prompt_char_token_present_color``
- ``$__fish_svn_prompt_char_token_other_display``
- ``$__fish_svn_prompt_char_token_other_color``
- ``$__fish_svn_prompt_char_token_stolen_display``
- ``$__fish_svn_prompt_char_token_stolen_color``
- ``$__fish_svn_prompt_char_token_broken_display``
- ``$__fish_svn_prompt_char_token_broken_color``
- :envvar:`__fish_svn_prompt_char_added_display`
- :envvar:`__fish_svn_prompt_char_added_color`
- :envvar:`__fish_svn_prompt_char_conflicted_display`
- :envvar:`__fish_svn_prompt_char_conflicted_color`
- :envvar:`__fish_svn_prompt_char_deleted_display`
- :envvar:`__fish_svn_prompt_char_deleted_color`
- :envvar:`__fish_svn_prompt_char_ignored_display`
- :envvar:`__fish_svn_prompt_char_ignored_color`
- :envvar:`__fish_svn_prompt_char_modified_display`
- :envvar:`__fish_svn_prompt_char_modified_color`
- :envvar:`__fish_svn_prompt_char_replaced_display`
- :envvar:`__fish_svn_prompt_char_replaced_color`
- :envvar:`__fish_svn_prompt_char_unversioned_external_display`
- :envvar:`__fish_svn_prompt_char_unversioned_external_color`
- :envvar:`__fish_svn_prompt_char_unversioned_display`
- :envvar:`__fish_svn_prompt_char_unversioned_color`
- :envvar:`__fish_svn_prompt_char_missing_display`
- :envvar:`__fish_svn_prompt_char_missing_color`
- :envvar:`__fish_svn_prompt_char_versioned_obstructed_display`
- :envvar:`__fish_svn_prompt_char_versioned_obstructed_color`
- :envvar:`__fish_svn_prompt_char_locked_display`
- :envvar:`__fish_svn_prompt_char_locked_color`
- :envvar:`__fish_svn_prompt_char_scheduled_display`
- :envvar:`__fish_svn_prompt_char_scheduled_color`
- :envvar:`__fish_svn_prompt_char_switched_display`
- :envvar:`__fish_svn_prompt_char_switched_color`
- :envvar:`__fish_svn_prompt_char_token_present_display`
- :envvar:`__fish_svn_prompt_char_token_present_color`
- :envvar:`__fish_svn_prompt_char_token_other_display`
- :envvar:`__fish_svn_prompt_char_token_other_color`
- :envvar:`__fish_svn_prompt_char_token_stolen_display`
- :envvar:`__fish_svn_prompt_char_token_stolen_color`
- :envvar:`__fish_svn_prompt_char_token_broken_display`
- :envvar:`__fish_svn_prompt_char_token_broken_color`
See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.

5
doc_src/cmds/fish_title.rst
View File

@ -6,7 +6,10 @@ fish_title - define the terminal's title
Synopsis
--------
``fish_title``
.. synopsis::
fish_title
::
function fish_title

4
doc_src/cmds/fish_update_completions.rst
View File

@ -6,7 +6,9 @@ fish_update_completions - update completions using manual pages
Synopsis
--------
``fish_update_completions``
.. synopsis::
fish_update_completions
Description
-----------

7
doc_src/cmds/fish_vcs_prompt.rst
View File

@ -6,7 +6,10 @@ fish_vcs_prompt - output version control system information for use in a prompt
Synopsis
--------
``fish_vcs_prompt``
.. synopsis::
fish_vcs_prompt
::
function fish_prompt
@ -26,7 +29,7 @@ It calls out to VCS-specific functions. The currently supported systems are:
If a VCS isn't installed, the respective function does nothing.
The svn prompt is disabled by default because it's slow on large svn repositories. To enable it, modify fish_vcs_prompt to uncomment it. See :ref:`funced <cmd-funced>`.
The Subversion prompt is disabled by default, because it's slow on large repositories. To enable it, modify ``fish_vcs_prompt`` to uncomment it. See :ref:`funced <cmd-funced>`.
For more information, see the documentation for each of the functions above.

6
doc_src/cmds/for.rst
View File

@ -6,7 +6,9 @@ for - perform a set of commands multiple times
Synopsis
--------
**for** *VARNAME* in [*VALUES*...]; *COMMANDS*...; **end**
.. synopsis::
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
-----------
@ -15,6 +17,8 @@ Description
Much like :ref:`set <cmd-set>`, **for** does not modify $status, but the evaluation of its subordinate commands can.
The **-h** or **--help** option displays help about using this command.
Example
-------

16
doc_src/cmds/funced.rst
View File

@ -6,7 +6,9 @@ funced - edit a function interactively
Synopsis
--------
``funced`` [**OPTIONS**] *NAME*
.. synopsis::
funced [OPTIONS] NAME
Description
-----------
@ -19,11 +21,17 @@ If the ``$VISUAL`` environment variable is set, it will be used as the program t
If there is no function called *NAME*, a new function will be created with the specified name.
- ``-e command`` or ``--editor command`` Open the function body inside the text editor given by the command (for example, ``-e vi``). The special command ``fish`` will use the built-in editor (same as specifying ``-i``).
**-e command** or **--editor command**
Open the function body inside the text editor given by the command (for example, **-e vi**). The special command ``fish`` will use the built-in editor (same as specifying **-i**).
- ``-i`` or ``--interactive`` Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
**-i** or **--interactive**
Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
- ``-s`` or ``--save`` Automatically save the function after successfully editing it.
**-s** or **--save**
Automatically save the function after successfully editing it.
**-h** or **--help**
Displays help about using this command.
Example
-------

6
doc_src/cmds/funcsave.rst
View File

@ -6,8 +6,10 @@ funcsave - save the definition of a function to the user's autoload directory
Synopsis
--------
| ``funcsave`` *FUNCTION_NAME*
| ``funcsave`` [**-q**] [(**-d** | **--directory**) *DIR*] *FUNCTION_NAME*
.. synopsis::
funcsave FUNCTION_NAME
funcsave [-q] [(-d | --directory) DIR] FUNCTION_NAME
Description

42
doc_src/cmds/function.rst
View File

@ -6,41 +6,51 @@ function - create a function
Synopsis
--------
**function** *NAME* [*OPTIONS*]; BODY ...; **end**
.. synopsis::
function NAME [OPTIONS]; BODY; end
Description
-----------
``function`` creates a new function ``NAME`` with the body ``BODY``.
``function`` creates a new function *NAME* with the body *BODY*.
A function is a list of commands that will be executed when the name of the function is given as a command.
The following options are available:
- ``-a NAMES`` or ``--argument-names NAMES`` assigns the value of successive command-line arguments to the names given in NAMES.
**-a** *NAMES* or **--argument-names** *NAMES*
Assigns the value of successive command-line arguments to the names given in *NAMES*.
- ``-d DESCRIPTION`` or ``--description=DESCRIPTION`` is a description of what the function does, suitable as a completion description.
**-d** *DESCRIPTION* or **--description** *DESCRIPTION*
A description of what the function does, suitable as a completion description.
- ``-w WRAPPED_COMMAND`` or ``--wraps=WRAPPED_COMMAND`` causes the function to inherit completions from the given wrapped command. See the documentation for :ref:`complete <cmd-complete>` for more information.
**-w** *WRAPPED_COMMAND* or **--wraps** *WRAPPED_COMMAND*
Inherit completions from the given *WRAPPED_COMMAND*. See the documentation for :ref:`complete <cmd-complete>` for more information.
- ``-e`` or ``--on-event EVENT_NAME`` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
**-e** *EVENT_NAME* or **--on-event** *EVENT_NAME*
Run this function when the specified named event is emitted. Fish internally generates named events, for example,when showing the prompt. Custom events can be emitted using the :ref:`emit <cmd-emit>` command.
- ``-v`` or ``--on-variable VARIABLE_NAME`` tells fish to run this function when the variable VARIABLE_NAME changes value. Note that fish makes no guarantees on any particular timing or even that the function will be run for every single ``set``. Rather it will be run when the variable has been set at least once, possibly skipping some values or being run when the variable has been set to the same value (except for universal variables set in other shells - only changes in the value will be picked up for those).
**-v** *VARIABLE_NAME* or **--on-variable** *VARIABLE_NAME*
Run this function when the variable *VARIABLE_NAME* changes value. Note that :program:`fish`` makes no guarantees on any particular timing or even that the function will be run for every single ``set``. Rather it will be run when the variable has been set at least once, possibly skipping some values or being run when the variable has been set to the same value (except for universal variables set in other shells - only changes in the value will be picked up for those).
- ``-j PID`` or ``--on-job-exit PID`` tells fish to run this function when the job containing a child process with the given PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
**-j** *PID* or **--on-job-exit** *PID*
Run this function when the job containing a child process with the given process identifier *PID* exits. Instead of a PID, the string 'caller' can be specified. This is only allowed when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- ``-p PID`` or ``--on-process-exit PID`` tells fish to run this function when the fish child process
with process ID PID exits. Instead of a PID, for backward compatibility,
"``%self``" can be specified as an alias for ``$fish_pid``, and the function will be run when the
current fish instance exits.
**-p** *PID* or **--on-process-exit** *PID*
Run this function when the fish child process with process ID PID exits. Instead of a PID, for backward compatibility, "``%self``" can be specified as an alias for ``$fish_pid``, and the function will be run when the current fish instance exits.
- ``-s`` or ``--on-signal SIGSPEC`` tells fish to run this function when the signal ``SIGSPEC`` is delivered. ``SIGSPEC`` can be a signal number, or the signal name, such as ``SIGHUP`` (or just ``HUP``). Note that the signal must have been delivered to fish; for example, :kbd:`Ctrl-C` sends ``SIGINT`` to the foreground process group, which will not be fish if you are running another command at the time.
**-s** *SIGSPEC* or **--on-signal** *SIGSPEC*
Run this function when the signal ``SIGSPEC`` is delivered. ``SIGSPEC`` can be a signal number, or the signal name, such as ``SIGHUP`` (or just ``HUP``). Note that the signal must have been delivered to :program:`fish`; for example, :kbd:`Ctrl-C` sends ``SIGINT`` to the foreground process group, which will not be :program:`fish` if you are running another command at the time.
- ``-S`` or ``--no-scope-shadowing`` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents are independent of the calling function.
It's important to note that this does not capture referenced variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using ``--no-scope-shadowing`` the scope of the function each time it is run is shared with the scope it was *called* from rather than the scope it was *defined* in.
**-S** or **--no-scope-shadowing**
Allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents are independent of the calling function.
- ``-V`` or ``--inherit-variable NAME`` snapshots the value of the variable ``NAME`` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the ``function notify`` example below for how this might be used.
It's important to note that this does not capture referenced variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using **--no-scope-shadowing** the scope of the function each time it is run is shared with the scope it was *called* from rather than the scope it was *defined* in.
**-V** or **--inherit-variable NAME**
Snapshots the value of the variable ``NAME`` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the ``function notify`` example below for how this might be used.
If the user enters any additional arguments after the function, they are inserted into the environment :ref:`variable list <variables-lists>` ``$argv``. If the ``--argument-names`` option is provided, the arguments are also assigned to names specified in that option.

52
doc_src/cmds/functions.rst
View File

@ -6,11 +6,13 @@ 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...*
.. synopsis::
functions [-a | --all] [-n | --names]
functions [-D | --details] [-v] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [-e | -q] FUNCTION ...
Description
-----------
@ -19,35 +21,49 @@ Description
The following options are available:
- ``-a`` or ``--all`` lists all functions, even those whose name starts with an underscore.
**-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.
**-c** 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.
**-d** 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.
**-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:
**-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 standard input, **-** 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,
- ``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 or has no description.
You should not assume that only five lines will be written since we may add additional information to the output in the future.
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.
**--no-details**
Turns off function path reporting, so just the definition will be printed.
- ``-n`` or ``--names`` lists the names of all defined functions.
**-n** or **--names**
Lists the names of all defined functions.
- ``-q`` or ``--query`` tests if the specified functions exist.
**-q** or **--query**
Tests if the specified functions exist.
- ``-v`` or ``--verbose`` will make some output more verbose.
**-v** or **--verbose**
Make some output more verbose.
- ``-H`` or ``--handlers`` will show all event handlers.
**-H** or **--handlers**
Show all event handlers.
- ``-t`` or ``--handlers-type TYPE`` will show all event handlers matching the given type
**-t** or **--handlers-type** *TYPE*
Show all event handlers matching the given *TYPE*.
**-h** or **--help**
Displays help about using this command.
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.

11
doc_src/cmds/help.rst
View File

@ -6,7 +6,9 @@ help - display fish documentation
Synopsis
--------
``help`` [*SECTION*]
.. synopsis::
help [SECTION]
Description
-----------
@ -15,9 +17,10 @@ Description
If a *SECTION* is specified, the help for that command is shown.
If the BROWSER environment variable is set, it will be used to display the documentation.
Otherwise, fish will search for a suitable browser.
The **-h** or **--help** option displays help about using this command.
If the :envvar:`BROWSER`` environment variable is set, it will be used to display the documentation.
Otherwise, fish will search for a suitable browser.
To use a different browser than as described above, one can set the :envvar:`fish_help_browser` variable.
This variable may be set as a list, where the first element is the browser command and the rest are browser options.
@ -29,4 +32,4 @@ Example
Notes
-----
Most builtin commands display their help in the terminal when given the **--help** option.
Most builtin commands, including this one, display their help in the terminal when given the **--help** option.

62
doc_src/cmds/history.rst
View File

@ -6,12 +6,17 @@ history - show and manipulate command history
Synopsis
--------
| ``history`` [**search**] [**--show-time** **--case-sensitive**]
\ \ [**--exact** | **--prefix** | **--contains**] [**--max** *n*] [**--null** **--reverse**]
\ \ [ *SEARCH_STRING...* ]
| ``history`` **delete** [**--show-time** **--case-sensitive**]
\ \ [**--exact** | **--prefix** | **--contains**] *SEARCH_STRING...*
| ``history`` { **merge** | **save** | **clear** | **clear_session** }
.. synopsis::
history [search] [--show-time] [--case-sensitive]
[--exact | --prefix | --contains] [--max N] [--null] [--reverse]
[SEARCH_STRING ...]
history delete [--case-sensitive]
[--exact | --prefix | --contains] SEARCH_STRING ...
history merge
history save
history clear
history clear-session
Description
-----------
@ -20,39 +25,54 @@ Description
The following operations (sub-commands) are available:
- **search** returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say ``history search`` if you wish to search for one of the subcommands. The ``--contains`` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the ``--reverse`` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.
**search**
Returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say ``history search`` if you wish to search for one of the subcommands. The ``--contains`` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the ``--reverse`` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.
- **delete** deletes history items. The ``--contains`` search option will be used if you don't specify a different search option. If you don't specify ``--exact`` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports ``--exact --case-sensitive`` deletion.
**delete**
Deletes history items. The ``--contains`` search option will be used if you don't specify a different search option. If you don't specify ``--exact`` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports ``--exact --case-sensitive`` deletion.
- **merge** immediately incorporates history changes from other sessions. Ordinarily ``fish`` ignores history changes from sessions started after the current one. This command applies those changes immediately.
**merge**
Immediately incorporates history changes from other sessions. Ordinarily ``fish`` ignores history changes from sessions started after the current one. This command applies those changes immediately.
- **save** immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.
**save**
Immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.
- **clear** clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless ``builtin history`` is used.
**clear**
Clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless ``builtin history`` is used.
- **clear-session** clears the history file from all activity of the current session. Note: If ``history merge`` or ``builtin history merge`` is run in a session only the history after this will be erased.
**clear-session**
Clears the history file from all activity of the current session. Note: If ``history merge`` or ``builtin history merge`` is run in a session, only the history after this will be erased.
The following options are available:
These flags can appear before or immediately after one of the sub-commands listed above.
- **-C** or **--case-sensitive** does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.
**-C** or **--case-sensitive**
Does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.
- **-c** or **--contains** searches or deletes items in the history that contain the specified text string. This is the default for the **--search** flag. This is not currently supported by the **delete** subcommand.
**-c** or **--contains**
Searches items in the history that contain the specified text string. This is the default for the **--search** flag. This is not currently supported by the **delete** subcommand.
- **-e** or **--exact** searches or deletes items in the history that exactly match the specified text string. This is the default for the **delete** subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the **-C** or **--case-sensitive** flag.
**-e** or **--exact**
Searches or deletes items in the history that exactly match the specified text string. This is the default for the **delete** subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the **-C** or **--case-sensitive** flag.
- **-p** or **--prefix** searches or deletes items in the history that begin with the specified text string. This is not currently supported by the **--delete** flag.
**-p** or **--prefix**
Searches items in the history that begin with the specified text string. This is not currently supported by the **delete** subcommand.
- **-t** or **--show-time** prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format ``# %c%n``. You can specify another format; e.g., ``--show-time="%Y-%m-%d %H:%M:%S "`` or ``--show-time="%a%I%p"``. The short option, **-t**, doesn't accept a strftime format string; it only uses the default format. Any strftime format is allowed, including ``%s`` to get the raw UNIX seconds since the epoch.
**-t** or **--show-time**
Prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format ``# %c%n``. You can specify another format; e.g., ``--show-time="%Y-%m-%d %H:%M:%S "`` or ``--show-time="%a%I%p"``. The short option, **-t**, doesn't accept a strftime format string; it only uses the default format. Any strftime format is allowed, including ``%s`` to get the raw UNIX seconds since the epoch.
- **-z** or **--null** causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by ``read -z`` to correctly handle multiline history entries.
**-z** or **--null**
Causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by ``read -z`` to correctly handle multiline history entries.
- ``-<number>`` ``-n <number>`` or ``--max=<number>`` limits the matched history items to the first "n" matching entries. This is only valid for ``history search``.
**-**\*NUMBER* **-n** *NUMBER* or **--max** *NUMBER*
Limits the matched history items to the first *NUMBER* matching entries. This is only valid for ``history search``.
- **-R** or **--reverse** causes the history search results to be ordered oldest to newest. Which is the order used by most shells. The default is newest to oldest.
**-R** or **--reverse**
Causes the history search results to be ordered oldest to newest. Which is the order used by most shells. The default is newest to oldest.
- **-h** or **--help** display help for this command.
**-h** or **--help**
Displays help for this command.
Example
-------

12
doc_src/cmds/if.rst
View File

@ -6,10 +6,12 @@ if - conditionally execute a command
Synopsis
--------
| **if** *CONDITION*; *COMMANDS_TRUE*...;
| [**else** **if** *CONDITION2*; *COMMANDS_TRUE2*...;]
| [**else**; *COMMANDS_FALSE*...;]
| **end**
.. synopsis::
if CONDITION; COMMANDS_TRUE ...;
[else if CONDITION2; COMMANDS_TRUE2 ...;]
[else; COMMANDS_FALSE ...;]
end
Description
-----------
@ -20,6 +22,8 @@ You can use :ref:`and <cmd-and>` or :ref:`or <cmd-or>` in the condition. See the
The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
The **-h** or **--help** option displays help about using this command.
Example
-------

5
doc_src/cmds/isatty.rst
View File

@ -6,7 +6,9 @@ isatty - test if a file descriptor is a terminal
Synopsis
--------
``isatty`` [*FILE DESCRIPTOR*]
.. synopsis::
isatty [FILE DESCRIPTOR]
Description
-----------
@ -17,6 +19,7 @@ Description
If the specified file descriptor is a terminal device, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.
The **-h** or **--help** option displays help about using this command.
Examples
--------

26
doc_src/cmds/jobs.rst
View File

@ -6,7 +6,9 @@ jobs - print currently running jobs
Synopsis
--------
``jobs`` [*OPTIONS*] [ *PID* | %*JOBID* ]
.. synopsis::
jobs [OPTIONS] [PID | %JOBID]
Description
@ -14,21 +16,29 @@ Description
``jobs`` prints a list of the currently running :ref:`jobs <syntax-job-control>` and their status.
jobs accepts the following switches:
``jobs`` accepts the following options:
- ``-c`` or ``--command`` prints the command name for each process in jobs.
**-c** or **--command**
Prints the command name for each process in jobs.
- ``-g`` or ``--group`` only prints the group ID of each job.
**-g** or **--group**
Only prints the group ID of each job.
- ``-l`` or ``--last`` prints only the last job to be started.
**-l** or **--last**
Prints only the last job to be started.
- ``-p`` or ``--pid`` prints the process ID for each process in all jobs.
**-p** or **--pid**
Prints the process ID for each process in all jobs.
- ``-q`` or ``--query`` prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also ``--quiet`` (but this is deprecated).
**-q** or **--query**
Prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also **--quiet** (but this is deprecated).
**-h** or **--help**
Displays help about using this command.
On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
Arguments of the form ``PID`` or ``%JOBID`` restrict the output to jobs with the selected process identifiers or job numbers respectively.
Arguments of the form *PID* or *%JOBID* restrict the output to jobs with the selected process identifiers or job numbers respectively.
If the output of ``jobs`` is redirected or if it is part of a command substitution, the column header that is usually printed is omitted, making it easier to parse.

55
doc_src/cmds/math.rst
View File

@ -6,7 +6,9 @@ math - perform mathematics calculations
Synopsis
--------
``math`` [**-s** | **--scale** *N*] [**-b** | **--base** *BASE*] [--] *EXPRESSION...*
.. synopsis::
math [(-s | --scale) N] [(-b | --base) BASE] EXPRESSION ...
Description
@ -46,6 +48,9 @@ The following options are available:
Hex numbers will be printed with a ``0x`` prefix.
Octal numbers will have a prefix of ``0`` but aren't understood by ``math`` as input.
**-h** or **--help**
Displays help about using this command.
Return Values
-------------
@ -59,6 +64,8 @@ Syntax
For numbers, ``.`` is always the radix character regardless of locale - ``2.5``, not ``2,5``.
Scientific notation (``10e5``) and hexadecimal (``0xFF``) are also available.
``math`` allows you to use underscores as visual separators for digit grouping. For example, you can write ``1_000_000``, ``0x_89_AB_CD_EF``, and ``1.234_567_e89``.
Operators
---------
@ -106,56 +113,56 @@ Functions
``abs``
the absolute value, with positive sign
``acos``
arc cosine
arc cosine
``asin``
arc sine
arc sine
``atan``
arc tangent
arc tangent
``atan2``
arc tangent of two variables
arc tangent of two variables
``bitand``, ``bitor`` and ``bitxor``
perform bitwise operations.
These will throw away any non-integer parts andd interpret the rest as an int.
``ceil``
round number up to nearest integer
round number up to nearest integer
``cos``
the cosine
the cosine
``cosh``
hyperbolic cosine
hyperbolic cosine
``exp``
the base-e exponential function
the base-e exponential function
``fac``
factorial - also known as ``x!`` (``x * (x - 1) * (x - 2) * ... * 1``)
factorial - also known as ``x!`` (``x * (x - 1) * (x - 2) * ... * 1``)
``floor``
round number down to nearest integer
round number down to nearest integer
``ln``
the base-e logarithm
the base-e logarithm
``log`` or ``log10``
the base-10 logarithm
the base-10 logarithm
``log2``
the base-2 logarithm
the base-2 logarithm
``max``
returns the larger of two numbers
returns the larger of two numbers
``min``
returns the smaller of two numbers
returns the smaller of two numbers
``ncr``
"from n choose r" combination function - how many subsets of size r can be taken from n (order doesn't matter)
"from n choose r" combination function - how many subsets of size r can be taken from n (order doesn't matter)
``npr``
the number of subsets of size r that can be taken from a set of n elements (including different order)
the number of subsets of size r that can be taken from a set of n elements (including different order)
``pow(x,y)``
returns x to the y (and can be written as ``x ^ y``)
``round``
rounds to the nearest integer, away from 0
rounds to the nearest integer, away from 0
``sin``
the sine function
the sine function
``sinh``
the hyperbolic sine
the hyperbolic sine
``sqrt``
the square root - (can also be written as ``x ^ 0.5``)
the square root - (can also be written as ``x ^ 0.5``)
``tan``
the tangent
the tangent
``tanh``
the hyperbolic tangent
the hyperbolic tangent
All of the trigonometric functions use radians (the pi-based scale, not 360°).

12
doc_src/cmds/nextd.rst
View File

@ -6,16 +6,20 @@ nextd - move forward through directory history
Synopsis
--------
``nextd`` [ **-l** | **--list** ] [*POS*]
.. synopsis::
nextd [-l | --list] [POS]
Description
-----------
``nextd`` moves forwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
``nextd`` moves forwards *POS* positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
If the ``-l`` or ``--list`` flag is specified, the current directory history is also displayed.
If the **-l** or **--list** option is specified, the current directory history is also displayed.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
The **-h** or **--help** option displays help about using this command.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the :envvar:`dirprev` and :envvar:`dirnext` variables which this command manipulates.
Example
-------

5
doc_src/cmds/not.rst
View File

@ -6,7 +6,9 @@ not - negate the exit status of a job
Synopsis
--------
**not** *COMMAND* [*options*...]
.. synopsis::
not COMMAND [OPTIONS ...]
Description
@ -14,6 +16,7 @@ Description
``not`` negates the exit status of another command. If the exit status is zero, ``not`` returns 1. Otherwise, ``not`` returns 0.
The **-h** or **--help** option displays help about using this command.
Example
-------

4
doc_src/cmds/open.rst
View File

@ -6,7 +6,9 @@ open - open file in its default application
Synopsis
--------
``open`` *FILES*...
.. synopsis::
open FILES ...
Description

6
doc_src/cmds/or.rst
View File

@ -6,7 +6,9 @@ or - conditionally execute a command
Synopsis
--------
*COMMAND1*; **or** *COMMAND2*
.. synopsis::
COMMAND1; or COMMAND2
Description
-----------
@ -17,6 +19,8 @@ Description
``or`` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
The **-h** or **--help** option displays help about using this command.
Example
-------

6
doc_src/cmds/popd.rst
View File

@ -6,13 +6,17 @@ popd - move through directory stack
Synopsis
--------
``popd``
.. synopsis::
popd
Description
-----------
``popd`` removes the top directory from the :ref:`directory stack <directory-stack>` and changes the working directory to the new top directory. Use :ref:`pushd <cmd-pushd>` to add directories to the stack.
The **-h** or **--help** option displays help about using this command.
Example
-------

12
doc_src/cmds/prevd.rst
View File

@ -6,16 +6,20 @@ prevd - move backward through directory history
Synopsis
--------
``prevd`` [ **-l** | **--list** ] [*POS*]
.. synopsis::
prevd [-l | --list] [POS]
Description
-----------
``prevd`` moves backwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
``prevd`` moves backwards *POS* positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
If the ``-l`` or ``--list`` flag is specified, the current history is also displayed.
If the **-l** or **--list** flag is specified, the current history is also displayed.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the :envvar:`dirprev` and :envvar:`dirnext` variables which this command manipulates.
The **-h** or **--help** option displays help about using this command.
Example
-------

8
doc_src/cmds/printf.rst
View File

@ -6,7 +6,9 @@ printf - display text according to a format string
Synopsis
--------
``printf`` *FORMAT* [*ARGUMENT* ...]
.. synopsis::
printf FORMAT [ARGUMENT ...]
Description
-----------
@ -17,9 +19,9 @@ Description
To see the documentation on the ``printf`` command you might have,
use ``command man printf``.
printf uses the format string FORMAT to print the ARGUMENT arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
``printf`` uses the format string *FORMAT* to print the *ARGUMENT* arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
The ``format`` argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
The *FORMAT* argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
Unlike :ref:`echo <cmd-echo>`, ``printf`` does not append a new line unless it is specified as part of the string.

4
doc_src/cmds/prompt_hostname.rst
View File

@ -6,7 +6,9 @@ prompt_hostname - print the hostname, shortened for use in the prompt
Synopsis
--------
``prompt_hostname``
.. synopsis::
prompt_hostname
Description
-----------

6
doc_src/cmds/prompt_login.rst
View File

@ -6,12 +6,14 @@ prompt_login - describe the login suitable for prompt
Synopsis
--------
``prompt_login``
.. synopsis::
prompt_login
Description
-----------
``prompt_login`` is a function to describe the current login. It will show the user, the host and also whether the shell is running in a chroot (currently debian's debian_chroot is supported).
``prompt_login`` is a function to describe the current login. It will show the user, the host and also whether the shell is running in a chroot (currently Debian's ``debian_chroot`` file is supported).
Examples
--------

21
doc_src/cmds/prompt_pwd.rst
View File

@ -6,25 +6,32 @@ prompt_pwd - print pwd suitable for prompt
Synopsis
--------
``prompt_pwd``
.. synopsis::
prompt_pwd
Description
-----------
``prompt_pwd`` is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.
To change the number of characters per path component, pass ``--dir-length=`` or set ``$fish_prompt_pwd_dir_length`` to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. This defaults to 1.
To change the number of characters per path component, pass ``--dir-length=`` or set :envvar:`fish_prompt_pwd_dir_length` to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. This defaults to 1.
To keep some components unshortened, pass ``--full-length-dirs=`` or set ``$fish_prompt_pwd_full_dirs`` to the number of components. This defaults to 1, keeping the last component.
To keep some components unshortened, pass ``--full-length-dirs=`` or set :envvar:`$fish_prompt_pwd_full_dirs` to the number of components. This defaults to 1, keeping the last component.
If any positional arguments are given, prompt_pwd shortens them instead of $PWD.
If any positional arguments are given, ``prompt_pwd`` shortens them instead of $PWD.
Options
-------
- ``-h`` or ``--help`` displays the help and exits
- ``-d`` or ``--dir-length=MAX`` causes the components to be shortened to MAX characters each. This overrides $fish_prompt_pwd_dir_length.
- ``-D`` or ``--full-length-dirs=NUM`` keeps NUM components (counted from the right) as full length without shortening. This overrides $fish_prompt_pwd_full_dirs.
**-d** or **--dir-length** *MAX*
Causes the components to be shortened to *MAX* characters each. This overrides :envvar:`fish_prompt_pwd_dir_length`.
**-D** or **--full-length-dirs** *NUM*
Keeps *NUM* components (counted from the right) as full length without shortening. This overrides :envvar:`fish_prompt_pwd_full_dirs`.
**-h** or **--help**
Displays help about using this command.
Examples
--------

16
doc_src/cmds/psub.rst
View File

@ -6,7 +6,9 @@ psub - perform process substitution
Synopsis
--------
*COMMAND1* ( *COMMAND2* | ``psub`` [**-F** | -**-fifo**] [**-f** | **--file**] [**-s** *SUFFIX*] )
.. synopsis::
COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [(-s | --suffix) SUFFIX] )
Description
-----------
@ -15,11 +17,17 @@ Some shells (e.g., ksh, bash) feature a syntax that is a mix between command sub
The following options are available:
- ``-f`` or ``--file`` will cause psub to use a regular file instead of a named pipe to communicate with the calling process. This will cause ``psub`` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default.
**-f** or **--file**
Use a regular file instead of a named pipe to communicate with the calling process. This will cause ``psub`` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default.
- ``-F`` or ``--fifo`` will cause psub to use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur.
**-F** or **--fifo**
Use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur.
- ``-s`` or ``--suffix`` will append SUFFIX to the filename.
**-s** or **--suffix** *SUFFIX*
Append SUFFIX to the filename.
**-h** or **--help**
Displays help about using this command.
Example
-------

8
doc_src/cmds/pushd.rst
View File

@ -6,12 +6,14 @@ pushd - push directory to directory stack
Synopsis
--------
``pushd`` *DIRECTORY*
.. synopsis::
pushd DIRECTORY
Description
-----------
The ``pushd`` function adds ``DIRECTORY`` to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
The ``pushd`` function adds *DIRECTORY* to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
Without arguments, it exchanges the top two directories in the stack.
@ -19,6 +21,8 @@ Without arguments, it exchanges the top two directories in the stack.
``pushd -NUMBER`` rotates clockwise i.e. top to bottom.
The **-h** or **--help** option displays help about using this command.
Example
-------

15
doc_src/cmds/pwd.rst
View File

@ -6,8 +6,10 @@ pwd - output the current working directory
Synopsis
--------
| ``pwd`` [**-P** | **--physical**]
| ``pwd`` [**-L** | **--logical**]
.. synopsis::
pwd [-P | --physical]
pwd [-L | --logical]
Description
@ -23,9 +25,14 @@ Description
The following options are available:
- ``-L`` or ``--logical`` Output the logical working directory, without resolving symlinks (default behavior).
**-L** or **--logical**
Output the logical working directory, without resolving symlinks (default behavior).
- ``-P`` or ``--physical`` Output the physical working directory, with symlinks resolved.
**-P** or **--physical**
Output the physical working directory, with symlinks resolved.
**-h** or **--help**
Displays help about using this command.
See Also
--------

20
doc_src/cmds/random.rst
View File

@ -6,28 +6,34 @@ random - generate random number
Synopsis
--------
| ``random``
| ``random`` *SEED*
| ``random`` *START* *END*
| ``random`` *START* *STEP* *END*
| ``random`` choice [*ITEMS*...]
.. synopsis::
random
random SEED
random START END
random START STEP END
random choice [ITEMS ...]
Description
-----------
``random`` generates a pseudo-random integer from a uniform distribution. The
range (inclusive) depends on the arguments.
No arguments indicate a range of 0 to 32767 (inclusive).
If one argument is specified, the internal engine will be seeded with the
argument for future invocations of ``random`` and no output will be produced.
Two arguments indicate a range from START to END (both START and END included).
Two arguments indicate a range from *START* to *END* (both *START* and *END* included).
Three arguments indicate a range from START to END with a spacing of STEP
Three arguments indicate a range from *START* to *END* with a spacing of *STEP*
between possible outputs.
``random choice`` will select one random item from the succeeding arguments.
The **-h** or **--help** option displays help about using this command.
Note that seeding the engine will NOT give the same result across different
systems.

69
doc_src/cmds/read.rst
View File

@ -6,53 +6,72 @@ read - read line of input into variables
Synopsis
--------
``read`` [*options*] [*VARIABLE* ...]
.. synopsis::
read [OPTIONS] [VARIABLE ...]
Description
-----------
``read`` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, ``read`` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as ``REPLY``) for storing the result - instead, it is printed on standard output.
``read`` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, ``read`` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as :envvar:`REPLY`) for storing the result - instead, it is printed on standard output.
The following options are available:
- ``-c CMD`` or ``--command=CMD`` sets the initial string in the interactive mode command buffer to ``CMD``.
**-c** *CMD* or **--command** *CMD*
Sets the initial string in the interactive mode command buffer to *CMD*.
- ``-d DELIMITER`` or ``--delimiter=DELIMITER`` splits on DELIMITER. DELIMITER will be used as an entire string to split on, not a set of characters.
**-d** or **--delimiter** *DELIMITER*
Splits on *DELIMITER*. *DELIMITER* will be used as an entire string to split on, not a set of characters.
- ``-g`` or ``--global`` makes the variables global.
**-g** or **--global**
Makes the variables global.
- ``-s`` or ``--silent`` masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
**-s** or **--silent**
Masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
- ``-f`` or ``--function`` scopes the variable to the currently executing function. It is erased when the function ends.
**-f** or **--function**
Scopes the variable to the currently executing function. It is erased when the function ends.
- ``-l`` or ``--local`` scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as ``--function``.
**-l** or **--local**
Scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as **--function**.
- ``-n NCHARS`` or ``--nchars=NCHARS`` makes ``read`` return after reading NCHARS characters or the end of
the line, whichever comes first.
**-n** or **--nchars** *NCHARS*
Makes ``read`` return after reading *NCHARS* characters or the end of the line, whichever comes first.
- ``-p PROMPT_CMD`` or ``--prompt=PROMPT_CMD`` uses the output of the shell command ``PROMPT_CMD`` as the prompt for the interactive mode. The default prompt command is ``set_color green; echo read; set_color normal; echo "> "``
**-p** or **--prompt** *PROMPT_CMD*
Uses the output of the shell command *PROMPT_CMD* as the prompt for the interactive mode. The default prompt command is ``set_color green; echo read; set_color normal; echo "> "``
- ``-P PROMPT_STR`` or ``--prompt-str=PROMPT_STR`` uses the string as the prompt for the interactive mode. It is equivalent to ``echo PROMPT_STR`` and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the :ref:`echo <cmd-echo>` command.
**-P** or **--prompt-str** *PROMPT_STR*
Uses the *PROMPT_STR* as the prompt for the interactive mode. It is equivalent to ``echo $PROMPT_STR`` and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the :ref:`echo <cmd-echo>` command.
- ``-R RIGHT_PROMPT_CMD`` or ``--right-prompt=RIGHT_PROMPT_CMD`` uses the output of the shell command ``RIGHT_PROMPT_CMD`` as the right prompt for the interactive mode. There is no default right prompt command.
**-R** or **--right-prompt** *RIGHT_PROMPT_CMD*
Uses the output of the shell command *RIGHT_PROMPT_CMD* as the right prompt for the interactive mode. There is no default right prompt command.
- ``-S`` or ``--shell`` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. NOTE: Prior to fish 3.0, the short opt for ``--shell`` was ``-s``, but it has been changed for compatibility with bash's ``-s`` short opt for ``--silent``.
**-S** or **--shell**
Enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. NOTE: Prior to fish 3.0, the short opt for **--shell** was **-s**, but it has been changed for compatibility with bash's **-s** short opt for **--silent**.
- ``-t`` -or ``--tokenize`` causes read to split the input into variables by the shell's tokenization rules. This means it will honor quotes and escaping. This option is of course incompatible with other options to control splitting like ``--delimiter`` and does not honor $IFS (like fish's tokenizer). It saves the tokens in the manner they'd be passed to commands on the commandline, so e.g. ``a\ b`` is stored as ``a b``. Note that currently it leaves command substitutions intact along with the parentheses.
**-t** -or **--tokenize**
Causes read to split the input into variables by the shell's tokenization rules. This means it will honor quotes and escaping. This option is of course incompatible with other options to control splitting like **--delimiter** and does not honor :envvar:`IFS` (like fish's tokenizer). It saves the tokens in the manner they'd be passed to commands on the commandline, so e.g. ``a\ b`` is stored as ``a b``. Note that currently it leaves command substitutions intact along with the parentheses.
- ``-u`` or ``--unexport`` prevents the variables from being exported to child processes (default behaviour).
**-u** or **--unexport**
Prevents the variables from being exported to child processes (default behaviour).
- ``-U`` or ``--universal`` causes the specified shell variable to be made universal.
**-U** or **--universal**
Causes the specified shell variable to be made universal.
- ``-x`` or ``--export`` exports the variables to child processes.
**-x** or **--export**
Exports the variables to child processes.
- ``-a`` or ``--list`` stores the result as a list in a single variable. This option is also available as ``--array`` for backwards compatibility.
**-a** or **--list**
Stores the result as a list in a single variable. This option is also available as **--array** for backwards compatibility.
- ``-z`` or ``--null`` marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
**-z** or **--null**
Marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
- ``-L`` or ``--line`` reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the ``--delimiter`` option.
**-L** or **--line**
Reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the ``--delimiter`` option.
Without the ``--line`` option, ``read`` reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in ``VARIABLES``. If there are more tokens than variables, the complete remainder is assigned to the last variable.
Without the ``--line`` option, ``read`` reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in *VARIABLES*. If there are more tokens than variables, the complete remainder is assigned to the last variable.
If no option to determine how to split like ``--delimiter``, ``--line`` or ``--tokenize`` is given, the variable ``IFS`` is used as a list of characters to split on. Relying on the use of ``IFS`` is deprecated and this behaviour will be removed in future versions. The default value of ``IFS`` contains space, tab and newline characters. As a special case, if ``IFS`` is set to the empty string, each character of the input is considered a separate token.
@ -72,14 +91,14 @@ When ``read`` reaches the end-of-file (EOF) instead of the terminator, the exit
Otherwise, it is set to 0.
In order to protect the shell from consuming too many system resources, ``read`` will only consume a
maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then VARIABLE
maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then *VARIABLE*
is set to empty and the exit status is set to 122. This limit can be altered with the
``fish_read_limit`` variable. If set to 0 (zero), the limit is removed.
:envvar:`fish_read_limit` variable. If set to 0 (zero), the limit is removed.
Example
-------
The following code stores the value 'hello' in the shell variable ``$foo``.
The following code stores the value 'hello' in the shell variable :envvar:`$foo`.

10
doc_src/cmds/realpath.rst
View File

@ -7,7 +7,9 @@ realpath - convert a path to an absolute path without symlinks
Synopsis
--------
**realpath** [*options*] *PATH*
.. synopsis::
realpath [OPTIONS] PATH
Description
-----------
@ -25,4 +27,8 @@ If a :command:`realpath` command exists, that will be preferred.
The following options are available:
- ``-s`` or ``--no-symlinks``: Don't resolve symlinks, only make paths absolute, squash multiple slashes and remove trailing slashes.
**-s** or **--no-symlinks**
Don't resolve symlinks, only make paths absolute, squash multiple slashes and remove trailing slashes.
**-h** or **--help**
Displays help about using this command.

8
doc_src/cmds/return.rst
View File

@ -7,13 +7,15 @@ return - stop the current inner function
Synopsis
--------
**return** [*n*]
.. synopsis::
return [N]
Description
-----------
:program:`return` halts a currently running function.
The exit status is set to ``n`` if it is given.
The exit status is set to *N* if it is given.
If :program:`return` is invoked outside of a function or dot script it is equivalent to exit.
It is often added inside of a conditional block such as an :ref:`if <cmd-if>` statement or a :ref:`switch <cmd-switch>` statement to conditionally stop the executing function and return to the caller; it can also be used to specify the exit status of a function.
@ -21,6 +23,8 @@ It is often added inside of a conditional block such as an :ref:`if <cmd-if>` st
If at the top level of a script, it exits with the given status, like :ref:`exit <cmd-exit>`.
If at the top level in an interactive session, it will set :envvar:`status`, but not exit the shell.
The **-h** or **--help** option displays help about using this command.
Example
-------

67
doc_src/cmds/set.rst
View File

@ -6,13 +6,15 @@ set - display and change shell variables
Synopsis
--------
| ``set`` [*scope options*]
| ``set`` [*options*] *VARIABLE* *VALUES*...
| ``set`` [*options*] *VARIABLE*[*indicies*]... *VALUES*...
| ``set`` ( **-q** | **--query** ) [*scope options*] *VARIABLE* ...
| ``set`` ( **-e** | **--erase** ) [*scope options*] *VARIABLE* ...
| ``set`` ( **-e** | **--erase** ) [*scope options*] *VARIABLE*\[*indicies*] ...
| ``set`` ( **-S** | **--show** ) *VARIABLE*...
.. synopsis::
set [SCOPE_OPTIONS]
set [OPTIONS] VARIABLE VALUES ...
set [OPTIONS] VARIABLE[INDICES] VALUES ...
set (-q | --query) [SCOPE_OPTIONS] VARIABLE ...
set (-e | --erase) [SCOPE_OPTIONS] VARIABLE ...
set (-e | --erase) [SCOPE_OPTIONS] VARIABLE[INDICES] ...
set (-S | --show) VARIABLE ...
Description
-----------
@ -31,40 +33,57 @@ With ``--show``, ``set`` will describe the given variable names, explaining how
The following options control variable scope:
- ``-f`` or ``--function`` scopes the variable to the currently executing function. It is erased when the function ends.
**-f** or **--function**
Scopes the variable to the currently executing function. It is erased when the function ends.
- ``-l`` or ``--local`` scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as ``--function``.
**-l** or **--local**
Scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as **--function**.
- ``-g`` or ``--global`` causes the specified shell variable to be given a global scope. Global variables don't disappear and are available to all functions running in the same shell. They can even be modified.
**-g** or **--global**
Causes the specified shell variable to be given a global scope. Global variables don't disappear and are available to all functions running in the same shell. They can even be modified.
- ``-U`` or ``--universal`` causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current user's fish instances on the current computer, and will be preserved across restarts of the shell.
**-U** or **--universal**
Causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current user's fish instances on the current computer, and will be preserved across restarts of the shell.
These options control additional variable options:
- ``-x`` or ``--export`` causes the specified shell variable to be exported to child processes (making it an "environment variable")
**-x** or **--export**
Causes the specified shell variable to be exported to child processes (making it an "environment variable")
- ``-u`` or ``--unexport`` causes the specified shell variable to NOT be exported to child processes
**-u** or **--unexport**
Causes the specified shell variable to NOT be exported to child processes
- ``--path`` causes the specified variable to be treated as a path variable, meaning it will automatically be split on colons, and joined using colons when quoted (``echo "$PATH"``) or exported.
**--path**
Causes the specified variable to be treated as a :ref:`path variable <variables-path>`, meaning it will automatically be split on colons, and joined using colons when quoted (``echo "$PATH"``) or exported.
- ``--unpath`` causes the specified variable to not be treated as a path variable. Variables with a name ending in "PATH" are automatically path variables, so this can be used to treat such a variable normally.
**--unpath**
Causes the specified variable to not be treated as a :ref:`path variable <variables-path>`. Variables with a name ending in "PATH" are automatically path variables, so this can be used to treat such a variable normally.
The following other options are available:
- ``-a`` or ``--append`` causes the values to be appended to the current set of values for the variable. This can be used with ``--prepend`` to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
**-a** or **--append**
Causes the values to be appended to the current set of values for the variable. This can be used with **--prepend** to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
- ``-p`` or ``--prepend`` causes the values to be prepended to the current set of values for the variable. This can be used with ``--append`` to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
**-p** or **--prepend**
Causes the values to be prepended to the current set of values for the variable. This can be used with **--append** to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
- ``-e`` or ``--erase`` causes the specified shell variables to be erased
**-e** or **--erase**
Causes the specified shell variables to be erased
- ``-q`` or ``--query`` test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined, up to a maximum of 255. If no variable was given, it also returns 255.
**-q** or **--query**
Test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined, up to a maximum of 255. If no variable was given, it also returns 255.
- ``-n`` or ``--names``: List only the names of all defined variables, not their value. The names are guaranteed to be sorted.
**-n** or **--names**
List only the names of all defined variables, not their value. The names are guaranteed to be sorted.
- ``-S`` or ``--show`` shows information about the given variables. If no variable names are given then all variables are shown in sorted order. It shows the scopes the given variables are set in, along with the values in each and whether or not it is exported. No other flags can be used with this option.
**-S** or **--show**
Shows information about the given variables. If no variable names are given then all variables are shown in sorted order. It shows the scopes the given variables are set in, along with the values in each and whether or not it is exported. No other flags can be used with this option.
- ``-L`` or ``--long`` do not abbreviate long values when printing set variables
**-L** or **--long**
Do not abbreviate long values when printing set variables.
**-h** or **--help**
Displays help about using this command.
If a variable is set to more than one value, the variable will be a list with the specified elements. If a variable is set to zero elements, it will become a list with zero elements.
@ -92,12 +111,12 @@ In query mode, the scope to be examined can be specified. Whether the variable h
In erase mode, if variable indices are specified, only the specified slices of the list variable will be erased.
``set`` requires all options to come before any other arguments. For example, ``set flags -l`` will have the effect of setting the value of the variable ``flags`` to '-l', not making the variable local.
``set`` requires all options to come before any other arguments. For example, ``set flags -l`` will have the effect of setting the value of the variable :envvar:`flags` to '-l', not making the variable local.
Exit status
-----------
In assignment mode, ``set`` does not modify the exit status, but passes along whatever $status was set, including by command substitutions. This allows capturing the output and exit status of a subcommand, like in ``if set output (command)``.
In assignment mode, ``set`` does not modify the exit status, but passes along whatever :envvar:`status` was set, including by command substitutions. This allows capturing the output and exit status of a subcommand, like in ``if set output (command)``.
In query mode, the exit status is the number of variables that were not found.

56
doc_src/cmds/set_color.rst
View File

@ -6,43 +6,61 @@ set_color - set the terminal color
Synopsis
--------
``set_color`` [*OPTIONS*] *VALUE*
.. synopsis::
set_color [OPTIONS] VALUE
Description
-----------
``set_color`` is used to control the color and styling of text in the terminal. ``VALUE`` describes that styling. ``VALUE`` can be a reserved color name like *red* or a RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277"). A special keyword *normal* resets text formatting to terminal defaults.
``set_color`` is used to control the color and styling of text in the terminal. *VALUE* describes that styling. *VALUE* can be a reserved color name like **red** or a RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277"). A special keyword **normal** resets text formatting to terminal defaults.
Valid colors include:
- *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*
- *brblack*, *brred*, *brgreen*, *bryellow*, *brblue*, *brmagenta*, *brcyan*, *brwhite*
- **black**, **red**, **green**, **yellow**, **blue**, **magenta**, **cyan**, **white**
- **brblack**, **brred**, **brgreen**, **bryellow**, **brblue**, **brmagenta**, **brcyan**, **brwhite**
The *br*- (as in 'bright') forms are full-brightness variants of the 8 standard-brightness colors on many terminals. *brblack* has higher brightness than *black* - towards gray.
The *br*- (as in 'bright') forms are full-brightness variants of the 8 standard-brightness colors on many terminals. **brblack** has higher brightness than **black** - towards gray.
An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. ``fish`` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., ``set_color 2BC`` is the same as ``set_color 22BBCC``. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support ``set_color`` has for it) the actual color may be approximated by a nearby matching reserved color name or ``set_color`` may not have an effect on color.
An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. Fish will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., ``set_color 2BC`` is the same as ``set_color 22BBCC``. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support ``set_color`` has for it) the actual color may be approximated by a nearby matching reserved color name or ``set_color`` may not have an effect on color.
A second color may be given as a desired fallback color. e.g. ``set_color 124212 brblue`` will instruct set_color to use *brblue* if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color.
The following *OPTIONS* are available:
The following options are available:
- ``-b``, ``--background`` *COLOR* sets the background color.
- ``-c``, ``--print-colors`` prints a list of the 16 named colors.
- ``-o``, ``--bold`` sets bold mode.
- ``-d``, ``--dim`` sets dim mode.
- ``-i``, ``--italics`` sets italics mode.
- ``-r``, ``--reverse`` sets reverse mode.
- ``-u``, ``--underline`` sets underlined mode.
**-b** or **--background** *COLOR*
Sets the background color.
Using the *normal* keyword will reset foreground, background, and all formatting back to default.
**-c** or **--print-colors**
Prints a list of the 16 named colors.
**-o** or **--bold**
Sets bold mode.
**-d** or **--dim**
Sets dim mode.
**-i** or **--italics**
Sets italics mode.
**-r** or **--reverse**
Sets reverse mode.
**-u** or **--underline**
Sets underlined mode.
**-h** or **--help**
Displays help about using this command.
Using the **normal** keyword will reset foreground, background, and all formatting back to default.
Notes
-----
1. Using the *normal* keyword will reset both background and foreground colors to whatever is the default for the terminal.
1. Using the **normal** keyword will reset both background and foreground colors to whatever is the default for the terminal.
2. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. Look for a config option.
3. Some terminals use the ``--bold`` escape sequence to switch to a brighter color set rather than increasing the weight of text.
4. ``set_color`` works by printing sequences of characters to *stdout*. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
4. ``set_color`` works by printing sequences of characters to standard output. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
Examples
--------
@ -63,13 +81,13 @@ Fish uses some heuristics to determine what colors a terminal supports to avoid
In particular it will:
- Enable 256 colors if $TERM contains "xterm", except for known exceptions (like MacOS 10.6 Terminal.app)
- Enable 256 colors if :envvar:`TERM` contains "xterm", except for known exceptions (like MacOS 10.6 Terminal.app)
- Enable 24-bit ("true-color") even if the $TERM entry only reports 256 colors. This includes modern xterm, VTE-based terminals like Gnome Terminal, Konsole and iTerm2.
- Detect support for italics, dim, reverse and other modes.
If terminfo reports 256 color support for a terminal, 256 color support will always be enabled.
To force true-color support on or off, set $fish_term24bit to "1" for on and 0 for off - ``set -g fish_term24bit 1``.
To force true-color support on or off, set :envvar:`fish_term24bit`` to "1" for on and 0 for off - ``set -g fish_term24bit 1``.
To debug color palette problems, ``tput colors`` may be useful to see the number of colors in terminfo for a terminal. Fish launched as ``fish -d2`` will include diagnostic messages that indicate the color support mode in use.

15
doc_src/cmds/source.rst
View File

@ -6,25 +6,28 @@ source - evaluate contents of file
Synopsis
--------
| **source** *FILE* [*arguments*...]
| ``somecommand`` | **source**
.. synopsis::
source FILE [ARGUMENTS ...]
SOMECOMMAND | source
Description
-----------
``source`` evaluates the commands of the specified file in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. ``fish < FILE``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the ``$argv`` variable. The ``$argv`` variable will not include the name of the sourced file.
``source`` evaluates the commands of the specified *FILE* in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. ``fish < FILE``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the :envvar:`argv` variable. The :envvar:`argv` variable will not include the name of the sourced file.
fish will search the working directory to resolve relative paths but will not search ``$PATH``.
fish will search the working directory to resolve relative paths but will not search :envvar:`PATH` .
If no file is specified and stdin is not the terminal, or if the file name ``-`` is used, stdin will be read.
The exit status of ``source`` is the exit status of the last job to execute. If something goes wrong while opening or reading the file, ``source`` exits with a non-zero status.
``.`` (a single period) is an alias for the ``source`` command. The use of ``.`` is deprecated in favour of ``source``, and ``.`` will be removed in a future version of fish.
**.** (a single period) is an alias for the ``source`` command. The use of **.** is deprecated in favour of ``source``, and **.** will be removed in a future version of fish.
``source`` creates a new :ref:`local scope<variables-scope>`; ``set --local`` within a sourced block will not affect variables in the enclosing scope.
The **-h** or **--help** option displays help about using this command.
Example
-------
@ -40,4 +43,4 @@ Example
Caveats
-------
In fish versions prior to 2.3.0, the ``$argv`` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.
In fish versions prior to 2.3.0, the :envvar:`argv` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.

102
doc_src/cmds/status.rst
View File

@ -6,72 +6,92 @@ status - query fish runtime information
Synopsis
--------
| **status**
| **status** is-login
| **status** is-interactive
| **status** is-block
| **status** is-breakpoint
| **status** is-command-substitution
| **status** is-no-job-control
| **status** is-full-job-control
| **status** is-interactive-job-control
| **status** current-command
| **status** filename
| **status** basename
| **status** dirname
| **status** fish-path
| **status** function
| **status** line-number
| **status** stack-trace
| **status** job-control *CONTROL_TYPE*
| **status** features
| **status** test-feature *FEATURE*
.. synopsis::
status
status is-login
status is-interactive
status is-block
status is-breakpoint
status is-command-substitution
status is-no-job-control
status is-full-job-control
status is-interactive-job-control
status current-command
status filename
status basename
status dirname
status fish-path
status function
status line-number
status stack-trace
status job-control CONTROL_TYPE
status features
status test-feature FEATURE
Description
-----------
With no arguments, ``status`` displays a summary of the current login and job control status of the shell.
The following operations (sub-commands) are available:
The following operations (subcommands) are available:
- ``is-command-substitution`` returns 0 if fish is currently executing a command substitution. Also ``-c`` or ``--is-command-substitution``.
**is-command-substitution**, **-c** or **--is-command-substitution**
Returns 0 if fish is currently executing a command substitution.
- ``is-block`` returns 0 if fish is currently executing a block of code. Also ``-b`` or ``--is-block``.
**is-block**, **-b** or **--is-block**
Returns 0 if fish is currently executing a block of code.
- ``is-breakpoint`` returns 0 if fish is currently showing a prompt in the context of a ``breakpoint`` command. See also the ``fish_breakpoint_prompt`` function.
**is-breakpoint**
Returns 0 if fish is currently showing a prompt in the context of a :ref:`breakpoint <cmd-breakpoint>` command. See also the :ref:`fish_breakpoint_prompt <cmd-fish_breakpoint_prompt>` function.
- ``is-interactive`` returns 0 if fish is interactive - that is, connected to a keyboard. Also ``-i`` or ``--is-interactive``.
**is-interactive**, **-i** or **--is-interactive**
Returns 0 if fish is interactive - that is, connected to a keyboard.
- ``is-login`` returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. Also ``-l`` or ``--is-login``.
**is-login**, **-l** or **--is-login**
Returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up :envvar:`PATH`.
- ``is-full-job-control`` returns 0 if full job control is enabled. Also ``--is-full-job-control`` (no short flag).
**is-full-job-control** or **--is-full-job-control**
Returns 0 if full job control is enabled.
- ``is-interactive-job-control`` returns 0 if interactive job control is enabled. Also, ``--is-interactive-job-control`` (no short flag).
**is-interactive-job-control** or **--is-interactive-job-control**
Returns 0 if interactive job control is enabled.
- ``is-no-job-control`` returns 0 if no job control is enabled. Also ``--is-no-job-control`` (no short flag).
**is-no-job-control** or **--is-no-job-control**
Returns 0 if no job control is enabled.
- ``current-command`` prints the name of the currently-running function or command, like the deprecated ``_`` variable.
**current-command**
Prints the name of the currently-running function or command, like the deprecated :envvar:`_` variable.
- ``filename`` prints the filename of the currently-running script. Also ``current-filename``, ``-f`` or ``--current-filename``. If the current script was called via a symlink, this will return the symlink. If the current script was received by piping into ``source``, then this will return ``-``.
**filename**, **current-filename**, **-f** or **--current-filename**
Prints the filename of the currently-running script. If the current script was called via a symlink, this will return the symlink. If the current script was received by piping into :ref:`source <cmd-source>`, then this will return ``-``.
- ``basename`` prints just the filename of the running script, without any path-components before.
**basename**
Prints just the filename of the running script, without any path components before.
- ``dirname`` prints just the path to the running script, without the actual filename itself. This can be relative to $PWD (including just "."), depending on how the script was called. This is the same as passing the ``filename`` to ``dirname(3)``. It's useful if you want to use other files in the current script's directory or similar.
**dirname**
Prints just the path to the running script, without the actual filename itself. This can be relative to :envvar:`PWD` (including just "."), depending on how the script was called. This is the same as passing the filename to ``dirname(3)``. It's useful if you want to use other files in the current script's directory or similar.
- ``fish-path`` prints the absolute path to the currently executing instance of fish.
**fish-path**
Prints the absolute path to the currently executing instance of fish.
- ``function`` prints the name of the currently called function if able, when missing displays "Not a
function" (or equivalent translated string). Also ``current-function``.
**function** or **current-function**
Prints the name of the currently called function if able, when missing displays "Not a function" (or equivalent translated string).
- ``line-number`` prints the line number of the currently running script. Also ``current-line-number``, ``-n`` or ``--current-line-number``.
**line-number**, **current-line-number**, **-n** or **--current-line-number**
Prints the line number of the currently running script.
- ``stack-trace`` prints a stack trace of all function calls on the call stack. Also ``print-stack-trace``, ``-t`` or ``--print-stack-trace``.
**stack-trace**, **print-stack-trace**, **-t** or **--print-stack-trace**
Prints a stack trace of all function calls on the call stack.
- ``job-control CONTROL_TYPE`` sets the job control type, which can be ``none``, ``full``, or ``interactive``. Also ``-j CONTROL_TYPE`` or ``--job-control CONTROL_TYPE``.
**job-control**, **-j** or **--job-control** *CONTROL_TYPE*
Sets the job control type to *CONTROL_TYPE*, which can be **none**, **full**, or **interactive**.
- ``features`` lists all available feature flags.
**features**
Lists all available feature flags.
- ``test-feature FEATURE`` returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized.
**test-feature** *FEATURE*
Returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized.
Notes
-----

8
doc_src/cmds/string-collect.rst
View File

@ -6,7 +6,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` collect [**-N** | **--no-trim-newlines**] [*STRING*...]
.. synopsis::
string collect [-N | --no-trim-newlines] [STRING ...]
.. END SYNOPSIS
@ -21,9 +23,9 @@ A command like ``echo (cmd | string collect)`` is mostly equivalent to a quoted
If invoked with multiple arguments instead of input, ``string collect`` preserves each argument separately, where the number of output arguments is equal to the number of arguments given to ``string collect``.
Any trailing newlines on the input are trimmed, just as with ``"$(cmd)"`` substitution. Use ``--no-trim-newlines`` to disable this behavior, which may be useful when running a command such as ``set contents (cat filename | string collect -N)``.
Any trailing newlines on the input are trimmed, just as with ``"$(cmd)"`` substitution. Use **--no-trim-newlines** to disable this behavior, which may be useful when running a command such as ``set contents (cat filename | string collect -N)``.
With ``--allow-empty``, ``string collect`` always prints one (empty) argument. This can be used to prevent an argument from disappearing.
With **--allow-empty**, ``string collect`` always prints one (empty) argument. This can be used to prevent an argument from disappearing.
.. END DESCRIPTION

16
doc_src/cmds/string-escape.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
| ``string`` escape [**-n** | **--no-quoted**] [**--style=**] [*STRING*...]
| ``string`` unescape [**--style=**] [*STRING*...]
.. synopsis::
string escape [-n | --no-quoted] [--style=] [STRING ...]
string unescape [--style=] [STRING ...]
.. END SYNOPSIS
@ -16,15 +18,15 @@ Description
.. BEGIN DESCRIPTION
``string escape`` escapes each STRING in one of three ways. The first is ``--style=script``. This is the default. It alters the string such that it can be passed back to ``eval`` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If ``-n`` or ``--no-quoted`` is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
``string escape`` escapes each *STRING* in one of three ways. The first is **--style=script**. This is the default. It alters the string such that it can be passed back to ``eval`` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If **-n** or **--no-quoted** is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
``--style=var`` ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.
**--style=var** ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.
``--style=url`` ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded.
**--style=url** ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded.
``--style=regex`` escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded.
**--style=regex** escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded.
``string unescape`` performs the inverse of the ``string escape`` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing ``string unescape --style=var (string escape --style=var $str)`` will return the original string. There is no support for unescaping ``--style=regex``.
``string unescape`` performs the inverse of the ``string escape`` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing ``string unescape --style=var (string escape --style=var $str)`` will return the original string. There is no support for unescaping **--style=regex**.
.. END DESCRIPTION

10
doc_src/cmds/string-join.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
| ``string`` join [**-q** | **--quiet**] SEP [*STRING*...]
| ``string`` join0 [**-q** | **--quiet**] [*STRING*...]
.. synopsis::
string join [-q | --quiet] SEP [STRING ...]
string join0 [-q | --quiet] [STRING ...]
.. END SYNOPSIS
@ -16,9 +18,9 @@ Description
.. BEGIN DESCRIPTION
``string join`` joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
``string join`` joins its *STRING* arguments into a single string separated by *SEP*, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
``string join0`` joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise.
``string join0`` joins its *STRING* arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise.
Because Unix uses NUL as the string terminator, passing the output of ``string join0`` as an *argument* to a command (via a :ref:`command substitution <expand-command-substitution>`) won't actually work. Fish will pass the correct bytes along, but the command won't be able to tell where the argument ends. This is a limitation of Unix' argument passing.

8
doc_src/cmds/string-length.rst
View File

@ -8,7 +8,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` length [**-q** | **--quiet**] [*STRING*...]
.. synopsis::
string length [-q | --quiet] [-V | --visible] [STRING ...]
.. END SYNOPSIS
@ -17,9 +19,9 @@ Description
.. BEGIN DESCRIPTION
``string length`` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
``string length`` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty *STRING* was given, or 1 otherwise.
With ``-V`` or ``--visible``, it uses the visible width of the arguments. That means it will discount escape sequences fish knows about, account for $fish_emoji_width and $fish_ambiguous_width. It will also count each line (separated by ``\n``) on its own, and with a carriage return (``\r``) count only the widest stretch on a line. The intent is to measure the number of columns the STRING would occupy in the current terminal.
With **-V** or **--visible**, it uses the visible width of the arguments. That means it will discount escape sequences fish knows about, account for $fish_emoji_width and $fish_ambiguous_width. It will also count each line (separated by ``\n``) on its own, and with a carriage return (``\r``) count only the widest stretch on a line. The intent is to measure the number of columns the *STRING* would occupy in the current terminal.
.. END DESCRIPTION

6
doc_src/cmds/string-lower.rst
View File

@ -6,7 +6,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` lower [**-q** | **--quiet**] [*STRING*...]
.. synopsis::
string lower [-q | --quiet] [STRING ...]
.. END SYNOPSIS
@ -15,7 +17,7 @@ Description
.. BEGIN DESCRIPTION
``string lower`` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the ``-q`` flag you can readily test whether a string is already lowercase.
``string lower`` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the **-q** flag you can readily test whether a string is already lowercase.
.. END DESCRIPTION

24
doc_src/cmds/string-match.rst
View File

@ -6,9 +6,11 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` match [**-a** | **--all**] [**-e** | **--entire**] [**-i** | **--ignore-case**]
\ \ [**-r** | **--regex**] [**-n** | **--index**] [**-q** | **--quiet**] [**-v** | **--invert**]
\ \ *PATTERN* [*STRING*...]
.. synopsis::
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING ...]
.. END SYNOPSIS
@ -17,21 +19,21 @@ Description
.. BEGIN DESCRIPTION
``string match`` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless ``-a`` or ``--all`` is given, in which case all matches are reported.
``string match`` tests each *STRING* against *PATTERN* and prints matching substrings. Only the first match for each *STRING* is reported unless **-a** or **--all** is given, in which case all matches are reported.
If you specify the ``-e`` or ``--entire`` then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to ``grep`` without the ``-o`` flag). You can, obviously, achieve the same result by prepending and appending ``*`` or ``.*`` depending on whether or not you have specified the ``--regex`` flag. The ``--entire`` flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the ``string match`` clearer. Without ``--entire`` and ``--regex``, a PATTERN will need to match the entire STRING before it will be reported.
If you specify the **-e** or **--entire** then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to ``grep`` without the **-o** flag). You can, obviously, achieve the same result by prepending and appending **\*** or **.*** depending on whether or not you have specified the **--regex** flag. The **--entire** flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the ``string match`` clearer. Without **--entire** and **--regex**, a *PATTERN* will need to match the entire *STRING* before it will be reported.
Matching can be made case-insensitive with ``--ignore-case`` or ``-i``.
Matching can be made case-insensitive with **--ignore-case** or **-i**.
If ``--groups-only`` or ``-g`` is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with ``--entire`` and ``--invert``, and requires ``--regex``. It is useful as a simple cutting tool instead of ``string replace``, so you can simply choose "this part" of a string.
If **--groups-only** or **-g** is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with **--entire** and **--invert**, and requires **--regex**. It is useful as a simple cutting tool instead of ``string replace``, so you can simply choose "this part" of a string.
If ``--index`` or ``-n`` is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING.
If **--index** or **-n** is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire *STRING* argument. A glob pattern is only considered a valid match if it matches the entire *STRING*.
If ``--regex`` or ``-r`` is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the STRING will be reported, unless ``--entire`` is given.
If **--regex** or **-r** is given, *PATTERN* is interpreted as a Perl-compatible regular expression, which does not have to match the entire *STRING*. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the *STRING* will be reported, unless **--entire** is given.
When matching via regular expressions, ``string match`` automatically sets variables for all named capturing groups (``(?<name>expression)``). It will create a variable with the name of the group, in the default scope, for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like ``set var ""``). If it did not match, the variable will be set to nothing (like ``set var``). When ``--regex`` is used with ``--all``, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.
When matching via regular expressions, ``string match`` automatically sets variables for all named capturing groups (``(?<name>expression)``). It will create a variable with the name of the group, in the default scope, for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like ``set var ""``). If it did not match, the variable will be set to nothing (like ``set var``). When **--regex** is used with **--all**, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.
If ``--invert`` or ``-v`` is used the selected lines will be only those which do not match the given glob pattern or regular expression.
If **--invert** or **-v** is used the selected lines will be only those which do not match the given glob pattern or regular expression.
Exit status: 0 if at least one match was found, or 1 otherwise.

Some files were not shown because too many files have changed in this diff Show More