diff options
Diffstat (limited to 'doc_src/test.txt')
-rw-r--r-- | doc_src/test.txt | 155 |
1 files changed, 92 insertions, 63 deletions
diff --git a/doc_src/test.txt b/doc_src/test.txt index 946c5330..64a6f471 100644 --- a/doc_src/test.txt +++ b/doc_src/test.txt @@ -1,100 +1,129 @@ \section test test - perform tests on files and text \subsection test-synopsis Synopsis - <tt>test [EXPRESSION]</tt> +\fish{synopsis} +test [EXPRESSION] +[ [EXPRESSION] ] +\endfish \subsection test-description Description -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. +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 ] ]`). The following operators are available to examine files and directories: -- <tt>-b FILE</tt> returns true if \c FILE is a block device. -- <tt>-c FILE</tt> returns true if \c FILE is a character device. -- <tt>-d FILE</tt> returns true if \c FILE is a directory. -- <tt>-e FILE</tt> returns true if \c FILE exists. -- <tt>-f FILE</tt> returns true if \c FILE is a regular file. -- <tt>-g FILE</tt> returns true if \c FILE has the set-group-ID bit set. -- <tt>-G FILE</tt> returns true if \c FILE exists and has the same group ID -as the current user. -- <tt>-L FILE</tt> returns true if \c FILE is a symbolic link. -- <tt>-O FILE</tt> returns true if \c FILE exists and is owned by the current -user. -- <tt>-p FILE</tt> returns true if \c FILE is a named pipe. -- <tt>-r FILE</tt> returns true if \c FILE is marked as readable. -- <tt>-s FILE</tt> returns true if the size of \c FILE is greater than zero. -- <tt>-S FILE</tt> returns true if \c FILE is a socket. -- <tt>-t FD</tt> returns true if the file descriptor \c FD is a terminal (TTY). -- <tt>-u FILE</tt> returns true if \c FILE has the set-user-ID bit set. -- <tt>-w FILE</tt> returns true if \c FILE is marked as writable; note that this does not check if the filesystem is read-only. -- <tt>-x FILE</tt> returns true if \c FILE is marked as executable. + +- `-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. + +- `-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. The following operators are available to compare and examine text strings: -- <tt>STRING1 = STRING2</tt> returns true if the strings \c STRING1 and -\c STRING2 are identical. -- <tt>STRING1 != STRING2</tt> returns true if the strings \c STRING1 and -\c STRING2 are not identical. -- <tt>-n STRING</tt> returns true if the length of \c STRING is non-zero. -- <tt>-z STRING</tt> returns true if the length of \c STRING is zero. + +- `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. The following operators are available to compare and examine numbers: -- <tt>NUM1 -eq NUM2</tt> returns true if \c NUM1 and \c NUM2 are numerically equal. -- <tt>NUM1 -ne NUM2</tt> returns true if \c NUM1 and \c NUM2 are not numerically equal. -- <tt>NUM1 -gt NUM2</tt> returns true if \c NUM1 is greater than <tt>NUM2</tt>. -- <tt>NUM1 -ge NUM2</tt> returns true if \c NUM1 is greater than or equal to <tt>NUM2</tt>. -- <tt>NUM1 -lt NUM2</tt> returns true if \c NUM1 is less than <tt>NUM2</tt>. -- <tt>NUM1 -le NUM2</tt> returns true if \c NUM1 is less than or equal to <tt>NUM2</tt>. -Note that only integers are supported. For more complex mathematical -operations, including fractions, the \c env program may be useful. Consult the -documentation for your operating system. +- `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`. + +Note that only integers are supported. For more complex mathematical operations, including fractions, the `env` program may be useful. Consult the documentation for your operating system. Expressions can be combined using the following operators: -- <tt>COND1 -a COND2</tt> returns true if both \c COND1 and \c COND2 are true. -- <tt>COND1 -o COND2</tt> returns true if either \c COND1 or \c COND2 are true. -Expressions can be inverted using the \c ! operator: -- <tt>! EXPRESSION</tt> returns true if \c EXPRESSION is false, and false if -\c EXPRESSION is true. +- `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. -- <tt>( EXPRESSION )</tt> returns the value of <tt>EXPRESSION</tt>. -Note that parentheses will usually require escaping with <tt>\\(</tt> to avoid -being interpreted as a command substitution. + +- `( EXPRESSION )` returns the value of `EXPRESSION`. + + Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution. + \subsection test-example Examples -If the \c /tmp directory exists, copy the \c /etc/motd file to it: +If the `/tmp` directory exists, copy the `/etc/motd` file to it: -<pre> +\fish if test -d /tmp cp /etc/motd /tmp/motd end -</pre> +\endfish -If the variable \c MANPATH is defined and not empty, print the contents: +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.) -<pre> -if test -n $MANPATH +\fish +if test -n "$MANPATH" echo $MANPATH end -</pre> +\endfish -Parentheses and the \c -o and \c -a operators can be combined to produce -more complicated expressions. In this example, success is printed if there is -a \c /foo or \c /bar file as well as a \c /baz or \c /bat file. +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. -<pre> -if test \\( -f /foo -o -f /bar \\) -a \\( -f /baz -o -f /bat \\) +\fish +if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) echo Success. end. -</pre> +\endfish + \subsection test-standards Standards -\c test implements a subset of the -<a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 -(POSIX.1) standard</a>. The following exceptions apply: -- The \c < and \c > operators for comparing strings are not implemented. +`test` implements a subset of the <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 (POSIX.1) standard</a>. 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`. |