git.sur5r.net Git - openldap/blob - doc/man/man3/regex.3

   1 .TH regex 3 local
   2 .DA Jun 19 1986
   3 .SH NAME
   4 re_comp, re_exec, re_subs, re_modw, re_fail  \- regular expression handling
   5 .SH ORIGIN
   6 Dept. of Computer Science
   7 .br
   8 York University
   9 .SH SYNOPSIS
  10 .B char *re_comp(pat)
  11 .br
  12 .B char *pat;
  13 .PP
  14 .B re_exec(str)
  15 .br
  16 .B char *str;
  17 .PP
  18 .B re_subs(src, dst)
  19 .br
  20 .B char *src;
  21 .br
  22 .B char *dst;
  23 .PP
  24 .B void re_fail(msg, op)
  25 .br
  26 .B char *msg;
  27 .br
  28 .B char op;
  29 .PP
  30 .B void re_modw(str)
  31 .br
  32 .B char *str;
  33
  34 .SH DESCRIPTION
  35 .PP
  36 These functions implement
  37 .IR ed (1)-style
  38 partial regular expressions and supporting facilities.
  39 .PP
  40 .I Re_comp
  41 compiles a pattern string into an internal form (a deterministic finite-state
  42 automaton) to be executed by
  43 .I re_exec
  44 for pattern matching.
  45 .I Re_comp
  46 returns 0 if the pattern is compiled successfully, otherwise it returns an
  47 error message string. If
  48 .I re_comp
  49 is called with a 0 or a \fInull\fR string, it returns without changing the
  50 currently compiled regular expression.
  51 .sp
  52 .I Re_comp
  53 supports the same limited set of
  54 .I regular expressions
  55 found in
  56 .I ed
  57 and Berkeley
  58 .IR regex (3)
  59 routines:
  60 .sp
  61 .if n .in +1.6i
  62 .if t .in +1i
  63 .de Ti
  64 .if n .ti -1.6i
  65 .if t .ti -1i
  66 ..
  67 .if n .ta 0.8i +0.8i +0.8i
  68 .if t .ta 0.5i +0.5i +0.5i
  69 .Ti
  70 [1]     \fIchar\fR      Matches itself, unless it is a special
  71 character (meta-character): \fB. \\ [ ] * + ^ $\fR
  72
  73 .Ti
  74 [2]     \fB.\fR Matches \fIany\fR character.
  75
  76 .Ti
  77 [3]     \fB\\\fR        Matches the character following it, except
  78 when followed by a digit 1 to 9, \fB(\fR, fB)\fR, \fB<\fR or \fB>\fR.
  79 (see [7], [8] and [9]) It is used as an escape character for all
  80 other meta-characters, and itself. When used
  81 in a set ([4]), it is treated as an ordinary
  82 character.
  83
  84 .Ti
  85 [4]     \fB[\fIset\fB]\fR       Matches one of the characters in the set.
  86 If the first character in the set is \fB^\fR,
  87 it matches a character NOT in the set. A
  88 shorthand
  89 .IR S - E
  90 is used to specify a set of
  91 characters
  92 .I S
  93 up to
  94 .IR E ,
  95 inclusive. The special
  96 characters \fB]\fR and \fB-\fR have no special
  97 meaning if they appear as the first chars
  98 in the set.
  99 .nf
 100         examples:       match:
 101         [a-z]           any lowercase alpha
 102         [^]-]           any char except ] and -
 103         [^A-Z]          any char except
 104                         uppercase alpha
 105         [a-zA-Z0-9]     any alphanumeric
 106 .fi
 107
 108 .Ti
 109 [5]     \fB*\fR Any regular expression form [1] to [4], followed by
 110 closure char (*) matches zero or more matches of
 111 that form.
 112
 113 .Ti
 114 [6]     \fB+\fR Same as [5], except it matches one or more.
 115
 116 .Ti
 117 [7]             A regular expression in the form [1] to [10], enclosed
 118 as \\(\fIform\fR\\) matches what form matches. The enclosure
 119 creates a set of tags, used for [8] and for
 120 pattern substitution in
 121 .I re_subs.
 122 The tagged forms are numbered
 123 starting from 1.
 124
 125 .Ti
 126 [8]             A \\ followed by a digit 1 to 9 matches whatever a
 127 previously tagged regular expression ([7]) matched.
 128
 129 .Ti
 130 [9]     \fB\\<\fR       Matches the beginning of a \fIword\fR,
 131 that is, an empty string followed by a
 132 letter, digit, or _ and not preceded by
 133 a letter, digit, or _ .
 134 .Ti
 135         \fB\\>\fR       Matches the end of a \fIword\fR,
 136 that is, an empty string preceded
 137 by a letter, digit, or _ , and not
 138 followed by a letter, digit, or _ .
 139
 140 .Ti
 141 [10]            A composite regular expression
 142 \fIxy\fR where \fIx\fR and \fIy\fR
 143 are in the form of [1] to [10] matches the longest
 144 match of \fIx\fR followed by a match for \fIy\fR.
 145
 146 .Ti
 147 [11]    \fB^ $\fR       a regular expression starting with a \fB^\fR character
 148 and/or ending with a \fB$\fR character, restricts the
 149 pattern matching to the beginning of the line,
 150 and/or the end of line [anchors]. Elsewhere in the
 151 pattern, \fB^\fR and \fB$\fR are treated as ordinary characters.
 152 .if n .in -1.6i
 153 .if t .in -1i
 154
 155 .PP
 156 .I Re_exec
 157 executes the internal form produced by
 158 .I re_comp
 159 and searches the argument string for the regular expression described
 160 by the internal
 161 form.
 162 .I Re_exec
 163 returns 1 if the last regular expression pattern is matched within the string,
 164 0 if no match is found. In case of an internal error (corrupted internal
 165 form),
 166 .I re_exec
 167 calls the user-supplied
 168 .I re_fail
 169 and returns 0.
 170 .PP
 171 The strings passed to both
 172 .I re_comp
 173 and
 174 .I re_exec
 175 may have trailing or embedded newline characters. The strings
 176 must be terminated by nulls.
 177 .PP
 178 .I Re_subs
 179 does
 180 .IR ed -style
 181 pattern substitution, after a successful match is found by
 182 .I re_exec.
 183 The source string parameter to
 184 .I re_subs
 185 is copied to the destination string with the following interpretation;
 186 .sp
 187 .if n .in +1.6i
 188 .if t .in +1i
 189 .Ti
 190 [1]     &       Substitute the entire matched string in the destination.
 191
 192 .Ti
 193 [2]     \\\fIn\fR       Substitute the substring matched by a tagged subpattern
 194 numbered \fIn\fR, where \fIn\fR is between 1 to 9, inclusive.
 195
 196 .Ti
 197 [3]     \\\fIchar\fR    Treat the next character literally,
 198 unless the character is a digit ([2]).
 199 .if n .in -1.6i
 200 .if t .in -1i
 201
 202 .PP
 203 If the copy operation with the substitutions is successful,
 204 .I re_subs
 205 returns 1.
 206 If the source string is corrupted, or the last call to
 207 .I re_exec
 208 fails, it returns 0.
 209
 210 .I Re_modw
 211 is used to
 212 add new characters into an internal table to
 213 change the re_exec's understanding of what
 214 a \fIword\fR should look like, when matching with \fB\\<\fR and \fB\\>\fR
 215 constructs. If the string parameter is 0 or null string,
 216 the table is reset back to the default, which contains \fBA-Z a-z 0-9 _\fR .
 217
 218 .I Re_fail
 219 is a user-supplied routine to handle internal errors.
 220 .I re_exec
 221 calls
 222 .I re_fail
 223 with an error message string, and the opcode character that caused the error.
 224 The default
 225 .I re_fail
 226 routine simply prints the message and the opcode character to
 227 .I stderr
 228 and invokes
 229 .IR exit (2).
 230 .SH EXAMPLES
 231 In the examples below, the
 232 .I nfaform
 233 describes the internal form after the pattern is compiled. For additional
 234 details, refer to the sources.
 235 .PP
 236 .ta 0.5i +0.5i +0.5i
 237 .nf
 238 foo*.*
 239         nfaform:        CHR f CHR o CLO CHR o END CLO ANY END END
 240         matches:        \fIfo foo fooo foobar fobar foxx ...\fR
 241
 242 fo[ob]a[rz]
 243         nfaform:        CHR f CHR o CCL 2 o b CHR a CCL 2 r z END
 244         matches:        \fIfobar fooar fobaz fooaz\fR
 245
 246 foo\\\\+
 247         nfaform:        CHR f CHR o CHR o CHR \\ CLO CHR \\ END END
 248         matches:        \fIfoo\\ foo\\\\ foo\\\\\\  ...\fR
 249
 250 \\(foo\\)[1-3]\\1       (same as foo[1-3]foo, but takes less internal space)
 251         nfaform:        BOT 1 CHR f CHR o CHR o EOT 1 CCL 3 1 2 3 REF 1 END
 252         matches:        \fIfoo1foo foo2foo foo3foo\fR
 253
 254 \\(fo.*\\)-\\1
 255         nfaform:        BOT 1 CHR f CHR o CLO ANY END EOT 1 CHR - REF 1 END
 256         matches:        \fIfoo-foo fo-fo fob-fob foobar-foobar ...\fR
 257 .SH DIAGNOSTICS
 258 .I Re_comp
 259 returns one of the following strings if an error occurs:
 260 .PP
 261 .nf
 262 .in +0.5i
 263 \fINo previous regular expression,
 264 Empty closure,
 265 Illegal closure,
 266 Cyclical reference,
 267 Undetermined reference,
 268 Unmatched \e(,
 269 Missing ],
 270 Null pattern inside \e(\e),
 271 Null pattern inside \e<\e>,
 272 Too many \e(\e) pairs,
 273 Unmatched \e)\fP.
 274 .in -0.5i
 275 .fi
 276 .SH REFERENCES
 277 .if n .ta 3i
 278 .if t .ta 1.8i
 279 .nf
 280 \fISoftware tools\fR    Kernighan & Plauger
 281 \fISoftware tools in Pascal\fR  Kernighan & Plauger
 282 \fIGrep sources\fR [rsx-11 C dist]      David Conroy
 283 \fIEd - text editor\fR  Unix Programmer's Manual
 284 \fIAdvanced editing on Unix\fR  B. W. Kernighan
 285 \fIRegExp sources\fR    Henry Spencer
 286 .fi
 287 .SH "HISTORY AND NOTES"
 288 These routines are derived from various implementations
 289 found in
 290 .I "Software Tools"
 291 books, and David Conroy's
 292 .I grep.
 293 They are NOT derived from licensed/restricted software.
 294 For more interesting/academic/complicated implementations,
 295 see Henry Spencer's
 296 .I regexp
 297 routines (V8), or
 298 .I "GNU Emacs"
 299 pattern
 300 matching module.
 301 .PP
 302 The
 303 .I re_comp
 304 and
 305 .I re_exec
 306 routines perform
 307 .I almost
 308 as well as their licensed counterparts, sometimes better.
 309 In very few instances, they
 310 are about 10% to 15% slower.
 311 .SH AUTHOR
 312 Ozan S. Yigit (oz)
 313 .br
 314 usenet: utzoo!yetti!oz
 315 .br
 316 bitnet: oz@yusol || oz@yuyetti
 317 .SH "SEE ALSO"
 318 ed(1), ex(1), egrep(1), fgrep(1), grep(1), regex(3)
 319 .SH BUGS
 320 These routines are \fIPublic Domain\fR. You can get them
 321 in source.
 322 .br
 323 The internal storage for the \fInfa form\fR is not checked for
 324 overflows. Currently, it is 1024 bytes.
 325 .br
 326 Others, no doubt.