-
Notifications
You must be signed in to change notification settings - Fork 1.9k
/
test.rst
246 lines (155 loc) · 6.88 KB
/
test.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
.. _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``.
``test`` checks the given conditions and sets the exit status to 0 if they are true, 1 if they are false.
The first form (``test``) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brackets (``[ [EXPRESSION] ]``).
When using a variable or command substitution as an argument with ``test`` you should almost always enclose it in double-quotes, as variables expanding to zero or more than one argument will most likely interact badly with ``test``.
For historical reasons, ``test`` supports the one-argument form (``test foo``), and this will also be triggered by e.g. ``test -n $foo`` if $foo is unset. We recommend you don't use the one-argument form and quote all variables or command substitutions used with ``test``.
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 to compare files and directories
------------------------------------------
*FILE1* **-nt** *FILE2*
Returns true if *FILE1* is newer than *FILE2*, or *FILE1* exists and *FILE2* does not.
*FILE1* **-ot** *FILE2*
Returns true if *FILE1* is older than *FILE2*, or *FILE2* exists and *FILE1* does not.
*FILE1* **-ef** *FILE1*
Returns true if *FILE1* and *FILE2* refer to the same file.
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 ``\`` (so they appear as ``\(`` and ``\)``) 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 :envvar:`MANPATH` is defined and not empty, print the contents. (If :envvar:`MANPATH` is not defined, then it will expand to zero arguments, unless quoted.)
::
if test -n "$MANPATH"
echo $MANPATH
end
Be careful with unquoted variables::
if test -n $MANPATH
# This will also be reached if $MANPATH is unset,
# because in that case we have `test -n`, so it checks if "-n" is non-empty, and it is.
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 :envvar:`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
---------
Unlike many things in fish, ``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.
In cases such as this, one can use ``command`` ``test`` to explicitly use the system's standalone ``test`` rather than this ``builtin`` ``test``.
See also
--------
Other commands that may be useful as a condition, and are often easier to use:
- :doc:`string`, which can do string operations including wildcard and regular expression matching
- :doc:`path`, which can do file checks and operations, including filters on multiple paths at once