mirror of
https://github.com/fish-shell/fish-shell.git
synced 2024-11-27 03:13:37 +08:00
c0d1e41313
Recent synopsis changes move from literal code blocks to [RST line blocks]. This does not translate well to HTML: it's not rendered in monospace, so aligment is lost. Additionally, we don't get syntax highlighting in HTML, which adds differences to our code samples which are highlighted. We hard-wrap synopsis lines (like code blocks). To align continuation lines in manpages we need [backslashes in weird places]. Combined with the **, *, and `` markup, it's a bit hard to get the alignment right. Fix these by moving synopsis sources back to code blocks and compute HTML syntax highlighting and manpage markup with a custom Sphinx extension. The new Pygments lexer can tokenize a synopsis and assign the various highlighting roles, which closely matches fish's syntax highlighing: - command/keyword (dark blue) - parameter (light blue) - operator like and/or/not/&&/|| (cyan) - grammar metacharacter (black) For manpage output, we don't project the fish syntax highlighting but follow the markup convention in GNU's man(1): bold text type exactly as shown. italic text replace with appropriate argument. To make it easy to separate these two automatically, formalize that (italic) placeholders must be uppercase; while all lowercase text is interpreted literally (so rendered bold). This makes manpages more consistent, see string-join(1) and and(1). Implementation notes: Since we want manpage formatting but Sphinx's Pygments highlighing plugin does not support manpage output, add our custom "synopsis" directive. This directive parses differently when manpage output is specified. This means that the HTML and manpage build processes must not share a cache, because the parsed doctrees are cached. Work around this by using separate cache locations for build targets "sphinx-docs" (which creates HTML) and "sphinx-manpages". A better solution would be to only override Sphinx's ManualPageBuilder but that would take a bit more code (ideally we could override ManualPageWriter but Sphinx 4.3.2 doesn't really support that). --- Alternative solution: stick with line blocks but use roles like :command: or :option: (or custom ones). While this would make it possible to produce HTML that is consistent with code blocks (by adding a bit of CSS), the source would look uglier and is harder to maintain. (Let's say we want to add custom formatting to the [|] metacharacters in HTML. This is much easier with the proposed patch.) --- [RST line blocks]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks [backslashes in weird places]: https://github.com/fish-shell/fish-shell/pull/8626#discussion_r782837750
207 lines
6.4 KiB
ReStructuredText
207 lines
6.4 KiB
ReStructuredText
.. _cmd-test:
|
|
|
|
test - perform tests on files and text
|
|
======================================
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. synopsis::
|
|
|
|
test [EXPRESSION]
|
|
[ [EXPRESSION] ]
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
.. only:: builder_man
|
|
|
|
NOTE: This page documents the fish builtin ``test``.
|
|
To see the documentation on the ``test`` command you might have,
|
|
use ``command man test``.
|
|
|
|
Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.
|
|
|
|
The first form (``test``) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brackets (``[ [EXPRESSION] ]``).
|
|
|
|
This test is mostly POSIX-compatible.
|
|
|
|
When using a variable as an argument for a test operator you should almost always enclose it in double-quotes. There are only two situations it is safe to omit the quote marks. The first is when the argument is a literal string with no whitespace or other characters special to the shell (e.g., semicolon). For example, ``test -b /my/file``. The second is using a variable that expands to exactly one element including if that element is the empty string (e.g., ``set x ''``). If the variable is not set, set but with no value, or set to more than one value you must enclose it in double-quotes. For example, ``test "$x" = "$y"``. Since it is always safe to enclose variables in double-quotes when used as ``test`` arguments that is the recommended practice.
|
|
|
|
Operators for files and directories
|
|
-----------------------------------
|
|
|
|
- ``-b FILE`` returns true if ``FILE`` is a block device.
|
|
|
|
- ``-c FILE`` returns true if ``FILE`` is a character device.
|
|
|
|
- ``-d FILE`` returns true if ``FILE`` is a directory.
|
|
|
|
- ``-e FILE`` returns true if ``FILE`` exists.
|
|
|
|
- ``-f FILE`` returns true if ``FILE`` is a regular file.
|
|
|
|
- ``-g FILE`` returns true if ``FILE`` has the set-group-ID bit set.
|
|
|
|
- ``-G FILE`` returns true if ``FILE`` exists and has the same group ID as the current user.
|
|
|
|
- ``-k FILE`` returns true if ``FILE`` has the sticky bit set. If the OS does not support the concept it returns false. See https://en.wikipedia.org/wiki/Sticky_bit.
|
|
|
|
- ``-L FILE`` returns true if ``FILE`` is a symbolic link.
|
|
|
|
- ``-O FILE`` returns true if ``FILE`` exists and is owned by the current user.
|
|
|
|
- ``-p FILE`` returns true if ``FILE`` is a named pipe.
|
|
|
|
- ``-r FILE`` returns true if ``FILE`` is marked as readable.
|
|
|
|
- ``-s FILE`` returns true if the size of ``FILE`` is greater than zero.
|
|
|
|
- ``-S FILE`` returns true if ``FILE`` is a socket.
|
|
|
|
- ``-t FD`` returns true if the file descriptor ``FD`` is a terminal (TTY).
|
|
|
|
- ``-u FILE`` returns true if ``FILE`` has the set-user-ID bit set.
|
|
|
|
- ``-w FILE`` returns true if ``FILE`` is marked as writable; note that this does not check if the filesystem is read-only.
|
|
|
|
- ``-x FILE`` returns true if ``FILE`` is marked as executable.
|
|
|
|
Operators for text strings
|
|
--------------------------
|
|
|
|
- ``STRING1 = STRING2`` returns true if the strings ``STRING1`` and ``STRING2`` are identical.
|
|
|
|
- ``STRING1 != STRING2`` returns true if the strings ``STRING1`` and ``STRING2`` are not identical.
|
|
|
|
- ``-n STRING`` returns true if the length of ``STRING`` is non-zero.
|
|
|
|
- ``-z STRING`` returns true if the length of ``STRING`` is zero.
|
|
|
|
Operators to compare and examine numbers
|
|
----------------------------------------
|
|
|
|
- ``NUM1 -eq NUM2`` returns true if ``NUM1`` and ``NUM2`` are numerically equal.
|
|
|
|
- ``NUM1 -ne NUM2`` returns true if ``NUM1`` and ``NUM2`` are not numerically equal.
|
|
|
|
- ``NUM1 -gt NUM2`` returns true if ``NUM1`` is greater than ``NUM2``.
|
|
|
|
- ``NUM1 -ge NUM2`` returns true if ``NUM1`` is greater than or equal to ``NUM2``.
|
|
|
|
- ``NUM1 -lt NUM2`` returns true if ``NUM1`` is less than ``NUM2``.
|
|
|
|
- ``NUM1 -le NUM2`` returns true if ``NUM1`` is less than or equal to ``NUM2``.
|
|
|
|
Both integers and floating point numbers are supported.
|
|
|
|
Operators to combine expressions
|
|
--------------------------------
|
|
|
|
- ``COND1 -a COND2`` returns true if both ``COND1`` and ``COND2`` are true.
|
|
|
|
- ``COND1 -o COND2`` returns true if either ``COND1`` or ``COND2`` are true.
|
|
|
|
Expressions can be inverted using the ``!`` operator:
|
|
|
|
- ``! EXPRESSION`` returns true if ``EXPRESSION`` is false, and false if ``EXPRESSION`` is true.
|
|
|
|
Expressions can be grouped using parentheses.
|
|
|
|
- ``( EXPRESSION )`` returns the value of ``EXPRESSION``.
|
|
|
|
Note that parentheses will usually require escaping with ``\(`` to avoid being interpreted as a command substitution.
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
If the ``/tmp`` directory exists, copy the ``/etc/motd`` file to it:
|
|
|
|
|
|
|
|
::
|
|
|
|
if test -d /tmp
|
|
cp /etc/motd /tmp/motd
|
|
end
|
|
|
|
|
|
If the variable ``MANPATH`` is defined and not empty, print the contents. (If ``MANPATH`` is not defined, then it will expand to zero arguments, unless quoted.)
|
|
|
|
|
|
|
|
::
|
|
|
|
if test -n "$MANPATH"
|
|
echo $MANPATH
|
|
end
|
|
|
|
|
|
Parentheses and the ``-o`` and ``-a`` operators can be combined to produce more complicated expressions. In this example, success is printed if there is a ``/foo`` or ``/bar`` file as well as a ``/baz`` or ``/bat`` file.
|
|
|
|
|
|
|
|
::
|
|
|
|
if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \)
|
|
echo Success.
|
|
end.
|
|
|
|
|
|
Numerical comparisons will simply fail if one of the operands is not a number:
|
|
|
|
|
|
|
|
::
|
|
|
|
if test 42 -eq "The answer to life, the universe and everything"
|
|
echo So long and thanks for all the fish # will not be executed
|
|
end
|
|
|
|
|
|
A common comparison is with $status:
|
|
|
|
|
|
|
|
::
|
|
|
|
if test $status -eq 0
|
|
echo "Previous command succeeded"
|
|
end
|
|
|
|
|
|
The previous test can likewise be inverted:
|
|
|
|
|
|
|
|
::
|
|
|
|
if test ! $status -eq 0
|
|
echo "Previous command failed"
|
|
end
|
|
|
|
|
|
which is logically equivalent to the following:
|
|
|
|
|
|
|
|
::
|
|
|
|
if test $status -ne 0
|
|
echo "Previous command failed"
|
|
end
|
|
|
|
|
|
Standards
|
|
---------
|
|
|
|
``test`` implements a subset of the `IEEE Std 1003.1-2008 (POSIX.1) standard <https://www.unix.com/man-page/posix/1p/test/>`__. The following exceptions apply:
|
|
|
|
- The ``<`` and ``>`` operators for comparing strings are not implemented.
|
|
|
|
- Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the ``test`` utility in another shell.
|
|
|
|
In cases such as this, one can use ``command`` ``test`` to explicitly use the system's standalone ``test`` rather than this ``builtin`` ``test``.
|