manual/gnumaniak/original/man1/expr.1

   1 .\" You may copy, distribute and modify under the terms of the LDP General
   2 .\" Public License as specified in the LICENSE file that comes with the
   3 .\" gnumaniak distribution
   4 .\"
   5 .\" The author kindly requests that no comments regarding the "better"
   6 .\" suitability or up-to-date notices of any info documentation alternative
   7 .\" is added without contacting him first.
   8 .\"
   9 .\" (C) 1999-2002 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
  10 .\"
  11 .\"     GNU expr man page
  12 .\"     man pages are NOT obsolete!
  13 .\"     <ragnar@ragnar-hojland.com>
  14 .TH expr 1 "18 June 2002" "GNU Shell Utilities 2.1"
  15 .SH NAME
  16 expr \- evaluate expressions
  17 .SH SYNOPSIS
  18 .BI "expr " expression...
  19 .sp
  20 .B expr [\-\-help] [\-\-version]
  21 .br
  22 .SH DESCRIPTION
  23 .B expr
  24 evaluates an expression and writes the result on its standard output.
  25 Each token of the expression must be a separate argument.
  26 .P
  27 Operands are either numbers or strings. \fBexpr\fP converts anything
  28 appearing in an operand position to an integer or a string depending on
  29 the operation being applied to it. Strings are not quoted for
  30 \fBexpr\fP itself, though you may need to quote them to protect
  31 characters with special meaning to the shell (e.g, spaces)
  32 .P
  33 Operators may given as infix symbols or prefix keywords.  Parentheses
  34 may be used for grouping in the usual manner (you must quote parentheses
  35 to avoid the shell evaluating them, however).
  36 .P
  37 .B expr
  38 returns the following exit status:
  39 .br
  40 0 if the expression is neither null nor 0,
  41 .br
  42 1 if the expression is null or 0,
  43 .br
  44 2 for invalid expressions.
  45 .SH OPERATORS (in order of increasing precedence)
  46 .SS Connectives
  47 .IP "\fB|\fP"
  48 Yields its first argument if it is neither null nor 0, otherwise its
  49 second argument.  This is the usual `or' operation.
  50 .IP "\fB&\fP"
  51 Yields its first argument if neither argument is null or 0,
  52 otherwise 0.
  53 .IP "\fB<\fP\0 \fB<=\fP\0 \fB=\fP\0 \fB==\fP\0 \fB!=\fP\0 \fB>=\fP\0 \fB>\fP"
  54 Compare their arguments and return 1 if the relation is true, 0
  55 otherwise.  (\fB==\fP is a synonym for \fB=\fP.)
  56 \fBexpr\fP tries to convert both arguments to numbers and
  57 do a numeric comparison; if it fails when trying to convert either
  58 argument it then does a lexicographic comparison.
  59 .SS Numeric expressions
  60 .IP "\fB+\fP\0 \fB-\fP"
  61 Arithmetic addition and substraction.  Both arguments are converted to numbers;
  62 an error occurs if this cannot be done.
  63 .IP "\fB*\fP\0 \fB/\fP\0 \fB%\fP"
  64 Arithmetic multiplication, division and remainder (`%' is the remainder
  65 operation, as in C).  Both arguments are converted to numbers; an error
  66 occurs if this cannot be done.
  67 .SS String expressions
  68 .IP "\fIstring\fP \fB:\fP \fIregex\fP"
  69 Perform pattern matching.  The arguments are converted to strings and the
  70 second one is considered to be a (basic, a la \fBgrep\fP(1) regular
  71 expression, with a `^'implicitly added at the beginning.  The first
  72 argument is then matched against this regular expression.
  73
  74 If the match succeeds and .\fIregex\fP uses `\e(' and
  75 `\e)', the \fB:\fP expression returns the part of \fIstring\fP that
  76 matched the subexpression; otherwise returns an integer whose value is
  77 the number of characters matched.
  78
  79 If the match fails, the \fB:\fP operator returns the null string if `\e('
  80 and `\e)' are used, otherwise 0.
  81
  82 Only the first `\e(' and `\e)' pair is relevant to the return value;
  83 additional pairs are meaningful only for grouping the regular expression
  84 operators.
  85
  86 Unlike other \fBexpr\fR'ss, `\+' (one or more), `\?' (zero or one), and `\|'
  87 (or connective) are recognized as matching operators.
  88 .TP
  89 In addition, the following keywords are recognized:
  90 .TP
  91 .BI index " string charset"
  92 Return the first position in \fIstring\fP where the first character in
  93 \fIcharset\fP was found.  If no character in
  94 \fIcharset\fP is found in \fIstring\fP, return 0.
  95 .TP
  96 .BI length " string"
  97 Return the length of \fIstring\fP.
  98 .TP
  99 .BI match " string regex"
 100 An alternative way to do pattern matching.  This is the same as
 101 ``\fIstring\fP \fB:\fP \fIregex\fP''.
 102 .TP
 103 .BI quote " string"
 104 Interpret \fIstring\fR as a regular string, no matter if it is an operator or
 105 a keyword.  Disabled when the environment variable \fBPOSIXLY_CORRECT\fR is
 106 set.
 107 .TP
 108 .BI substr " string position length"
 109 Return the substring of \fIstring\fP beginning at \fIposition\fP with
 110 length at most \fIlength\fP.  If either \fIposition\fP or \fIlength\fP
 111 isn't positive or numeric, return a null string.
 112 .PP
 113 Parentheses are used for grouping in the usual manner.  The keywords
 114 (match, substr, index, length) cannot be used as strings.
 115 .SH OPTIONS
 116 When GNU
 117 .B expr
 118 is invoked with exactly one argument, the following options are recognized:
 119 .TP
 120 .B "\-\-help"
 121 Print a usage message on standard output and exit successfully.
 122 .TP
 123 .B "\-\-version"
 124 Print version information on standard output then exit successfully.
 125 .SH EXAMPLES
 126 .PP
 127 To add 1 to the shell variable
 128 .IR foo :
 129 .IP
 130 foo=\`expr $a + 1\`
 131 .PP
 132 To print the non-directory part of the file name stored in variable
 133 .IR bar
 134 (the value in
 135 .IR bar
 136 need not contain `/'):
 137 .IP
 138 expr $bar : \'.*/\e(\^.*\e)\' \'\^|\' $a
 139 .PP
 140 Matching character `b' in the string `abc'
 141 .IP
 142 expr abc : 'a\e(.\e)c'
 143 .PP
 144 Finding out the index for any occurences of `c' and `z' in the string
 145 `abcdef'
 146 .IP
 147 expr index abcdef cz
 148 .PP
 149 Erroneuosly using a keyword (index) as a string
 150 .IP
 151 expr index index a
 152 .PP
 153 Correctly using a keyword (index) as a string
 154 .IP
 155 expr index quote index d
 156 .SH NOTES
 157 Report bugs to bug-sh-utils@gnu.org.
 158 Page updated by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>