fish-shell/doc_src/cmds/commandline.rst

.. _cmd-commandline:

commandline - set or get the current command line buffer
========================================================

Synopsis
--------

::

    commandline [OPTIONS] [CMD]

Description
-----------

``commandline`` can be used to set or get the current contents of the command line buffer.

With no parameters, ``commandline`` returns the current value of the command line.

With ``CMD`` specified, the command line buffer is erased and replaced with the contents of ``CMD``.

The following options are available:

- ``-C`` or ``--cursor`` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position. If one of the options ``-j``, ``-p`` or ``-t`` is given, the position is relative to the respective substring instead of the entire command line buffer.

- ``-f`` or ``--function`` causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are. This option cannot be combined with any other option. See :ref:`bind <cmd-bind>` for a list of input functions.

The following options change the way ``commandline`` updates the command line buffer:

- ``-a`` or ``--append`` do not remove the current commandline, append the specified string at the end of it

- ``-i`` or ``--insert`` do not remove the current commandline, insert the specified string at the current cursor position

- ``-r`` or ``--replace`` remove the current commandline and replace it with the specified string (default)

The following options change what part of the commandline is printed or updated:

- ``-b`` or ``--current-buffer`` select the entire commandline, not including any displayed autosuggestion (default)

- ``-j`` or ``--current-job`` select the current job - a `job` here is one pipeline. It stops at logical operators or terminators (``;``, ``&`` or newlines).

- ``-p`` or ``--current-process`` select the current process - a `process` here is one simple command. It stops at logical operators, terminators or pipes.

- ``-s`` or ``--current-selection`` selects the current selection

- ``-t`` or ``--current-token`` select the current token

The following options change the way ``commandline`` prints the current commandline buffer:

- ``-c`` or ``--cut-at-cursor`` only print selection up until the current cursor position

- ``-o`` or ``--tokenize`` tokenize the selection and print one string-type token per line

If ``commandline`` is called during a call to complete a given string using ``complete -C STRING``, ``commandline`` will consider the specified string to be the current contents of the command line.

The following options output metadata about the commandline state:

- ``-L`` or ``--line`` print the line that the cursor is on, with the topmost line starting at 1

- ``-S`` or ``--search-mode`` evaluates to true if the commandline is performing a history search

- ``-P`` or ``--paging-mode`` evaluates to true if the commandline is showing pager contents, such as tab completions

- ``--paging-full-mode`` evaluates to true if the commandline is showing pager contents, such as tab completions and all lines are shown (no "<n> more rows" message)

- ``--is-valid`` returns true when the commandline is syntactically valid and complete. If it is, it would be executed when the ``execute`` bind function is called. If the commandline is incomplete, it returns 2, if it is erroneus, it returns 1.

Example
-------

``commandline -j $history[3]`` replaces the job under the cursor with the third item from the command line history.

If the commandline contains


::

    >_ echo $flounder >&2 | less; and echo $catfish


(with the cursor on the "o" of "flounder")

The ``echo $flounder >&`` is the first process, ``less`` the second and ``and echo $catfish`` the third.

``echo $flounder >&2 | less`` is the first job, ``and echo $catfish`` the second.

``$flounder`` is the current token.

More examples:


::

    >_ commandline -t
    $flounder
    >_ commandline -ct
    $fl
    >_ commandline -b # or just commandline
    echo $flounder >&2 | less; and echo $catfish
    >_ commandline -p
    echo $flounder >&2
    >_ commandline -j
    echo $flounder >&2 | less
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 09:05:09 +00:00			`.. _cmd-commandline:`

Switch command docs from \section to reStructuredText 2018-12-17 01:39:33 +00:00			`commandline - set or get the current command line buffer`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`========================================================`
Switch command docs from \section to reStructuredText 2018-12-17 01:39:33 +00:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 01:58:24 +00:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 09:59:04 +00:00			`::`
Migrate the 'synopsis' sections to .rst format 2018-12-18 01:58:24 +00:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 09:59:04 +00:00			`commandline [OPTIONS] [CMD]`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Convert \\subsection sections into rst format 2018-12-19 02:44:30 +00:00			`Description`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			``commandline`` can be used to set or get the current contents of the command line buffer.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			With no parameters, ``commandline`` returns the current value of the command line.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			With ``CMD`` specified, the command line buffer is erased and replaced with the contents of ``CMD``.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`The following options are available:`

commandline: allow to get/set cursor position relative to token/process/job With a command line like a \| b <cursor> \| c "commandline -C 0 --current-process" will place the cursor just left of "b". 2021-06-23 06:26:21 +00:00			- ``-C`` or ``--cursor`` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position. If one of the options ``-j``, ``-p`` or ``-t`` is given, the position is relative to the respective substring instead of the entire command line buffer.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: Reword `commandline -f` We don't refer to "readline functions" anywhere else, and "injecting" them "into the reader" is an overly jargony way of expressing it that only makes sense to someone familiar with the internals. And even then the term "readline" is already taken by the "readline" library, used by bash et al, but not by us. So we pick the term "input functions", like we did in bind. See https://stackoverflow.com/questions/55542839/what-does-commandline-f-repaint-in-fish-shell/55543411#55543411. [ci skip] 2019-04-06 18:37:14 +00:00			- ``-f`` or ``--function`` causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are. This option cannot be combined with any other option. See :ref:`bind <cmd-bind>` for a list of input functions.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			The following options change the way ``commandline`` updates the command line buffer:
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-a`` or ``--append`` do not remove the current commandline, append the specified string at the end of it
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-i`` or ``--insert`` do not remove the current commandline, insert the specified string at the current cursor position
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-r`` or ``--replace`` remove the current commandline and replace it with the specified string (default)
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`The following options change what part of the commandline is printed or updated:`

Correct the docs for commandline --current-buffer commandline current-buffer was incorrectly documented as returning the autosuggestion. Clarify that it does not. 2021-05-26 00:14:19 +00:00			- ``-b`` or ``--current-buffer`` select the entire commandline, not including any displayed autosuggestion (default)
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: use monospace for inline code snippets more consistently 2020-10-26 18:19:05 +00:00			- ``-j`` or ``--current-job`` select the current job - a `job` here is one pipeline. It stops at logical operators or terminators (``;``, ``&`` or newlines).
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs: Clarify commandline parts This was quite confusing as it was basically just documented with a teensy example later on. See #6583. [ci skip] 2020-02-11 19:42:12 +00:00			- ``-p`` or ``--current-process`` select the current process - a `process` here is one simple command. It stops at logical operators, terminators or pipes.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-s`` or ``--current-selection`` selects the current selection
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-t`` or ``--current-token`` select the current token
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			The following options change the way ``commandline`` prints the current commandline buffer:
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-c`` or ``--cut-at-cursor`` only print selection up until the current cursor position
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-o`` or ``--tokenize`` tokenize the selection and print one string-type token per line
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			If ``commandline`` is called during a call to complete a given string using ``complete -C STRING``, ``commandline`` will consider the specified string to be the current contents of the command line.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`The following options output metadata about the commandline state:`

Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-L`` or ``--line`` print the line that the cursor is on, with the topmost line starting at 1
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-S`` or ``--search-mode`` evaluates to true if the commandline is performing a history search
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-P`` or ``--paging-mode`` evaluates to true if the commandline is showing pager contents, such as tab completions
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
builtin commandline: add option to determine if pager is fully disclosed Use the remaining_to_disclose count to determine if all completions are shown (allows consistent behavior between short and long completion lists). Closes #8485 2021-11-24 23:03:20 +00:00			- ``--paging-full-mode`` evaluates to true if the commandline is showing pager contents, such as tab completions and all lines are shown (no "<n> more rows" message)

commandline: Add --is-valid option (#8142) * commandline: Add --is-valid option to query whether it's syntactically complete This means querying when the commandline is in a state that it could be executed. Because our `execute` bind function also inserts a newline if it isn't. One case that's not handled right now: `execute` also expands abbreviations, those can technically make the commandline invalid again. Unfortunately we have no real way to check without doing the replacement. Also since abbreviations are only available in command position when you _execute_ them the commandline will most likely be valid. This is enough to make transient prompts work: ```fish function reset-transient --on-event fish_postexec set -g TRANSIENT 0 end function maybe_execute if commandline --is-valid set -g TRANSIENT 1 commandline -f repaint else set -g TRANSIENT 0 end commandline -f execute end bind \r maybe_execute ``` and then in `fish_prompt` react to $TRANSIENT being set to 1. 2021-08-14 09:29:22 +00:00			- ``--is-valid`` returns true when the commandline is syntactically valid and complete. If it is, it would be executed when the ``execute`` bind function is called. If the commandline is incomplete, it returns 2, if it is erroneus, it returns 1.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Convert \\subsection sections into rst format 2018-12-19 02:44:30 +00:00			`Example`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			``commandline -j $history[3]`` replaces the job under the cursor with the third item from the command line history.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`If the commandline contains`
Switch \fish sections to rst format 2018-12-19 03:14:04 +00:00

			`::`

docs: Clarify commandline parts This was quite confusing as it was basically just documented with a teensy example later on. See #6583. [ci skip] 2020-02-11 19:42:12 +00:00			`>_ echo $flounder >&2 \| less; and echo $catfish`
Switch \fish sections to rst format 2018-12-19 03:14:04 +00:00
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`(with the cursor on the "o" of "flounder")`

docs: use monospace for inline code snippets more consistently 2020-10-26 18:19:05 +00:00			The ``echo $flounder >&`` is the first process, ``less`` the second and ``and echo $catfish`` the third.
docs: Clarify commandline parts This was quite confusing as it was basically just documented with a teensy example later on. See #6583. [ci skip] 2020-02-11 19:42:12 +00:00
docs: use monospace for inline code snippets more consistently 2020-10-26 18:19:05 +00:00			``echo $flounder >&2 \| less`` is the first job, ``and echo $catfish`` the second.
docs: Clarify commandline parts This was quite confusing as it was basically just documented with a teensy example later on. See #6583. [ci skip] 2020-02-11 19:42:12 +00:00
docs: use monospace for inline code snippets more consistently 2020-10-26 18:19:05 +00:00			``$flounder`` is the current token.
docs: Clarify commandline parts This was quite confusing as it was basically just documented with a teensy example later on. See #6583. [ci skip] 2020-02-11 19:42:12 +00:00
docs: Remove extra colon to fix formatting 2020-04-17 03:01:04 +00:00			`More examples:`
Switch \fish sections to rst format 2018-12-19 03:14:04 +00:00

			`::`

			`>_ commandline -t`
			`$flounder`
			`>_ commandline -ct`
			`$fl`
			`>_ commandline -b # or just commandline`
			`echo $flounder >&2 \| less; and echo $catfish`
			`>_ commandline -p`
			`echo $flounder >&2`
			`>_ commandline -j`
			`echo $flounder >&2 \| less`