Annotation of src/bin/expr/expr.1, Revision 1.36
1.36 ! sevan 1: .\" $NetBSD: expr.1,v 1.35 2016/08/23 03:21:16 sevan Exp $
1.8 cgd 2: .\"
1.24 jdolecek 3: .\" Copyright (c) 2000,2003 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
1.1 jtc 5: .\"
1.24 jdolecek 6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by J.T. Conklin <jtc@NetBSD.org> and Jaromir Dolecek <jdolecek@NetBSD.org>.
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28: .\" POSSIBILITY OF SUCH DAMAGE.
29: .\"
1.34 sevan 30: .Dd August 23, 2016
1.1 jtc 31: .Dt EXPR 1
32: .Os
33: .Sh NAME
34: .Nm expr
35: .Nd evaluate expression
36: .Sh SYNOPSIS
1.10 enami 37: .Nm
1.1 jtc 38: .Ar expression
39: .Sh DESCRIPTION
40: The
1.10 enami 41: .Nm
1.16 jdolecek 42: utility evaluates
1.1 jtc 43: .Ar expression
44: and writes the result on standard output.
45: .Pp
46: All operators are separate arguments to the
1.10 enami 47: .Nm
1.1 jtc 48: utility.
49: Characters special to the command interpreter must be escaped.
50: .Pp
1.6 jtc 51: Operators are listed below in order of increasing precedence.
52: Operators with equal precedence are grouped within { } symbols.
1.1 jtc 53: .Bl -tag -width indent
1.30 joerg 54: .It Ar expr1 Li \&| Ar expr2
1.16 jdolecek 55: Returns the evaluation of
56: .Ar expr1
1.1 jtc 57: if it is neither an empty string nor zero;
58: otherwise, returns the evaluation of
59: .Ar expr2 .
1.19 ross 60: .It Ar expr1 Li \*[Am] Ar expr2
1.1 jtc 61: Returns the evaluation of
62: .Ar expr1
63: if neither expression evaluates to an empty string or zero;
64: otherwise, returns zero.
1.19 ross 65: .It Ar expr1 Li "{=, \*[Gt], \*[Ge], \*[Lt], \*[Le], !=}" Ar expr2
1.16 jdolecek 66: Returns the results of integer comparison if both arguments are integers;
1.3 jtc 67: otherwise, returns the results of string comparison using the locale-specific
68: collation sequence.
1.1 jtc 69: The result of each comparison is 1 if the specified relation is true,
70: or 0 if the relation is false.
71: .It Ar expr1 Li "{+, -}" Ar expr2
72: Returns the results of addition or subtraction of integer-valued arguments.
73: .It Ar expr1 Li "{*, /, %}" Ar expr2
74: Returns the results of multiplication, integer division, or remainder of integer-valued arguments.
1.30 joerg 75: .It Ar expr1 Li \&: Ar expr2
1.16 jdolecek 76: The
1.17 wiz 77: .Dq \&:
1.16 jdolecek 78: operator matches
79: .Ar expr1
80: against
1.1 jtc 81: .Ar expr2 ,
1.21 wiz 82: which must be a regular expression.
83: The regular expression is anchored
1.32 jdf 84: to the beginning of the string with an implicit
1.5 jtc 85: .Dq ^ .
1.1 jtc 86: .Pp
1.5 jtc 87: If the match succeeds and the pattern contains at least one regular
1.16 jdolecek 88: expression subexpression
89: .Dq "\e(...\e)" ,
90: the string corresponding to
1.1 jtc 91: .Dq "\e1"
92: is returned;
1.16 jdolecek 93: otherwise the matching operator returns the number of characters matched.
1.5 jtc 94: If the match fails and the pattern contains a regular expression subexpression
95: the null string is returned;
96: otherwise 0.
1.27 wiz 97: .It "( " Ar expr No " )"
1.15 jdolecek 98: Parentheses are used for grouping in the usual manner.
1.1 jtc 99: .El
100: .Pp
1.27 wiz 101: Additionally, the following keywords are recognized:
1.26 jdolecek 102: .Bl -tag -width indent
1.30 joerg 103: .It length Ar expr
1.27 wiz 104: Returns the length of the specified string in bytes.
1.26 jdolecek 105: .El
106: .Pp
1.15 jdolecek 107: Operator precedence (from highest to lowest):
108: .Bl -enum -compact -offset indent
109: .It
110: parentheses
111: .It
1.26 jdolecek 112: length
113: .It
1.17 wiz 114: .Dq \&:
1.16 jdolecek 115: .It
116: .Dq "*" ,
117: .Dq "/" ,
118: and
119: .Dq "%"
120: .It
121: .Dq "+"
122: and
123: .Dq "-"
124: .It
125: compare operators
1.15 jdolecek 126: .It
1.19 ross 127: .Dq \*[Am]
1.15 jdolecek 128: .It
1.30 joerg 129: .Dq \&|
1.15 jdolecek 130: .El
1.18 wiz 131: .Sh EXIT STATUS
132: The
133: .Nm
134: utility exits with one of the following values:
135: .Bl -tag -width Ds -compact
136: .It 0
137: the expression is neither an empty string nor 0.
138: .It 1
139: the expression is an empty string or 0.
140: .It 2
141: the expression is invalid.
1.19 ross 142: .It \*[Gt]2
1.18 wiz 143: an error occurred (such as memory allocation failure).
144: .El
1.1 jtc 145: .Sh EXAMPLES
146: .Bl -enum
1.15 jdolecek 147: .It
1.33 wiz 148: The following example adds one to variable
149: .Dq a :
1.1 jtc 150: .Dl a=`expr $a + 1`
151: .It
1.31 dholland 152: The following example returns zero, due to subtraction having higher precedence
1.33 wiz 153: than the
154: .Dq \*[Am]
155: operator:
1.19 ross 156: .Dl expr 1 '\*[Am]' 1 - 1
1.15 jdolecek 157: .It
1.1 jtc 158: The following example returns the filename portion of a pathname stored
1.33 wiz 159: in variable
160: .Dq a :
1.14 jdolecek 161: .Dl expr "/$a" Li : '.*/\e(.*\e)'
1.1 jtc 162: .It
1.33 wiz 163: The following example returns the number of characters in variable
164: .Dq a :
1.1 jtc 165: .Dl expr $a Li : '.*'
166: .El
1.15 jdolecek 167: .Sh COMPATIBILITY
1.14 jdolecek 168: This implementation of
169: .Nm
1.23 perry 170: internally uses 64 bit representation of integers and checks for
1.21 wiz 171: over- and underflows.
1.33 wiz 172: It also treats
173: .Dq /
174: (the division mark) and option
175: .Dq --
176: correctly depending upon context.
1.14 jdolecek 177: .Pp
178: .Nm
179: on other systems (including
180: .Nx
181: up to and including
182: .Nx 1.5 )
1.28 wiz 183: might not be so graceful.
1.21 wiz 184: Arithmetic results might be arbitrarily
1.14 jdolecek 185: limited on such systems, most commonly to 32 bit quantities.
186: This means such
187: .Nm
188: can only process values between -2147483648 and +2147483647.
189: .Pp
190: On other systems,
191: .Nm
192: might also not work correctly for regular expressions where
1.33 wiz 193: either side contains
194: .Dq /
195: (a single forward slash), like this:
1.14 jdolecek 196: .Bd -literal -offset indent
197: expr / : '.*/\e(.*\e)'
198: .Ed
199: .Pp
1.33 wiz 200: If this is the case, you might use
201: .Dq //
202: (a double forward slash)
1.23 perry 203: to avoid confusion with the division operator:
1.14 jdolecek 204: .Bd -literal -offset indent
205: expr "//$a" : '.*/\e(.*\e)'
206: .Ed
1.15 jdolecek 207: .Pp
208: According to
209: .St -p1003.2 ,
210: .Nm
1.33 wiz 211: has to recognize special option
212: .Dq -- ,
213: treat it as a delimiter to mark the end of command
214: line options, and ignore it.
1.15 jdolecek 215: Some
216: .Nm
1.34 sevan 217: implementations do not recognize it at all; others
1.15 jdolecek 218: might ignore it even in cases where doing so results in syntax
1.21 wiz 219: error.
220: There should be same result for both following examples,
1.15 jdolecek 221: but it might not always be:
222: .Bl -enum -compact -offset indent
223: .It
224: expr -- : .
225: .It
226: expr -- -- : .
227: .El
1.23 perry 228: Although
1.15 jdolecek 229: .Nx
230: .Nm
1.23 perry 231: handles both cases correctly, you should not depend on this behavior
1.33 wiz 232: for portability reasons and avoid passing a bare
233: .Dq --
234: as the first
1.15 jdolecek 235: argument.
1.30 joerg 236: .Sh STANDARDS
237: The
238: .Nm
239: utility conforms to
240: .St -p1003.2 .
241: The
242: .Ar length
243: keyword is an extension for compatibility with GNU
244: .Nm .
1.34 sevan 245: .Sh HISTORY
246: An
247: .Nm
248: utility first appeared in the Programmer's Workbench (PWB/UNIX).
1.36 ! sevan 249: A public domain version of
1.34 sevan 250: .Nm
251: written by
252: .An Pace Willisson
253: .Aq pace@blitz.com
254: appeared in
255: .Bx 386 0.1 .
1.30 joerg 256: .Sh AUTHORS
1.34 sevan 257: Initial implementation by
1.36 ! sevan 258: .An Pace Willisson Aq Mt pace@blitz.com
1.34 sevan 259: was largely rewritten by
1.35 sevan 260: .An -nosplit
1.36 ! sevan 261: .An J.T. Conklin Aq Mt jtc@NetBSD.org .
1.34 sevan 262: It was rewritten again for
1.30 joerg 263: .Nx 1.6
264: by
1.36 ! sevan 265: .An -nosplit
! 266: .An Jaromir Dolecek Aq Mt jdolecek@NetBSD.org .
1.30 joerg 267: .Sh NOTES
268: The empty string
269: .Do Dc
270: cannot be matched with the intuitive:
271: .Bd -literal -offset indent
272: expr '' : '$'
273: .Ed
274: .Pp
275: The reason is that the returned number of matched characters (zero)
276: is indistinguishable from a failed match, so this returns failure.
277: To match the empty string, use something like:
278: .Bd -literal -offset indent
279: expr x'' : 'x$'
280: .Ed
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to expr.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / bin / expr