github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-23 14:40:37 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Revise through "Input/Output Redirection" section

Browse Source
This commit is contained in:
Matthew Dutson 2020-12-27 17:49:52 -07:00
parent f3fee832d4
commit 0136db0a22
1 changed files with 63 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
doc_src/index.rst
View File

@ -106,7 +106,7 @@ Shells like fish are used by giving them commands. Every fish command follows th
echo hello world
This calls the :ref:`echo <cmd-echo>` command. ``echo`` writes its arguments to the screen. In the example above, the output is 'hello world'. Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax.
This calls the :ref:`echo <cmd-echo>` command. ``echo`` writes its arguments to the screen. In the example above, the output is ``hello world``. Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax.
To learn more about the ``echo`` command, read its manual page by typing ``man echo``. ``man`` is a command for displaying a manual page on a given topic. It takes the name of the manual page to display as an argument. There are manual pages for almost every command. There are also manual pages for many other things, such as system libraries and important files.
@ -182,104 +182,98 @@ searches for lines ending in ``enabled)`` in ``foo.txt`` (the ``$`` is special t
.. _escapes:
Escaping characters
Escaping Characters
-------------------
Some characters can not be written directly on the command line. For these characters, so called escape sequences are provided. These are:
Some characters cannot be written directly on the command line. For these characters, so-called escape sequences are provided. These are:
- ``\a`` represents the alert character
- ``\b`` represents the backspace character
- ``\e`` represents the escape character
- ``\f`` represents the form feed character
- ``\n`` represents a newline character
- ``\r`` represents the carriage return character
- ``\t`` represents the tab character
- ``\v`` represents the vertical tab character
- :code:`\ `  escapes the space character
- ``\$`` escapes the dollar character
- ``\\`` escapes the backslash character
- ``\*`` escapes the star character
- ``\?`` escapes the question mark character (this is not necessary if the ``qmark-noglob`` :ref:`feature flag<featureflags>` is enabled)
- ``\~`` escapes the tilde character
- ``\#`` escapes the hash character
- ``\(`` escapes the left parenthesis character
- ``\)`` escapes the right parenthesis character
- ``\{`` escapes the left curly bracket character
- ``\}`` escapes the right curly bracket character
- ``\[`` escapes the left bracket character
- ``\]`` escapes the right bracket character
- ``\<`` escapes the less than character
- ``\>`` escapes the more than character
- ``\^`` escapes the circumflex character
- ``\&`` escapes the ampersand character
- ``\|`` escapes the vertical bar character
- ``\;`` escapes the semicolon character
- ``\"`` escapes the quote character
- ``\'`` escapes the apostrophe character
- ``\a`` represents the alert character.
- ``\e`` represents the escape character.
- ``\f`` represents the form feed character.
- ``\n`` represents a newline character.
- ``\r`` represents the carriage return character.
- ``\t`` represents the tab character.
- ``\v`` represents the vertical tab character.
- ``\xHH``, where ``HH`` is a hexadecimal number, represents the ASCII character with the specified value. For example, ``\x9`` is the tab character.
- ``\XHH``, where ``HH`` is a hexadecimal number, represents a byte of data with the specified value. If you are using a multibyte encoding, this can be used to enter invalid strings. Only use this if you know what you are doing.
- ``\ooo``, where ``ooo`` is an octal number, represents the ASCII character with the specified value. For example, ``\011`` is the tab character.
- ``\uXXXX``, where ``XXXX`` is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, ``\u9`` is the tab character.
- ``\UXXXXXXXX``, where ``XXXXXXXX`` is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, ``\U9`` is the tab character.
- ``\cX``, where ``X`` is a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example, ``\ci`` is the tab character
- ``\xHH``, where *HH* is a hexadecimal number, represents the ascii character with the specified value. For example, ``\x9`` is the tab character.
Some characters have special meaning to the shell. For example, an apostrophe ``'`` disables expansion (see :ref:`Quotes<quotes>`). To tell the shell to treat these characters literally, escape them with a backslash. For example, the command::
- ``\XHH``, where *HH* is a hexadecimal number, represents a byte of data with the specified value. If you are using a multibyte encoding, this can be used to enter invalid strings. Only use this if you know what you are doing.
echo \'hello world\'
- ``\ooo``, where *ooo* is an octal number, represents the ascii character with the specified value. For example, ``\011`` is the tab character.
outputs ``'hello world'`` (including the apostrophes), while the command::
- ``\uXXXX``, where *XXXX* is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, ``\u9`` is the tab character.
echo 'hello world'
- ``\UXXXXXXXX``, where *XXXXXXXX* is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, ``\U9`` is the tab character.
outputs ``hello world`` (without the apostrophes). In the former case the shell treats the apostrophes as literal ``'`` characters, while in the latter case it treats them as special expansion modifiers.
- ``\cX``, where *X* is a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example, ``\ci`` is the tab character
The special characters and their escape sequences are:
- :code:`\ ` (backslash space) escapes the space character. This keeps the shell from splitting arguments on the escaped space.
- ``\$`` escapes the dollar character.
- ``\\`` escapes the backslash character.
- ``\*`` escapes the star character.
- ``\?`` escapes the question mark character (this is not necessary if the ``qmark-noglob`` :ref:`feature flag<featureflags>` is enabled).
- ``\~`` escapes the tilde character.
- ``\#`` escapes the hash character.
- ``\(`` escapes the left parenthesis character.
- ``\)`` escapes the right parenthesis character.
- ``\{`` escapes the left curly bracket character.
- ``\}`` escapes the right curly bracket character.
- ``\[`` escapes the left bracket character.
- ``\]`` escapes the right bracket character.
- ``\<`` escapes the less than character.
- ``\>`` escapes the more than character.
- ``\^`` escapes the circumflex character.
- ``\&`` escapes the ampersand character.
- ``\|`` escapes the vertical bar character.
- ``\;`` escapes the semicolon character.
- ``\"`` escapes the quote character.
- ``\'`` escapes the apostrophe character.
.. _redirects:
Input/Output Redirection
-----------------------------
Most programs use three input/output [#]_ streams:
Most programs use three input/output (I/O) streams:
- Standard input ("stdin"), FD 0, for reading, defaults to reading from the keyboard.
- Standard input (stdin) for reading. Defaults to reading from the keyboard.
- Standard output (stdout) for writing output. Defaults to writing to the screen.
- Standard error (stderr) for writing errors and warnings. Defaults to writing to the screen.
- Standard output ("stdout"), FD 1, for writing, defaults to writing to the screen.
Each stream has a number called the file descriptor (FD): 0 for stdin, 1 for stdout, and 2 for stderr.
- Standard error ("stderr"), FD 2, for writing errors and warnings, defaults to writing to the screen.
The destination of a stream can be changed using something called *redirection*. For example, ``echo hello > output.txt``, redirects the standard output of the ``echo`` command to a text file.
They are also represented by numbers: 0 for input, 1 for output, 2 for error. This number is called "file descriptor" or "FD".
The destination of a stream can be changed by something known as *redirection*.
An example of a redirection is ``echo hello > output.txt``, which directs the output of the echo command to the file output.txt.
- To read standard input from a file, write ``<SOURCE_FILE``
- To write standard output to a file, write ``>DESTINATION``
- To write standard error to a file, write ``2>DESTINATION`` [#]_
- To append standard output to a file, write ``>>DESTINATION_FILE``
- To append standard error to a file, write ``2>>DESTINATION_FILE``
- To not overwrite ("clobber") an existing file, write ``>?DESTINATION`` or ``2>?DESTINATION`` (this is also known as the "noclobber" redirection)
- To read standard input from a file, use ``<SOURCE_FILE``.
- To write standard output to a file, use ``>DESTINATION``.
- To write standard error to a file, use ``2>DESTINATION``. [#]_
- To append standard output to a file, use ``>>DESTINATION_FILE``.
- To append standard error to a file, use ``2>>DESTINATION_FILE``.
- To not overwrite ("clobber") an existing file, use ``>?DESTINATION`` or ``2>?DESTINATION``. This is known as the "noclobber" redirection.
``DESTINATION`` can be one of the following:
- A filename. The output will be written to the specified file.
- An ampersand (``&``) followed by the number of another file descriptor. The output will be written to that file descriptor instead.
- An ampersand (``&``) followed by the number of another file descriptor. The output will be written to the destination descriptor.
- An ampersand followed by a minus sign (``&-``). The file descriptor will be closed.
As a convenience, the redirection ``&>`` can be used to direct both stdout and stderr to the same file.
As a convenience, the redirection ``&>`` can be used to direct both stdout and stderr to the same destination. For example, ``echo hello &> all_output.txt`` redirects both stdout and stderr to the file ``all_output.txt``. This is equivalent to ``echo hello > all_output.txt 2>&1``.
Example:
Any arbitrary file descriptor can used in a redirection by prefixing the redirection with the FD number.
To redirect both standard output and standard error to the file 'all_output.txt', you can write ``echo Hello &> all_output.txt``, which is a convenience for ``echo Hello > all_output.txt 2>&1``.
- To redirect the input of descriptor N, use ``N<DESTINATION``.
- To redirect the output of descriptor N, use ``N>DESTINATION``.
- To append the output of descriptor N to a file, use ``N>>DESTINATION_FILE``.
Any file descriptor can be redirected in an arbitrary way by prefixing the redirection with the file descriptor.
For example, ``echo hello 2> output.stderr`` writes the standard error (file descriptor 2) to ``output.stderr``.
- To redirect input of FD N, write ``N<DESTINATION``
- To redirect output of FD N, write ``N>DESTINATION``
- To append the output of FD N to a file, write ``N>>DESTINATION_FILE``
Example: ``echo Hello 2>output.stderr`` writes the standard error (file descriptor 2) of the target program to ``output.stderr``.
.. [#] Also shortened as "I/O" or "IO".
.. [#] Previous versions of fish also allowed spelling this as ``^DESTINATION``, but that made another character special so it was deprecated and will be removed in future. See :ref:`feature flags<featureflags>`.
.. [#] Previous versions of fish also allowed specifying this as ``^DESTINATION``, but that made another character special so it was deprecated and will be removed in the future. See :ref:`feature flags<featureflags>`.
.. _pipes: