mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-27 05:13:10 +00:00
Document new abbreviation features
This commit is contained in:
ridiculousfish
parent
c51a1f1f60
commit
22bd43f9d5
1 changed files with 90 additions and 44 deletions
|
|
@ -8,12 +8,14 @@ Synopsis
|
|||
|
||||
.. synopsis::
|
||||
|
||||
abbr --add [SCOPE] WORD EXPANSION
|
||||
abbr --erase WORD ...
|
||||
abbr --rename [SCOPE] OLD_WORD NEW_WORD
|
||||
abbr --add NAME [--quiet] [--position command | anywhere] [--regex PATTERN]
|
||||
[--set-cursor SENTINEL] [--trigger-on entry | exec]...
|
||||
[-f | --function] EXPANSION
|
||||
abbr --erase NAME ...
|
||||
abbr --rename OLD_WORD NEW_WORD
|
||||
abbr --show
|
||||
abbr --list
|
||||
abbr --query WORD ...
|
||||
abbr --query NAME ...
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
|
@ -23,80 +25,124 @@ Description
|
|||
For example, a frequently-run command like ``git checkout`` can be abbreviated to ``gco``.
|
||||
After entering ``gco`` and pressing :kbd:`Space` or :kbd:`Enter`, the full text ``git checkout`` will appear in the command line.
|
||||
|
||||
Options
|
||||
-------
|
||||
An abbreviation may match a literal word, or it may match a pattern given by a regular expression. When an abbreviation matches a word, that word is replaced by new text, called its *expansion*. This expansion may be a fixed new phrase, or it can be dynamically created via a fish function.
|
||||
|
||||
The following options are available:
|
||||
Abbreviations may expand either after their word is entered, or if they are executed with the enter key. The ``--trigger-on`` option allows limiting expansion to only entering, or only executing.
|
||||
|
||||
**-a** *WORD* *EXPANSION* or **--add** *WORD* *EXPANSION*
|
||||
Adds a new abbreviation, causing *WORD* to be expanded to *EXPANSION*
|
||||
By default abbreviations print the new command line after being entered. The ``--quiet`` option causes abbreviations to expand silently.
|
||||
|
||||
**-r** *OLD_WORD* *NEW_WORD* or **--rename** *OLD_WORD* *NEW_WORD*
|
||||
Renames an abbreviation, from *OLD_WORD* to *NEW_WORD*
|
||||
Combining these features, it is possible to create custom syntaxes, where a regular expression recognizes matching tokens, and the expansion function interprets them. See the `Examples`_ section.
|
||||
|
||||
**-s** or **--show**
|
||||
Show all abbreviations in a manner suitable for import and export
|
||||
Abbreviations may be added to :ref:`config.fish <configuration>`. Abbreviations are only expanded for typed-in commands, not in scripts.
|
||||
|
||||
**-l** or **--list**
|
||||
Lists all abbreviated words
|
||||
|
||||
**-e** *WORD* or **--erase** *WORD* ...
|
||||
Erase the given abbreviations
|
||||
"add" subcommand
|
||||
--------------------
|
||||
|
||||
**-q** or **--query**
|
||||
Return 0 (true) if one of the *WORD* is an abbreviation.
|
||||
.. synopsis::
|
||||
|
||||
**-h** or **--help**
|
||||
Displays help about using this command.
|
||||
abbr [-a | --add] NAME [--quiet] [--position command | anywhere] [--regex PATTERN]
|
||||
[--set-cursor SENTINEL] [--trigger-on entry | exec]...
|
||||
[-f | --function] EXPANSION
|
||||
|
||||
In addition, when adding or renaming abbreviations, one of the following **SCOPE** options can be used:
|
||||
``abbr --add`` creates a new abbreviation. With no other options, the string **NAME** is replaced by **EXPANSION**.
|
||||
|
||||
**-g** or **--global**
|
||||
Use a global variable
|
||||
With **--quiet**, the expansion occurs without printing the new command line. The original, unexpanded command is saved in history. Without **--quiet** the new command line is shown with the abbreviation expanded. If a **--quiet** abbreviation results in an incomplete command or syntax error, the command line is printed as if it were not quiet.
|
||||
|
||||
**-U** or **--universal**
|
||||
Use a universal variable (default)
|
||||
With **--position command**, the abbreviation will only expand when it is positioned as a command, not as an argument to another command. With **--position anywhere** the abbreviation may expand anywhere in the command line. The default is **command**.
|
||||
|
||||
With **--regex**, the abbreviation matches using the regular expression given by **PATTERN**, instead of the literal **NAME**. The pattern is interpreted using PCRE2 syntax and must match the entire token. If multiple abbreviations match the same token, the last abbreviation added is used.
|
||||
|
||||
With **--set-cursor**, the cursor is moved to the first occurrence of **SENTINEL** in the expansion. That **SENTINEL** value is erased.
|
||||
|
||||
With **--trigger-on entry**, the abbreviation will expand after its word or pattern is ended, for example by typing a space. With **--trigger-on exec**, the abbreviation will expand when the enter key is pressed. These options may be combined, but are incompatible with **--quiet**. The default is both **entry** and **exec**.
|
||||
|
||||
With **-f** or **--function**, **EXPANSION** is treated as the name of a fish function instead of a literal replacement. When the abbreviation matches, the function will be called with the matching token as an argument. If the function's exit status is 0 (success), the token will be replaced by the function's output; otherwise the token will be left unchanged.
|
||||
|
||||
See the "Internals" section for more on them.
|
||||
|
||||
Examples
|
||||
--------
|
||||
########
|
||||
|
||||
::
|
||||
|
||||
abbr -a gco git checkout
|
||||
abbr --add gco git checkout
|
||||
|
||||
Add a new abbreviation where ``gco`` will be replaced with ``git checkout``.
|
||||
This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish).
|
||||
|
||||
::
|
||||
|
||||
abbr -a l less
|
||||
abbr -a --position anywhere -- -C --color
|
||||
|
||||
Add a new abbreviation where ``l`` will be replaced with ``less`` universal to all shells.
|
||||
Add a new abbreviation where ``-C`` will be replaced with ``--color``. The ``--`` allows ``-C`` to be treated as the name of the abbreviation, instead of an option.
|
||||
|
||||
::
|
||||
|
||||
abbr -r gco gch
|
||||
abbr -a L --position anywhere --set-cursor ! "! | less"
|
||||
|
||||
Add a new abbreviation where ``L`` will be replaced with ``| less``, placing the cursor before the pipe.
|
||||
|
||||
Renames an existing abbreviation from ``gco`` to ``gch``.
|
||||
|
||||
::
|
||||
|
||||
abbr -e gco
|
||||
function last_history_item
|
||||
echo $history[1]
|
||||
end
|
||||
abbr -a !! --position anywhere --function last_history_item --quiet
|
||||
|
||||
Erase the ``gco`` abbreviation.
|
||||
This first creates a function ``last_history_item`` which outputs the last entered command. It then adds an abbreviation which replaces ``!!`` with the result of calling this function. The ``--quiet`` option causes the expansion to happen without visibly modifying the text. Taken together, this implements the ``!!`` history expansion feature of bash.
|
||||
|
||||
::
|
||||
|
||||
ssh another_host abbr -s | source
|
||||
function vim_edit
|
||||
echo vim $argv
|
||||
end
|
||||
abbr -a vim_edit_texts --position command --regex ".+\.txt" --function vim_edit
|
||||
|
||||
Import the abbreviations defined on another_host over SSH.
|
||||
This first creates a function ``vim_edit`` which prepends ``vim`` before its argument. It then adds an abbreviation which matches commands ending in ``.txt``, and replaces the command with the result of calling this function. This allows text files to be "executed" as a command to open them in vim, similar to the "suffix alias" feature in zsh.
|
||||
|
||||
Internals
|
||||
---------
|
||||
Each abbreviation is stored in its own global or universal variable.
|
||||
The name consists of the prefix ``_fish_abbr_`` followed by the WORD after being transformed by ``string escape style=var``.
|
||||
The WORD cannot contain a space but all other characters are legal.
|
||||
::
|
||||
|
||||
abbr 4DIRS --trigger-on entry --set-cursor ! "$(string join \n -- 'for dir in */' 'cd $dir' '!' 'cd ..' 'end')"
|
||||
|
||||
This creates an abbreviation "4DIRS" which expands to a multi-line loop "template." The template enters each directory and then leaves it. The cursor is positioned ready to enter the command to run in each directory, at the location of the ``!``, which is itself erased.
|
||||
|
||||
Other subcommands
|
||||
--------------------
|
||||
|
||||
|
||||
::
|
||||
|
||||
abbr [-r | --rename] OLD_NAME NEW_NAME
|
||||
|
||||
Renames an abbreviation, from *OLD_NAME* to *NEW_NAME*
|
||||
|
||||
::
|
||||
|
||||
abbr [-s | --show]
|
||||
|
||||
Show all abbreviations in a manner suitable for import and export
|
||||
|
||||
::
|
||||
|
||||
abbr [-l | --list]
|
||||
|
||||
Prints the names of all abbreviation
|
||||
|
||||
::
|
||||
|
||||
abbr [-e | --erase] NAME
|
||||
|
||||
Erases the abbreviation with the given name
|
||||
|
||||
::
|
||||
|
||||
abbr -q or --query [NAME...]
|
||||
|
||||
Return 0 (true) if one of the *NAME* is an abbreviation.
|
||||
|
||||
::
|
||||
|
||||
abbr -h or --help
|
||||
|
||||
Displays help for the `abbr` command.
|
||||
|
||||
Abbreviations created with the **--universal** flag will be visible to other fish sessions, whilst **--global** will be limited to the current session.
|
||||
|
|
|
|||
Loading…
Reference in a new issue