3
@setfilename regex.info
7
@c \\{fill-paragraph} works better (for me, anyway) if the text in the
8
@c source file isn't indented.
11
@c Define a new index for our magic constants.
14
@c Put everything in one index (arbitrarily chosen to be the concept index).
21
@c Here is what we use in the Info `dir' file:
22
@c * Regex: (regex). Regular expression library.
26
This file documents the GNU regular expression library.
28
Copyright (C) 1992, 1993 Free Software Foundation, Inc.
30
Permission is granted to make and distribute verbatim copies of this
31
manual provided the copyright notice and this permission notice are
32
preserved on all copies.
35
Permission is granted to process this file through TeX and print the
36
results, provided the printed document carries a copying permission
37
notice identical to this one except for the removal of this paragraph
38
(this paragraph not being relevant to the printed manual).
41
Permission is granted to copy and distribute modified versions of this
42
manual under the conditions for verbatim copying, provided also that the
43
section entitled ``GNU General Public License'' is included exactly as
44
in the original, and provided that the entire resulting derived work is
45
distributed under the terms of a permission notice identical to this one.
47
Permission is granted to copy and distribute translations of this manual
48
into another language, under the above conditions for modified versions,
49
except that the section entitled ``GNU General Public License'' may be
50
included in a translation approved by the Free Software Foundation
51
instead of in the original English.
58
@subtitle edition 0.12a
59
@subtitle 19 September 1992
60
@author Kathryn A. Hargreaves
65
@vskip 0pt plus 1filll
66
Copyright @copyright{} 1992 Free Software Foundation.
68
Permission is granted to make and distribute verbatim copies of this
69
manual provided the copyright notice and this permission notice are
70
preserved on all copies.
72
Permission is granted to copy and distribute modified versions of this
73
manual under the conditions for verbatim copying, provided also that the
74
section entitled ``GNU General Public License'' is included exactly as
75
in the original, and provided that the entire resulting derived work is
76
distributed under the terms of a permission notice identical to this
79
Permission is granted to copy and distribute translations of this manual
80
into another language, under the above conditions for modified versions,
81
except that the section entitled ``GNU General Public License'' may be
82
included in a translation approved by the Free Software Foundation
83
instead of in the original English.
89
@node Top, Overview, (dir), (dir)
90
@top Regular Expression Library
92
This manual documents how to program with the GNU regular expression
93
library. This is edition 0.12a of the manual, 19 September 1992.
95
The first part of this master menu lists the major nodes in this Info
96
document, including the index. The rest of the menu lists all the
97
lower level nodes in the document.
101
* Regular Expression Syntax::
104
* GNU Emacs Operators::
105
* What Gets Matched?::
106
* Programming with Regex::
107
* Copying:: Copying and sharing Regex.
108
* Index:: General index.
109
--- The Detailed Node Listing ---
111
Regular Expression Syntax
114
* Predefined Syntaxes::
115
* Collating Elements vs. Characters::
116
* The Backslash Character::
120
* Match-self Operator:: Ordinary characters.
121
* Match-any-character Operator:: .
122
* Concatenation Operator:: Juxtaposition.
123
* Repetition Operators:: * + ? @{@}
124
* Alternation Operator:: |
125
* List Operators:: [...] [^...]
126
* Grouping Operators:: (...)
127
* Back-reference Operator:: \digit
128
* Anchoring Operators:: ^ $
132
* Match-zero-or-more Operator:: *
133
* Match-one-or-more Operator:: +
134
* Match-zero-or-one Operator:: ?
135
* Interval Operators:: @{@}
137
List Operators (@code{[} @dots{} @code{]} and @code{[^} @dots{} @code{]})
139
* Character Class Operators:: [:class:]
140
* Range Operator:: start-end
144
* Match-beginning-of-line Operator:: ^
145
* Match-end-of-line Operator:: $
154
* Non-Emacs Syntax Tables::
155
* Match-word-boundary Operator:: \b
156
* Match-within-word Operator:: \B
157
* Match-beginning-of-word Operator:: \<
158
* Match-end-of-word Operator:: \>
159
* Match-word-constituent Operator:: \w
160
* Match-non-word-constituent Operator:: \W
164
* Match-beginning-of-buffer Operator:: \`
165
* Match-end-of-buffer Operator:: \'
169
* Syntactic Class Operators::
171
Syntactic Class Operators
173
* Emacs Syntax Tables::
174
* Match-syntactic-class Operator:: \sCLASS
175
* Match-not-syntactic-class Operator:: \SCLASS
177
Programming with Regex
179
* GNU Regex Functions::
180
* POSIX Regex Functions::
181
* BSD Regex Functions::
185
* GNU Pattern Buffers:: The re_pattern_buffer type.
186
* GNU Regular Expression Compiling:: re_compile_pattern ()
187
* GNU Matching:: re_match ()
188
* GNU Searching:: re_search ()
189
* Matching/Searching with Split Data:: re_match_2 (), re_search_2 ()
190
* Searching with Fastmaps:: re_compile_fastmap ()
191
* GNU Translate Tables:: The `translate' field.
192
* Using Registers:: The re_registers type and related fns.
193
* Freeing GNU Pattern Buffers:: regfree ()
195
POSIX Regex Functions
197
* POSIX Pattern Buffers:: The regex_t type.
198
* POSIX Regular Expression Compiling:: regcomp ()
199
* POSIX Matching:: regexec ()
200
* Reporting Errors:: regerror ()
201
* Using Byte Offsets:: The regmatch_t type.
202
* Freeing POSIX Pattern Buffers:: regfree ()
206
* BSD Regular Expression Compiling:: re_comp ()
207
* BSD Searching:: re_exec ()
210
@node Overview, Regular Expression Syntax, Top, Top
213
A @dfn{regular expression} (or @dfn{regexp}, or @dfn{pattern}) is a text
214
string that describes some (mathematical) set of strings. A regexp
215
@var{r} @dfn{matches} a string @var{s} if @var{s} is in the set of
216
strings described by @var{r}.
218
Using the Regex library, you can:
223
see if a string matches a specified pattern as a whole, and
226
search within a string for a substring matching a specified pattern.
230
Some regular expressions match only one string, i.e., the set they
231
describe has only one member. For example, the regular expression
232
@samp{foo} matches the string @samp{foo} and no others. Other regular
233
expressions match more than one string, i.e., the set they describe has
234
more than one member. For example, the regular expression @samp{f*}
235
matches the set of strings made up of any number (including zero) of
236
@samp{f}s. As you can see, some characters in regular expressions match
237
themselves (such as @samp{f}) and some don't (such as @samp{*}); the
238
ones that don't match themselves instead let you specify patterns that
239
describe many different strings.
241
To either match or search for a regular expression with the Regex
242
library functions, you must first compile it with a Regex pattern
243
compiling function. A @dfn{compiled pattern} is a regular expression
244
converted to the internal format used by the library functions. Once
245
you've compiled a pattern, you can use it for matching or searching any
248
The Regex library consists of two source files: @file{regex.h} and
252
Regex provides three groups of functions with which you can operate on
253
regular expressions. One group---the @sc{gnu} group---is more powerful
254
but not completely compatible with the other two, namely the @sc{posix}
255
and Berkeley @sc{unix} groups; its interface was designed specifically
256
for @sc{gnu}. The other groups have the same interfaces as do the
257
regular expression functions in @sc{posix} and Berkeley
260
We wrote this chapter with programmers in mind, not users of
261
programs---such as Emacs---that use Regex. We describe the Regex
262
library in its entirety, not how to write regular expressions that a
263
particular program understands.
266
@node Regular Expression Syntax, Common Operators, Overview, Top
267
@chapter Regular Expression Syntax
269
@cindex regular expressions, syntax of
270
@cindex syntax of regular expressions
272
@dfn{Characters} are things you can type. @dfn{Operators} are things in
273
a regular expression that match one or more characters. You compose
274
regular expressions from operators, which in turn you specify using one
277
Most characters represent what we call the match-self operator, i.e.,
278
they match themselves; we call these characters @dfn{ordinary}. Other
279
characters represent either all or parts of fancier operators; e.g.,
280
@samp{.} represents what we call the match-any-character operator
281
(which, no surprise, matches (almost) any character); we call these
282
characters @dfn{special}. Two different things determine what
283
characters represent what operators:
287
the regular expression syntax your program has told the Regex library to
291
the context of the character in the regular expression.
294
In the following sections, we describe these things in more detail.
298
* Predefined Syntaxes::
299
* Collating Elements vs. Characters::
300
* The Backslash Character::
304
@node Syntax Bits, Predefined Syntaxes, , Regular Expression Syntax
309
In any particular syntax for regular expressions, some characters are
310
always special, others are sometimes special, and others are never
311
special. The particular syntax that Regex recognizes for a given
312
regular expression depends on the value in the @code{syntax} field of
313
the pattern buffer of that regular expression.
315
You get a pattern buffer by compiling a regular expression. @xref{GNU
316
Pattern Buffers}, and @ref{POSIX Pattern Buffers}, for more information
317
on pattern buffers. @xref{GNU Regular Expression Compiling}, @ref{POSIX
318
Regular Expression Compiling}, and @ref{BSD Regular Expression
319
Compiling}, for more information on compiling.
321
Regex considers the value of the @code{syntax} field to be a collection
322
of bits; we refer to these bits as @dfn{syntax bits}. In most cases,
323
they affect what characters represent what operators. We describe the
324
meanings of the operators to which we refer in @ref{Common Operators},
325
@ref{GNU Operators}, and @ref{GNU Emacs Operators}.
327
For reference, here is the complete list of syntax bits, in alphabetical
332
@cnindex RE_BACKSLASH_ESCAPE_IN_LIST
333
@item RE_BACKSLASH_ESCAPE_IN_LISTS
334
If this bit is set, then @samp{\} inside a list (@pxref{List Operators}
335
quotes (makes ordinary, if it's special) the following character; if
336
this bit isn't set, then @samp{\} is an ordinary character inside lists.
337
(@xref{The Backslash Character}, for what `\' does outside of lists.)
339
@cnindex RE_BK_PLUS_QM
341
If this bit is set, then @samp{\+} represents the match-one-or-more
342
operator and @samp{\?} represents the match-zero-or-more operator; if
343
this bit isn't set, then @samp{+} represents the match-one-or-more
344
operator and @samp{?} represents the match-zero-or-one operator. This
345
bit is irrelevant if @code{RE_LIMITED_OPS} is set.
347
@cnindex RE_CHAR_CLASSES
348
@item RE_CHAR_CLASSES
349
If this bit is set, then you can use character classes in lists; if this
350
bit isn't set, then you can't.
352
@cnindex RE_CONTEXT_INDEP_ANCHORS
353
@item RE_CONTEXT_INDEP_ANCHORS
354
If this bit is set, then @samp{^} and @samp{$} are special anywhere outside
355
a list; if this bit isn't set, then these characters are special only in
356
certain contexts. @xref{Match-beginning-of-line Operator}, and
357
@ref{Match-end-of-line Operator}.
359
@cnindex RE_CONTEXT_INDEP_OPS
360
@item RE_CONTEXT_INDEP_OPS
361
If this bit is set, then certain characters are special anywhere outside
362
a list; if this bit isn't set, then those characters are special only in
363
some contexts and are ordinary elsewhere. Specifically, if this bit
364
isn't set then @samp{*}, and (if the syntax bit @code{RE_LIMITED_OPS}
365
isn't set) @samp{+} and @samp{?} (or @samp{\+} and @samp{\?}, depending
366
on the syntax bit @code{RE_BK_PLUS_QM}) represent repetition operators
367
only if they're not first in a regular expression or just after an
368
open-group or alternation operator. The same holds for @samp{@{} (or
369
@samp{\@{}, depending on the syntax bit @code{RE_NO_BK_BRACES}) if
370
it is the beginning of a valid interval and the syntax bit
371
@code{RE_INTERVALS} is set.
373
@cnindex RE_CONTEXT_INVALID_OPS
374
@item RE_CONTEXT_INVALID_OPS
375
If this bit is set, then repetition and alternation operators can't be
376
in certain positions within a regular expression. Specifically, the
377
regular expression is invalid if it has:
382
a repetition operator first in the regular expression or just after a
383
match-beginning-of-line, open-group, or alternation operator; or
386
an alternation operator first or last in the regular expression, just
387
before a match-end-of-line operator, or just after an alternation or
392
If this bit isn't set, then you can put the characters representing the
393
repetition and alternation characters anywhere in a regular expression.
394
Whether or not they will in fact be operators in certain positions
395
depends on other syntax bits.
397
@cnindex RE_DOT_NEWLINE
399
If this bit is set, then the match-any-character operator matches
400
a newline; if this bit isn't set, then it doesn't.
402
@cnindex RE_DOT_NOT_NULL
403
@item RE_DOT_NOT_NULL
404
If this bit is set, then the match-any-character operator doesn't match
405
a null character; if this bit isn't set, then it does.
407
@cnindex RE_INTERVALS
409
If this bit is set, then Regex recognizes interval operators; if this bit
410
isn't set, then it doesn't.
412
@cnindex RE_LIMITED_OPS
414
If this bit is set, then Regex doesn't recognize the match-one-or-more,
415
match-zero-or-one or alternation operators; if this bit isn't set, then
418
@cnindex RE_NEWLINE_ALT
420
If this bit is set, then newline represents the alternation operator; if
421
this bit isn't set, then newline is ordinary.
423
@cnindex RE_NO_BK_BRACES
424
@item RE_NO_BK_BRACES
425
If this bit is set, then @samp{@{} represents the open-interval operator
426
and @samp{@}} represents the close-interval operator; if this bit isn't
427
set, then @samp{\@{} represents the open-interval operator and
428
@samp{\@}} represents the close-interval operator. This bit is relevant
429
only if @code{RE_INTERVALS} is set.
431
@cnindex RE_NO_BK_PARENS
432
@item RE_NO_BK_PARENS
433
If this bit is set, then @samp{(} represents the open-group operator and
434
@samp{)} represents the close-group operator; if this bit isn't set, then
435
@samp{\(} represents the open-group operator and @samp{\)} represents
436
the close-group operator.
438
@cnindex RE_NO_BK_REFS
440
If this bit is set, then Regex doesn't recognize @samp{\}@var{digit} as
441
the back reference operator; if this bit isn't set, then it does.
443
@cnindex RE_NO_BK_VBAR
445
If this bit is set, then @samp{|} represents the alternation operator;
446
if this bit isn't set, then @samp{\|} represents the alternation
447
operator. This bit is irrelevant if @code{RE_LIMITED_OPS} is set.
449
@cnindex RE_NO_EMPTY_RANGES
450
@item RE_NO_EMPTY_RANGES
451
If this bit is set, then a regular expression with a range whose ending
452
point collates lower than its starting point is invalid; if this bit
453
isn't set, then Regex considers such a range to be empty.
455
@cnindex RE_UNMATCHED_RIGHT_PAREN_ORD
456
@item RE_UNMATCHED_RIGHT_PAREN_ORD
457
If this bit is set and the regular expression has no matching open-group
458
operator, then Regex considers what would otherwise be a close-group
459
operator (based on how @code{RE_NO_BK_PARENS} is set) to match @samp{)}.
464
@node Predefined Syntaxes, Collating Elements vs. Characters, Syntax Bits, Regular Expression Syntax
465
@section Predefined Syntaxes
467
If you're programming with Regex, you can set a pattern buffer's
468
(@pxref{GNU Pattern Buffers}, and @ref{POSIX Pattern Buffers})
469
@code{syntax} field either to an arbitrary combination of syntax bits
470
(@pxref{Syntax Bits}) or else to the configurations defined by Regex.
471
These configurations define the syntaxes used by certain
472
programs---@sc{gnu} Emacs,
481
Egrep---in addition to syntaxes for @sc{posix} basic and extended
484
The predefined syntaxes--taken directly from @file{regex.h}---are:
487
#define RE_SYNTAX_EMACS 0
489
#define RE_SYNTAX_AWK \
490
(RE_BACKSLASH_ESCAPE_IN_LISTS | RE_DOT_NOT_NULL \
491
| RE_NO_BK_PARENS | RE_NO_BK_REFS \
492
| RE_NO_BK_VBAR | RE_NO_EMPTY_RANGES \
493
| RE_UNMATCHED_RIGHT_PAREN_ORD)
495
#define RE_SYNTAX_POSIX_AWK \
496
(RE_SYNTAX_POSIX_EXTENDED | RE_BACKSLASH_ESCAPE_IN_LISTS)
498
#define RE_SYNTAX_GREP \
499
(RE_BK_PLUS_QM | RE_CHAR_CLASSES \
500
| RE_HAT_LISTS_NOT_NEWLINE | RE_INTERVALS \
503
#define RE_SYNTAX_EGREP \
504
(RE_CHAR_CLASSES | RE_CONTEXT_INDEP_ANCHORS \
505
| RE_CONTEXT_INDEP_OPS | RE_HAT_LISTS_NOT_NEWLINE \
506
| RE_NEWLINE_ALT | RE_NO_BK_PARENS \
509
#define RE_SYNTAX_POSIX_EGREP \
510
(RE_SYNTAX_EGREP | RE_INTERVALS | RE_NO_BK_BRACES)
512
/* P1003.2/D11.2, section 4.20.7.1, lines 5078ff. */
513
#define RE_SYNTAX_ED RE_SYNTAX_POSIX_BASIC
515
#define RE_SYNTAX_SED RE_SYNTAX_POSIX_BASIC
517
/* Syntax bits common to both basic and extended POSIX regex syntax. */
518
#define _RE_SYNTAX_POSIX_COMMON \
519
(RE_CHAR_CLASSES | RE_DOT_NEWLINE | RE_DOT_NOT_NULL \
520
| RE_INTERVALS | RE_NO_EMPTY_RANGES)
522
#define RE_SYNTAX_POSIX_BASIC \
523
(_RE_SYNTAX_POSIX_COMMON | RE_BK_PLUS_QM)
525
/* Differs from ..._POSIX_BASIC only in that RE_BK_PLUS_QM becomes
526
RE_LIMITED_OPS, i.e., \? \+ \| are not recognized. Actually, this
527
isn't minimal, since other operators, such as \`, aren't disabled. */
528
#define RE_SYNTAX_POSIX_MINIMAL_BASIC \
529
(_RE_SYNTAX_POSIX_COMMON | RE_LIMITED_OPS)
531
#define RE_SYNTAX_POSIX_EXTENDED \
532
(_RE_SYNTAX_POSIX_COMMON | RE_CONTEXT_INDEP_ANCHORS \
533
| RE_CONTEXT_INDEP_OPS | RE_NO_BK_BRACES \
534
| RE_NO_BK_PARENS | RE_NO_BK_VBAR \
535
| RE_UNMATCHED_RIGHT_PAREN_ORD)
537
/* Differs from ..._POSIX_EXTENDED in that RE_CONTEXT_INVALID_OPS
538
replaces RE_CONTEXT_INDEP_OPS and RE_NO_BK_REFS is added. */
539
#define RE_SYNTAX_POSIX_MINIMAL_EXTENDED \
540
(_RE_SYNTAX_POSIX_COMMON | RE_CONTEXT_INDEP_ANCHORS \
541
| RE_CONTEXT_INVALID_OPS | RE_NO_BK_BRACES \
542
| RE_NO_BK_PARENS | RE_NO_BK_REFS \
543
| RE_NO_BK_VBAR | RE_UNMATCHED_RIGHT_PAREN_ORD)
546
@node Collating Elements vs. Characters, The Backslash Character, Predefined Syntaxes, Regular Expression Syntax
547
@section Collating Elements vs.@: Characters
549
@sc{posix} generalizes the notion of a character to that of a
550
collating element. It defines a @dfn{collating element} to be ``a
551
sequence of one or more bytes defined in the current collating sequence
552
as a unit of collation.''
554
This generalizes the notion of a character in
555
two ways. First, a single character can map into two or more collating
556
elements. For example, the German
563
collates as the collating element @samp{s} followed by another collating
564
element @samp{s}. Second, two or more characters can map into one
565
collating element. For example, the Spanish @samp{ll} collates after
566
@samp{l} and before @samp{m}.
568
Since @sc{posix}'s ``collating element'' preserves the essential idea of
569
a ``character,'' we use the latter, more familiar, term in this document.
571
@node The Backslash Character, , Collating Elements vs. Characters, Regular Expression Syntax
572
@section The Backslash Character
575
The @samp{\} character has one of four different meanings, depending on
576
the context in which you use it and what syntax bits are set
577
(@pxref{Syntax Bits}). It can: 1) stand for itself, 2) quote the next
578
character, 3) introduce an operator, or 4) do nothing.
582
It stands for itself inside a list
583
(@pxref{List Operators}) if the syntax bit
584
@code{RE_BACKSLASH_ESCAPE_IN_LISTS} is not set. For example, @samp{[\]}
585
would match @samp{\}.
588
It quotes (makes ordinary, if it's special) the next character when you
593
outside a list,@footnote{Sometimes
594
you don't have to explicitly quote special characters to make
595
them ordinary. For instance, most characters lose any special meaning
596
inside a list (@pxref{List Operators}). In addition, if the syntax bits
597
@code{RE_CONTEXT_INVALID_OPS} and @code{RE_CONTEXT_INDEP_OPS}
598
aren't set, then (for historical reasons) the matcher considers special
599
characters ordinary if they are in contexts where the operations they
600
represent make no sense; for example, then the match-zero-or-more
601
operator (represented by @samp{*}) matches itself in the regular
602
expression @samp{*foo} because there is no preceding expression on which
603
it can operate. It is poor practice, however, to depend on this
604
behavior; if you want a special character to be ordinary outside a list,
605
it's better to always quote it, regardless.} or
608
inside a list and the syntax bit @code{RE_BACKSLASH_ESCAPE_IN_LISTS} is set.
613
It introduces an operator when followed by certain ordinary
614
characters---sometimes only when certain syntax bits are set. See the
615
cases @code{RE_BK_PLUS_QM}, @code{RE_NO_BK_BRACES}, @code{RE_NO_BK_VAR},
616
@code{RE_NO_BK_PARENS}, @code{RE_NO_BK_REF} in @ref{Syntax Bits}. Also:
620
@samp{\b} represents the match-word-boundary operator
621
(@pxref{Match-word-boundary Operator}).
624
@samp{\B} represents the match-within-word operator
625
(@pxref{Match-within-word Operator}).
628
@samp{\<} represents the match-beginning-of-word operator @*
629
(@pxref{Match-beginning-of-word Operator}).
632
@samp{\>} represents the match-end-of-word operator
633
(@pxref{Match-end-of-word Operator}).
636
@samp{\w} represents the match-word-constituent operator
637
(@pxref{Match-word-constituent Operator}).
640
@samp{\W} represents the match-non-word-constituent operator
641
(@pxref{Match-non-word-constituent Operator}).
644
@samp{\`} represents the match-beginning-of-buffer
645
operator and @samp{\'} represents the match-end-of-buffer operator
646
(@pxref{Buffer Operators}).
649
If Regex was compiled with the C preprocessor symbol @code{emacs}
650
defined, then @samp{\s@var{class}} represents the match-syntactic-class
651
operator and @samp{\S@var{class}} represents the
652
match-not-syntactic-class operator (@pxref{Syntactic Class Operators}).
657
In all other cases, Regex ignores @samp{\}. For example,
658
@samp{\n} matches @samp{n}.
662
@node Common Operators, GNU Operators, Regular Expression Syntax, Top
663
@chapter Common Operators
665
You compose regular expressions from operators. In the following
666
sections, we describe the regular expression operators specified by
667
@sc{posix}; @sc{gnu} also uses these. Most operators have more than one
668
representation as characters. @xref{Regular Expression Syntax}, for
669
what characters represent what operators under what circumstances.
671
For most operators that can be represented in two ways, one
672
representation is a single character and the other is that character
673
preceded by @samp{\}. For example, either @samp{(} or @samp{\(}
674
represents the open-group operator. Which one does depends on the
675
setting of a syntax bit, in this case @code{RE_NO_BK_PARENS}. Why is
676
this so? Historical reasons dictate some of the varying
677
representations, while @sc{posix} dictates others.
679
Finally, almost all characters lose any special meaning inside a list
680
(@pxref{List Operators}).
683
* Match-self Operator:: Ordinary characters.
684
* Match-any-character Operator:: .
685
* Concatenation Operator:: Juxtaposition.
686
* Repetition Operators:: * + ? @{@}
687
* Alternation Operator:: |
688
* List Operators:: [...] [^...]
689
* Grouping Operators:: (...)
690
* Back-reference Operator:: \digit
691
* Anchoring Operators:: ^ $
694
@node Match-self Operator, Match-any-character Operator, , Common Operators
695
@section The Match-self Operator (@var{ordinary character})
697
This operator matches the character itself. All ordinary characters
698
(@pxref{Regular Expression Syntax}) represent this operator. For
699
example, @samp{f} is always an ordinary character, so the regular
700
expression @samp{f} matches only the string @samp{f}. In
701
particular, it does @emph{not} match the string @samp{ff}.
703
@node Match-any-character Operator, Concatenation Operator, Match-self Operator, Common Operators
704
@section The Match-any-character Operator (@code{.})
708
This operator matches any single printing or nonprinting character
709
except it won't match a:
713
if the syntax bit @code{RE_DOT_NEWLINE} isn't set.
716
if the syntax bit @code{RE_DOT_NOT_NULL} is set.
720
The @samp{.} (period) character represents this operator. For example,
721
@samp{a.b} matches any three-character string beginning with @samp{a}
722
and ending with @samp{b}.
724
@node Concatenation Operator, Repetition Operators, Match-any-character Operator, Common Operators
725
@section The Concatenation Operator
727
This operator concatenates two regular expressions @var{a} and @var{b}.
728
No character represents this operator; you simply put @var{b} after
729
@var{a}. The result is a regular expression that will match a string if
730
@var{a} matches its first part and @var{b} matches the rest. For
731
example, @samp{xy} (two match-self operators) matches @samp{xy}.
733
@node Repetition Operators, Alternation Operator, Concatenation Operator, Common Operators
734
@section Repetition Operators
736
Repetition operators repeat the preceding regular expression a specified
740
* Match-zero-or-more Operator:: *
741
* Match-one-or-more Operator:: +
742
* Match-zero-or-one Operator:: ?
743
* Interval Operators:: @{@}
746
@node Match-zero-or-more Operator, Match-one-or-more Operator, , Repetition Operators
747
@subsection The Match-zero-or-more Operator (@code{*})
751
This operator repeats the smallest possible preceding regular expression
752
as many times as necessary (including zero) to match the pattern.
753
@samp{*} represents this operator. For example, @samp{o*}
754
matches any string made up of zero or more @samp{o}s. Since this
755
operator operates on the smallest preceding regular expression,
756
@samp{fo*} has a repeating @samp{o}, not a repeating @samp{fo}. So,
757
@samp{fo*} matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
759
Since the match-zero-or-more operator is a suffix operator, it may be
760
useless as such when no regular expression precedes it. This is the
765
is first in a regular expression, or
768
follows a match-beginning-of-line, open-group, or alternation
774
Three different things can happen in these cases:
778
If the syntax bit @code{RE_CONTEXT_INVALID_OPS} is set, then the
779
regular expression is invalid.
782
If @code{RE_CONTEXT_INVALID_OPS} isn't set, but
783
@code{RE_CONTEXT_INDEP_OPS} is, then @samp{*} represents the
784
match-zero-or-more operator (which then operates on the empty string).
787
Otherwise, @samp{*} is ordinary.
792
The matcher processes a match-zero-or-more operator by first matching as
793
many repetitions of the smallest preceding regular expression as it can.
794
Then it continues to match the rest of the pattern.
796
If it can't match the rest of the pattern, it backtracks (as many times
797
as necessary), each time discarding one of the matches until it can
798
either match the entire pattern or be certain that it cannot get a
799
match. For example, when matching @samp{ca*ar} against @samp{caaar},
800
the matcher first matches all three @samp{a}s of the string with the
801
@samp{a*} of the regular expression. However, it cannot then match the
802
final @samp{ar} of the regular expression against the final @samp{r} of
803
the string. So it backtracks, discarding the match of the last @samp{a}
804
in the string. It can then match the remaining @samp{ar}.
807
@node Match-one-or-more Operator, Match-zero-or-one Operator, Match-zero-or-more Operator, Repetition Operators
808
@subsection The Match-one-or-more Operator (@code{+} or @code{\+})
812
If the syntax bit @code{RE_LIMITED_OPS} is set, then Regex doesn't recognize
813
this operator. Otherwise, if the syntax bit @code{RE_BK_PLUS_QM} isn't
814
set, then @samp{+} represents this operator; if it is, then @samp{\+}
817
This operator is similar to the match-zero-or-more operator except that
818
it repeats the preceding regular expression at least once;
819
@pxref{Match-zero-or-more Operator}, for what it operates on, how some
820
syntax bits affect it, and how Regex backtracks to match it.
822
For example, supposing that @samp{+} represents the match-one-or-more
823
operator; then @samp{ca+r} matches, e.g., @samp{car} and
824
@samp{caaaar}, but not @samp{cr}.
826
@node Match-zero-or-one Operator, Interval Operators, Match-one-or-more Operator, Repetition Operators
827
@subsection The Match-zero-or-one Operator (@code{?} or @code{\?})
830
If the syntax bit @code{RE_LIMITED_OPS} is set, then Regex doesn't
831
recognize this operator. Otherwise, if the syntax bit
832
@code{RE_BK_PLUS_QM} isn't set, then @samp{?} represents this operator;
833
if it is, then @samp{\?} does.
835
This operator is similar to the match-zero-or-more operator except that
836
it repeats the preceding regular expression once or not at all;
837
@pxref{Match-zero-or-more Operator}, to see what it operates on, how
838
some syntax bits affect it, and how Regex backtracks to match it.
840
For example, supposing that @samp{?} represents the match-zero-or-one
841
operator; then @samp{ca?r} matches both @samp{car} and @samp{cr}, but
844
@node Interval Operators, , Match-zero-or-one Operator, Repetition Operators
845
@subsection Interval Operators (@code{@{} @dots{} @code{@}} or @code{\@{} @dots{} @code{\@}})
847
@cindex interval expression
853
If the syntax bit @code{RE_INTERVALS} is set, then Regex recognizes
854
@dfn{interval expressions}. They repeat the smallest possible preceding
855
regular expression a specified number of times.
857
If the syntax bit @code{RE_NO_BK_BRACES} is set, @samp{@{} represents
858
the @dfn{open-interval operator} and @samp{@}} represents the
859
@dfn{close-interval operator} ; otherwise, @samp{\@{} and @samp{\@}} do.
861
Specifically, supposing that @samp{@{} and @samp{@}} represent the
862
open-interval and close-interval operators; then:
865
@item @{@var{count}@}
866
matches exactly @var{count} occurrences of the preceding regular
870
matches @var{min} or more occurrences of the preceding regular
873
@item @{@var{min, max}@}
874
matches at least @var{min} but no more than @var{max} occurrences of
875
the preceding regular expression.
879
The interval expression (but not necessarily the regular expression that
880
contains it) is invalid if:
884
@var{min} is greater than @var{max}, or
887
any of @var{count}, @var{min}, or @var{max} are outside the range
888
zero to @code{RE_DUP_MAX} (which symbol @file{regex.h}
893
If the interval expression is invalid and the syntax bit
894
@code{RE_NO_BK_BRACES} is set, then Regex considers all the
895
characters in the would-be interval to be ordinary. If that bit
896
isn't set, then the regular expression is invalid.
898
If the interval expression is valid but there is no preceding regular
899
expression on which to operate, then if the syntax bit
900
@code{RE_CONTEXT_INVALID_OPS} is set, the regular expression is invalid.
901
If that bit isn't set, then Regex considers all the characters---other
902
than backslashes, which it ignores---in the would-be interval to be
906
@node Alternation Operator, List Operators, Repetition Operators, Common Operators
907
@section The Alternation Operator (@code{|} or @code{\|})
911
@cindex alternation operator
914
If the syntax bit @code{RE_LIMITED_OPS} is set, then Regex doesn't
915
recognize this operator. Otherwise, if the syntax bit
916
@code{RE_NO_BK_VBAR} is set, then @samp{|} represents this operator;
917
otherwise, @samp{\|} does.
919
Alternatives match one of a choice of regular expressions:
920
if you put the character(s) representing the alternation operator between
921
any two regular expressions @var{a} and @var{b}, the result matches
922
the union of the strings that @var{a} and @var{b} match. For
923
example, supposing that @samp{|} is the alternation operator, then
924
@samp{foo|bar|quux} would match any of @samp{foo}, @samp{bar} or
928
@c Nobody needs to disallow empty alternatives any more.
929
If the syntax bit @code{RE_NO_EMPTY_ALTS} is set, then if either of the regular
930
expressions @var{a} or @var{b} is empty, the
931
regular expression is invalid. More precisely, if this syntax bit is
932
set, then the alternation operator can't:
936
be first or last in a regular expression;
939
follow either another alternation operator or an open-group operator
940
(@pxref{Grouping Operators}); or
943
precede a close-group operator.
948
For example, supposing @samp{(} and @samp{)} represent the open and
949
close-group operators, then @samp{|foo}, @samp{foo|}, @samp{foo||bar},
950
@samp{foo(|bar)}, and @samp{(foo|)bar} would all be invalid.
953
The alternation operator operates on the @emph{largest} possible
954
surrounding regular expressions. (Put another way, it has the lowest
955
precedence of any regular expression operator.)
956
Thus, the only way you can
957
delimit its arguments is to use grouping. For example, if @samp{(} and
958
@samp{)} are the open and close-group operators, then @samp{fo(o|b)ar}
959
would match either @samp{fooar} or @samp{fobar}. (@samp{foo|bar} would
960
match @samp{foo} or @samp{bar}.)
963
The matcher usually tries all combinations of alternatives so as to
964
match the longest possible string. For example, when matching
965
@samp{(fooq|foo)*(qbarquux|bar)} against @samp{fooqbarquux}, it cannot
966
take, say, the first (``depth-first'') combination it could match, since
967
then it would be content to match just @samp{fooqbar}.
969
@comment xx something about leftmost-longest
972
@node List Operators, Grouping Operators, Alternation Operator, Common Operators
973
@section List Operators (@code{[} @dots{} @code{]} and @code{[^} @dots{} @code{]})
975
@cindex matching list
982
@cindex nonmatching list
983
@cindex matching newline
984
@cindex bracket expression
986
@dfn{Lists}, also called @dfn{bracket expressions}, are a set of one or
987
more items. An @dfn{item} is a character,
989
(These get added when they get implemented.)
990
a collating symbol, an equivalence class expression,
992
a character class expression, or a range expression. The syntax bits
993
affect which kinds of items you can put in a list. We explain the last
994
two items in subsections below. Empty lists are invalid.
996
A @dfn{matching list} matches a single character represented by one of
997
the list items. You form a matching list by enclosing one or more items
998
within an @dfn{open-matching-list operator} (represented by @samp{[})
999
and a @dfn{close-list operator} (represented by @samp{]}).
1001
For example, @samp{[ab]} matches either @samp{a} or @samp{b}.
1002
@samp{[ad]*} matches the empty string and any string composed of just
1003
@samp{a}s and @samp{d}s in any order. Regex considers invalid a regular
1004
expression with a @samp{[} but no matching
1007
@dfn{Nonmatching lists} are similar to matching lists except that they
1008
match a single character @emph{not} represented by one of the list
1009
items. You use an @dfn{open-nonmatching-list operator} (represented by
1010
@samp{[^}@footnote{Regex therefore doesn't consider the @samp{^} to be
1011
the first character in the list. If you put a @samp{^} character first
1012
in (what you think is) a matching list, you'll turn it into a
1013
nonmatching list.}) instead of an open-matching-list operator to start a
1016
For example, @samp{[^ab]} matches any character except @samp{a} or
1019
If the @code{posix_newline} field in the pattern buffer (@pxref{GNU
1020
Pattern Buffers} is set, then nonmatching lists do not match a newline.
1022
Most characters lose any special meaning inside a list. The special
1023
characters inside a list follow.
1027
ends the list if it's not the first list item. So, if you want to make
1028
the @samp{]} character a list item, you must put it first.
1031
quotes the next character if the syntax bit @code{RE_BACKSLASH_ESCAPE_IN_LISTS} is
1035
Put these in if they get implemented.
1038
represents the open-collating-symbol operator (@pxref{Collating Symbol
1042
represents the close-collating-symbol operator.
1045
represents the open-equivalence-class operator (@pxref{Equivalence Class
1049
represents the close-equivalence-class operator.
1054
represents the open-character-class operator (@pxref{Character Class
1055
Operators}) if the syntax bit @code{RE_CHAR_CLASSES} is set and what
1056
follows is a valid character class expression.
1059
represents the close-character-class operator if the syntax bit
1060
@code{RE_CHAR_CLASSES} is set and what precedes it is an
1061
open-character-class operator followed by a valid character class name.
1064
represents the range operator (@pxref{Range Operator}) if it's
1065
not first or last in a list or the ending point of a range.
1070
All other characters are ordinary. For example, @samp{[.*]} matches
1071
@samp{.} and @samp{*}.
1074
* Character Class Operators:: [:class:]
1075
* Range Operator:: start-end
1079
(If collating symbols and equivalence class expressions get implemented,
1082
node Collating Symbol Operators
1083
subsubsection Collating Symbol Operators (@code{[.} @dots{} @code{.]})
1085
If the syntax bit @code{XX} is set, then you can represent
1086
collating symbols inside lists. You form a @dfn{collating symbol} by
1087
putting a collating element between an @dfn{open-collating-symbol
1088
operator} and an @dfn{close-collating-symbol operator}. @samp{[.}
1089
represents the open-collating-symbol operator and @samp{.]} represents
1090
the close-collating-symbol operator. For example, if @samp{ll} is a
1091
collating element, then @samp{[[.ll.]]} would match @samp{ll}.
1093
node Equivalence Class Operators
1094
subsubsection Equivalence Class Operators (@code{[=} @dots{} @code{=]})
1095
@cindex equivalence class expression in regex
1096
@cindex @samp{[=} in regex
1097
@cindex @samp{=]} in regex
1099
If the syntax bit @code{XX} is set, then Regex recognizes equivalence class
1100
expressions inside lists. A @dfn{equivalence class expression} is a set
1101
of collating elements which all belong to the same equivalence class.
1102
You form an equivalence class expression by putting a collating
1103
element between an @dfn{open-equivalence-class operator} and a
1104
@dfn{close-equivalence-class operator}. @samp{[=} represents the
1105
open-equivalence-class operator and @samp{=]} represents the
1106
close-equivalence-class operator. For example, if @samp{a} and @samp{A}
1107
were an equivalence class, then both @samp{[[=a=]]} and @samp{[[=A=]]}
1108
would match both @samp{a} and @samp{A}. If the collating element in an
1109
equivalence class expression isn't part of an equivalence class, then
1110
the matcher considers the equivalence class expression to be a collating
1115
@node Character Class Operators, Range Operator, , List Operators
1116
@subsection Character Class Operators (@code{[:} @dots{} @code{:]})
1118
@cindex character classes
1119
@cindex @samp{[:} in regex
1120
@cindex @samp{:]} in regex
1122
If the syntax bit @code{RE_CHARACTER_CLASSES} is set, then Regex
1123
recognizes character class expressions inside lists. A @dfn{character
1124
class expression} matches one character from a given class. You form a
1125
character class expression by putting a character class name between an
1126
@dfn{open-character-class operator} (represented by @samp{[:}) and a
1127
@dfn{close-character-class operator} (represented by @samp{:]}). The
1128
character class names and their meanings are:
1139
system-dependent; for @sc{gnu}, a space or tab
1142
control characters (in the @sc{ascii} encoding, code 0177 and codes
1149
same as @code{print} except omits space
1155
printable characters (in the @sc{ascii} encoding, space
1156
tilde---codes 040 through 0176)
1159
neither control nor alphanumeric characters
1162
space, carriage return, newline, vertical tab, and form feed
1168
hexadecimal digits: @code{0}--@code{9}, @code{a}--@code{f}, @code{A}--@code{F}
1173
These correspond to the definitions in the C library's @file{<ctype.h>}
1174
facility. For example, @samp{[:alpha:]} corresponds to the standard
1175
facility @code{isalpha}. Regex recognizes character class expressions
1176
only inside of lists; so @samp{[[:alpha:]]} matches any letter, but
1177
@samp{[:alpha:]} outside of a bracket expression and not followed by a
1178
repetition operator matches just itself.
1180
@node Range Operator, , Character Class Operators, List Operators
1181
@subsection The Range Operator (@code{-})
1183
Regex recognizes @dfn{range expressions} inside a list. They represent
1185
that fall between two elements in the current collating sequence. You
1186
form a range expression by putting a @dfn{range operator} between two
1188
(If these get implemented, then substitute this for ``characters.'')
1189
of any of the following: characters, collating elements, collating symbols,
1190
and equivalence class expressions. The starting point of the range and
1191
the ending point of the range don't have to be the same kind of item,
1192
e.g., the starting point could be a collating element and the ending
1193
point could be an equivalence class expression. If a range's ending
1194
point is an equivalence class, then all the collating elements in that
1195
class will be in the range.
1197
characters.@footnote{You can't use a character class for the starting
1198
or ending point of a range, since a character class is not a single
1199
character.} @samp{-} represents the range operator. For example,
1200
@samp{a-f} within a list represents all the characters from @samp{a}
1204
If the syntax bit @code{RE_NO_EMPTY_RANGES} is set, then if the range's
1205
ending point collates less than its starting point, the range (and the
1206
regular expression containing it) is invalid. For example, the regular
1207
expression @samp{[z-a]} would be invalid. If this bit isn't set, then
1208
Regex considers such a range to be empty.
1210
Since @samp{-} represents the range operator, if you want to make a
1211
@samp{-} character itself
1212
a list item, you must do one of the following:
1216
Put the @samp{-} either first or last in the list.
1219
Include a range whose starting point collates strictly lower than
1220
@samp{-} and whose ending point collates equal or higher. Unless a
1221
range is the first item in a list, a @samp{-} can't be its starting
1222
point, but @emph{can} be its ending point. That is because Regex
1223
considers @samp{-} to be the range operator unless it is preceded by
1224
another @samp{-}. For example, in the @sc{ascii} encoding, @samp{)},
1225
@samp{*}, @samp{+}, @samp{,}, @samp{-}, @samp{.}, and @samp{/} are
1226
contiguous characters in the collating sequence. You might think that
1227
@samp{[)-+--/]} has two ranges: @samp{)-+} and @samp{--/}. Rather, it
1228
has the ranges @samp{)-+} and @samp{+--}, plus the character @samp{/}, so
1229
it matches, e.g., @samp{,}, not @samp{.}.
1232
Put a range whose starting point is @samp{-} first in the list.
1236
For example, @samp{[-a-z]} matches a lowercase letter or a hyphen (in
1237
English, in @sc{ascii}).
1240
@node Grouping Operators, Back-reference Operator, List Operators, Common Operators
1241
@section Grouping Operators (@code{(} @dots{} @code{)} or @code{\(} @dots{} @code{\)})
1248
@cindex subexpressions
1249
@cindex parenthesizing
1251
A @dfn{group}, also known as a @dfn{subexpression}, consists of an
1252
@dfn{open-group operator}, any number of other operators, and a
1253
@dfn{close-group operator}. Regex treats this sequence as a unit, just
1254
as mathematics and programming languages treat a parenthesized
1255
expression as a unit.
1257
Therefore, using @dfn{groups}, you can:
1261
delimit the argument(s) to an alternation operator (@pxref{Alternation
1262
Operator}) or a repetition operator (@pxref{Repetition
1266
keep track of the indices of the substring that matched a given group.
1267
@xref{Using Registers}, for a precise explanation.
1272
use the back-reference operator (@pxref{Back-reference Operator}).
1275
use registers (@pxref{Using Registers}).
1281
If the syntax bit @code{RE_NO_BK_PARENS} is set, then @samp{(} represents
1282
the open-group operator and @samp{)} represents the
1283
close-group operator; otherwise, @samp{\(} and @samp{\)} do.
1285
If the syntax bit @code{RE_UNMATCHED_RIGHT_PAREN_ORD} is set and a
1286
close-group operator has no matching open-group operator, then Regex
1287
considers it to match @samp{)}.
1290
@node Back-reference Operator, Anchoring Operators, Grouping Operators, Common Operators
1291
@section The Back-reference Operator (@dfn{\}@var{digit})
1293
@cindex back references
1295
If the syntax bit @code{RE_NO_BK_REF} isn't set, then Regex recognizes
1296
back references. A back reference matches a specified preceding group.
1297
The back reference operator is represented by @samp{\@var{digit}}
1298
anywhere after the end of a regular expression's @w{@var{digit}-th}
1299
group (@pxref{Grouping Operators}).
1301
@var{digit} must be between @samp{1} and @samp{9}. The matcher assigns
1302
numbers 1 through 9 to the first nine groups it encounters. By using
1303
one of @samp{\1} through @samp{\9} after the corresponding group's
1304
close-group operator, you can match a substring identical to the
1305
one that the group does.
1307
Back references match according to the following (in all examples below,
1308
@samp{(} represents the open-group, @samp{)} the close-group, @samp{@{}
1309
the open-interval and @samp{@}} the close-interval operator):
1313
If the group matches a substring, the back reference matches an
1314
identical substring. For example, @samp{(a)\1} matches @samp{aa} and
1315
@samp{(bana)na\1bo\1} matches @samp{bananabanabobana}. Likewise,
1316
@samp{(.*)\1} matches any (newline-free if the syntax bit
1317
@code{RE_DOT_NEWLINE} isn't set) string that is composed of two
1318
identical halves; the @samp{(.*)} matches the first half and the
1319
@samp{\1} matches the second half.
1322
If the group matches more than once (as it might if followed
1323
by, e.g., a repetition operator), then the back reference matches the
1324
substring the group @emph{last} matched. For example,
1325
@samp{((a*)b)*\1\2} matches @samp{aabababa}; first @w{group 1} (the
1326
outer one) matches @samp{aab} and @w{group 2} (the inner one) matches
1327
@samp{aa}. Then @w{group 1} matches @samp{ab} and @w{group 2} matches
1328
@samp{a}. So, @samp{\1} matches @samp{ab} and @samp{\2} matches
1332
If the group doesn't participate in a match, i.e., it is part of an
1333
alternative not taken or a repetition operator allows zero repetitions
1334
of it, then the back reference makes the whole match fail. For example,
1335
@samp{(one()|two())-and-(three\2|four\3)} matches @samp{one-and-three}
1336
and @samp{two-and-four}, but not @samp{one-and-four} or
1337
@samp{two-and-three}. For example, if the pattern matches
1338
@samp{one-and-}, then its @w{group 2} matches the empty string and its
1339
@w{group 3} doesn't participate in the match. So, if it then matches
1340
@samp{four}, then when it tries to back reference @w{group 3}---which it
1341
will attempt to do because @samp{\3} follows the @samp{four}---the match
1342
will fail because @w{group 3} didn't participate in the match.
1346
You can use a back reference as an argument to a repetition operator. For
1347
example, @samp{(a(b))\2*} matches @samp{a} followed by two or more
1348
@samp{b}s. Similarly, @samp{(a(b))\2@{3@}} matches @samp{abbbb}.
1350
If there is no preceding @w{@var{digit}-th} subexpression, the regular
1351
expression is invalid.
1354
@node Anchoring Operators, , Back-reference Operator, Common Operators
1355
@section Anchoring Operators
1358
@cindex regexp anchoring
1360
These operators can constrain a pattern to match only at the beginning or
1361
end of the entire string or at the beginning or end of a line.
1364
* Match-beginning-of-line Operator:: ^
1365
* Match-end-of-line Operator:: $
1369
@node Match-beginning-of-line Operator, Match-end-of-line Operator, , Anchoring Operators
1370
@subsection The Match-beginning-of-line Operator (@code{^})
1373
@cindex beginning-of-line operator
1376
This operator can match the empty string either at the beginning of the
1377
string or after a newline character. Thus, it is said to @dfn{anchor}
1378
the pattern to the beginning of a line.
1380
In the cases following, @samp{^} represents this operator. (Otherwise,
1381
@samp{^} is ordinary.)
1386
It (the @samp{^}) is first in the pattern, as in @samp{^foo}.
1388
@cnindex RE_CONTEXT_INDEP_ANCHORS @r{(and @samp{^})}
1390
The syntax bit @code{RE_CONTEXT_INDEP_ANCHORS} is set, and it is outside
1391
a bracket expression.
1393
@cindex open-group operator and @samp{^}
1394
@cindex alternation operator and @samp{^}
1396
It follows an open-group or alternation operator, as in @samp{a\(^b\)}
1397
and @samp{a\|^b}. @xref{Grouping Operators}, and @ref{Alternation
1402
These rules imply that some valid patterns containing @samp{^} cannot be
1403
matched; for example, @samp{foo^bar} if @code{RE_CONTEXT_INDEP_ANCHORS}
1406
@vindex not_bol @r{field in pattern buffer}
1407
If the @code{not_bol} field is set in the pattern buffer (@pxref{GNU
1408
Pattern Buffers}), then @samp{^} fails to match at the beginning of the
1409
string. @xref{POSIX Matching}, for when you might find this useful.
1411
@vindex newline_anchor @r{field in pattern buffer}
1412
If the @code{newline_anchor} field is set in the pattern buffer, then
1413
@samp{^} fails to match after a newline. This is useful when you do not
1414
regard the string to be matched as broken into lines.
1417
@node Match-end-of-line Operator, , Match-beginning-of-line Operator, Anchoring Operators
1418
@subsection The Match-end-of-line Operator (@code{$})
1421
@cindex end-of-line operator
1424
This operator can match the empty string either at the end of
1425
the string or before a newline character in the string. Thus, it is
1426
said to @dfn{anchor} the pattern to the end of a line.
1428
It is always represented by @samp{$}. For example, @samp{foo$} usually
1429
matches, e.g., @samp{foo} and, e.g., the first three characters of
1432
Its interaction with the syntax bits and pattern buffer fields is
1433
exactly the dual of @samp{^}'s; see the previous section. (That is,
1434
``beginning'' becomes ``end'', ``next'' becomes ``previous'', and
1435
``after'' becomes ``before''.)
1438
@node GNU Operators, GNU Emacs Operators, Common Operators, Top
1439
@chapter GNU Operators
1441
Following are operators that @sc{gnu} defines (and @sc{posix} doesn't).
1445
* Buffer Operators::
1448
@node Word Operators, Buffer Operators, , GNU Operators
1449
@section Word Operators
1451
The operators in this section require Regex to recognize parts of words.
1452
Regex uses a syntax table to determine whether or not a character is
1453
part of a word, i.e., whether or not it is @dfn{word-constituent}.
1456
* Non-Emacs Syntax Tables::
1457
* Match-word-boundary Operator:: \b
1458
* Match-within-word Operator:: \B
1459
* Match-beginning-of-word Operator:: \<
1460
* Match-end-of-word Operator:: \>
1461
* Match-word-constituent Operator:: \w
1462
* Match-non-word-constituent Operator:: \W
1465
@node Non-Emacs Syntax Tables, Match-word-boundary Operator, , Word Operators
1466
@subsection Non-Emacs Syntax Tables
1468
A @dfn{syntax table} is an array indexed by the characters in your
1469
character set. In the @sc{ascii} encoding, therefore, a syntax table
1470
has 256 elements. Regex always uses a @code{char *} variable
1471
@code{re_syntax_table} as its syntax table. In some cases, it
1472
initializes this variable and in others it expects you to initialize it.
1476
If Regex is compiled with the preprocessor symbols @code{emacs} and
1477
@code{SYNTAX_TABLE} both undefined, then Regex allocates
1478
@code{re_syntax_table} and initializes an element @var{i} either to
1479
@code{Sword} (which it defines) if @var{i} is a letter, number, or
1480
@samp{_}, or to zero if it's not.
1483
If Regex is compiled with @code{emacs} undefined but @code{SYNTAX_TABLE}
1484
defined, then Regex expects you to define a @code{char *} variable
1485
@code{re_syntax_table} to be a valid syntax table.
1488
@xref{Emacs Syntax Tables}, for what happens when Regex is compiled with
1489
the preprocessor symbol @code{emacs} defined.
1493
@node Match-word-boundary Operator, Match-within-word Operator, Non-Emacs Syntax Tables, Word Operators
1494
@subsection The Match-word-boundary Operator (@code{\b})
1497
@cindex word boundaries, matching
1499
This operator (represented by @samp{\b}) matches the empty string at
1500
either the beginning or the end of a word. For example, @samp{\brat\b}
1501
matches the separate word @samp{rat}.
1503
@node Match-within-word Operator, Match-beginning-of-word Operator, Match-word-boundary Operator, Word Operators
1504
@subsection The Match-within-word Operator (@code{\B})
1508
This operator (represented by @samp{\B}) matches the empty string within
1509
a word. For example, @samp{c\Brat\Be} matches @samp{crate}, but
1510
@samp{dirty \Brat} doesn't match @samp{dirty rat}.
1512
@node Match-beginning-of-word Operator, Match-end-of-word Operator, Match-within-word Operator, Word Operators
1513
@subsection The Match-beginning-of-word Operator (@code{\<})
1517
This operator (represented by @samp{\<}) matches the empty string at the
1518
beginning of a word.
1520
@node Match-end-of-word Operator, Match-word-constituent Operator, Match-beginning-of-word Operator, Word Operators
1521
@subsection The Match-end-of-word Operator (@code{\>})
1525
This operator (represented by @samp{\>}) matches the empty string at the
1528
@node Match-word-constituent Operator, Match-non-word-constituent Operator, Match-end-of-word Operator, Word Operators
1529
@subsection The Match-word-constituent Operator (@code{\w})
1533
This operator (represented by @samp{\w}) matches any word-constituent
1536
@node Match-non-word-constituent Operator, , Match-word-constituent Operator, Word Operators
1537
@subsection The Match-non-word-constituent Operator (@code{\W})
1541
This operator (represented by @samp{\W}) matches any character that is
1542
not word-constituent.
1545
@node Buffer Operators, , Word Operators, GNU Operators
1546
@section Buffer Operators
1548
Following are operators which work on buffers. In Emacs, a @dfn{buffer}
1549
is, naturally, an Emacs buffer. For other programs, Regex considers the
1550
entire string to be matched as the buffer.
1553
* Match-beginning-of-buffer Operator:: \`
1554
* Match-end-of-buffer Operator:: \'
1558
@node Match-beginning-of-buffer Operator, Match-end-of-buffer Operator, , Buffer Operators
1559
@subsection The Match-beginning-of-buffer Operator (@code{\`})
1563
This operator (represented by @samp{\`}) matches the empty string at the
1564
beginning of the buffer.
1566
@node Match-end-of-buffer Operator, , Match-beginning-of-buffer Operator, Buffer Operators
1567
@subsection The Match-end-of-buffer Operator (@code{\'})
1571
This operator (represented by @samp{\'}) matches the empty string at the
1575
@node GNU Emacs Operators, What Gets Matched?, GNU Operators, Top
1576
@chapter GNU Emacs Operators
1578
Following are operators that @sc{gnu} defines (and @sc{posix} doesn't)
1579
that you can use only when Regex is compiled with the preprocessor
1580
symbol @code{emacs} defined.
1583
* Syntactic Class Operators::
1587
@node Syntactic Class Operators, , , GNU Emacs Operators
1588
@section Syntactic Class Operators
1590
The operators in this section require Regex to recognize the syntactic
1591
classes of characters. Regex uses a syntax table to determine this.
1594
* Emacs Syntax Tables::
1595
* Match-syntactic-class Operator:: \sCLASS
1596
* Match-not-syntactic-class Operator:: \SCLASS
1599
@node Emacs Syntax Tables, Match-syntactic-class Operator, , Syntactic Class Operators
1600
@subsection Emacs Syntax Tables
1602
A @dfn{syntax table} is an array indexed by the characters in your
1603
character set. In the @sc{ascii} encoding, therefore, a syntax table
1606
If Regex is compiled with the preprocessor symbol @code{emacs} defined,
1607
then Regex expects you to define and initialize the variable
1608
@code{re_syntax_table} to be an Emacs syntax table. Emacs' syntax
1609
tables are more complicated than Regex's own (@pxref{Non-Emacs Syntax
1610
Tables}). @xref{Syntax, , Syntax, emacs, The GNU Emacs User's Manual},
1611
for a description of Emacs' syntax tables.
1613
@node Match-syntactic-class Operator, Match-not-syntactic-class Operator, Emacs Syntax Tables, Syntactic Class Operators
1614
@subsection The Match-syntactic-class Operator (@code{\s}@var{class})
1618
This operator matches any character whose syntactic class is represented
1619
by a specified character. @samp{\s@var{class}} represents this operator
1620
where @var{class} is the character representing the syntactic class you
1621
want. For example, @samp{w} represents the syntactic
1622
class of word-constituent characters, so @samp{\sw} matches any
1623
word-constituent character.
1625
@node Match-not-syntactic-class Operator, , Match-syntactic-class Operator, Syntactic Class Operators
1626
@subsection The Match-not-syntactic-class Operator (@code{\S}@var{class})
1630
This operator is similar to the match-syntactic-class operator except
1631
that it matches any character whose syntactic class is @emph{not}
1632
represented by the specified character. @samp{\S@var{class}} represents
1633
this operator. For example, @samp{w} represents the syntactic class of
1634
word-constituent characters, so @samp{\Sw} matches any character that is
1635
not word-constituent.
1638
@node What Gets Matched?, Programming with Regex, GNU Emacs Operators, Top
1639
@chapter What Gets Matched?
1641
Regex usually matches strings according to the ``leftmost longest''
1642
rule; that is, it chooses the longest of the leftmost matches. This
1643
does not mean that for a regular expression containing subexpressions
1644
that it simply chooses the longest match for each subexpression, left to
1645
right; the overall match must also be the longest possible one.
1647
For example, @samp{(ac*)(c*d[ac]*)\1} matches @samp{acdacaaa}, not
1648
@samp{acdac}, as it would if it were to choose the longest match for the
1649
first subexpression.
1652
@node Programming with Regex, Copying, What Gets Matched?, Top
1653
@chapter Programming with Regex
1655
Here we describe how you use the Regex data structures and functions in
1656
C programs. Regex has three interfaces: one designed for @sc{gnu}, one
1657
compatible with @sc{posix} and one compatible with Berkeley @sc{unix}.
1660
* GNU Regex Functions::
1661
* POSIX Regex Functions::
1662
* BSD Regex Functions::
1666
@node GNU Regex Functions, POSIX Regex Functions, , Programming with Regex
1667
@section GNU Regex Functions
1669
If you're writing code that doesn't need to be compatible with either
1670
@sc{posix} or Berkeley @sc{unix}, you can use these functions. They
1671
provide more options than the other interfaces.
1674
* GNU Pattern Buffers:: The re_pattern_buffer type.
1675
* GNU Regular Expression Compiling:: re_compile_pattern ()
1676
* GNU Matching:: re_match ()
1677
* GNU Searching:: re_search ()
1678
* Matching/Searching with Split Data:: re_match_2 (), re_search_2 ()
1679
* Searching with Fastmaps:: re_compile_fastmap ()
1680
* GNU Translate Tables:: The `translate' field.
1681
* Using Registers:: The re_registers type and related fns.
1682
* Freeing GNU Pattern Buffers:: regfree ()
1686
@node GNU Pattern Buffers, GNU Regular Expression Compiling, , GNU Regex Functions
1687
@subsection GNU Pattern Buffers
1689
@cindex pattern buffer, definition of
1690
@tindex re_pattern_buffer @r{definition}
1691
@tindex struct re_pattern_buffer @r{definition}
1693
To compile, match, or search for a given regular expression, you must
1694
supply a pattern buffer. A @dfn{pattern buffer} holds one compiled
1695
regular expression.@footnote{Regular expressions are also referred to as
1696
``patterns,'' hence the name ``pattern buffer.''}
1698
You can have several different pattern buffers simultaneously, each
1699
holding a compiled pattern for a different regular expression.
1701
@file{regex.h} defines the pattern buffer @code{struct} as follows:
1704
/* Space that holds the compiled pattern. It is declared as
1705
`unsigned char *' because its elements are
1706
sometimes used as array indexes. */
1707
unsigned char *buffer;
1709
/* Number of bytes to which `buffer' points. */
1710
unsigned long allocated;
1712
/* Number of bytes actually used in `buffer'. */
1715
/* Syntax setting with which the pattern was compiled. */
1716
reg_syntax_t syntax;
1718
/* Pointer to a fastmap, if any, otherwise zero. re_search uses
1719
the fastmap, if there is one, to skip over impossible
1720
starting points for matches. */
1723
/* Either a translate table to apply to all characters before
1724
comparing them, or zero for no translation. The translation
1725
is applied to a pattern when it is compiled and to a string
1726
when it is matched. */
1729
/* Number of subexpressions found by the compiler. */
1732
/* Zero if this pattern cannot match the empty string, one else.
1733
Well, in truth it's used only in `re_search_2', to see
1734
whether or not we should use the fastmap, so we don't set
1735
this absolutely perfectly; see `re_compile_fastmap' (the
1736
`duplicate' case). */
1737
unsigned can_be_null : 1;
1739
/* If REGS_UNALLOCATED, allocate space in the `regs' structure
1740
for `max (RE_NREGS, re_nsub + 1)' groups.
1741
If REGS_REALLOCATE, reallocate space if necessary.
1742
If REGS_FIXED, use what's there. */
1743
#define REGS_UNALLOCATED 0
1744
#define REGS_REALLOCATE 1
1745
#define REGS_FIXED 2
1746
unsigned regs_allocated : 2;
1748
/* Set to zero when `regex_compile' compiles a pattern; set to one
1749
by `re_compile_fastmap' if it updates the fastmap. */
1750
unsigned fastmap_accurate : 1;
1752
/* If set, `re_match_2' does not return information about
1754
unsigned no_sub : 1;
1756
/* If set, a beginning-of-line anchor doesn't match at the
1757
beginning of the string. */
1758
unsigned not_bol : 1;
1760
/* Similarly for an end-of-line anchor. */
1761
unsigned not_eol : 1;
1763
/* If true, an anchor at a newline matches. */
1764
unsigned newline_anchor : 1;
1769
@node GNU Regular Expression Compiling, GNU Matching, GNU Pattern Buffers, GNU Regex Functions
1770
@subsection GNU Regular Expression Compiling
1772
In @sc{gnu}, you can both match and search for a given regular
1773
expression. To do either, you must first compile it in a pattern buffer
1774
(@pxref{GNU Pattern Buffers}).
1776
@cindex syntax initialization
1777
@vindex re_syntax_options @r{initialization}
1778
Regular expressions match according to the syntax with which they were
1779
compiled; with @sc{gnu}, you indicate what syntax you want by setting
1780
the variable @code{re_syntax_options} (declared in @file{regex.h} and
1781
defined in @file{regex.c}) before calling the compiling function,
1782
@code{re_compile_pattern} (see below). @xref{Syntax Bits}, and
1783
@ref{Predefined Syntaxes}.
1785
You can change the value of @code{re_syntax_options} at any time.
1786
Usually, however, you set its value once and then never change it.
1788
@cindex pattern buffer initialization
1789
@code{re_compile_pattern} takes a pattern buffer as an argument. You
1790
must initialize the following fields:
1794
@item translate @r{initialization}
1797
@vindex translate @r{initialization}
1798
Initialize this to point to a translate table if you want one, or to
1799
zero if you don't. We explain translate tables in @ref{GNU Translate
1803
@vindex fastmap @r{initialization}
1804
Initialize this to nonzero if you want a fastmap, or to zero if you
1809
@vindex buffer @r{initialization}
1810
@vindex allocated @r{initialization}
1812
If you want @code{re_compile_pattern} to allocate memory for the
1813
compiled pattern, set both of these to zero. If you have an existing
1814
block of memory (allocated with @code{malloc}) you want Regex to use,
1815
set @code{buffer} to its address and @code{allocated} to its size (in
1818
@code{re_compile_pattern} uses @code{realloc} to extend the space for
1819
the compiled pattern as necessary.
1823
To compile a pattern buffer, use:
1825
@findex re_compile_pattern
1828
re_compile_pattern (const char *@var{regex}, const int @var{regex_size},
1829
struct re_pattern_buffer *@var{pattern_buffer})
1833
@var{regex} is the regular expression's address, @var{regex_size} is its
1834
length, and @var{pattern_buffer} is the pattern buffer's address.
1836
If @code{re_compile_pattern} successfully compiles the regular
1837
expression, it returns zero and sets @code{*@var{pattern_buffer}} to the
1838
compiled pattern. It sets the pattern buffer's fields as follows:
1842
@vindex buffer @r{field, set by @code{re_compile_pattern}}
1843
to the compiled pattern.
1846
@vindex used @r{field, set by @code{re_compile_pattern}}
1847
to the number of bytes the compiled pattern in @code{buffer} occupies.
1850
@vindex syntax @r{field, set by @code{re_compile_pattern}}
1851
to the current value of @code{re_syntax_options}.
1854
@vindex re_nsub @r{field, set by @code{re_compile_pattern}}
1855
to the number of subexpressions in @var{regex}.
1857
@item fastmap_accurate
1858
@vindex fastmap_accurate @r{field, set by @code{re_compile_pattern}}
1859
to zero on the theory that the pattern you're compiling is different
1860
than the one previously compiled into @code{buffer}; in that case (since
1861
you can't make a fastmap without a compiled pattern),
1862
@code{fastmap} would either contain an incompatible fastmap, or nothing
1868
If @code{re_compile_pattern} can't compile @var{regex}, it returns an
1869
error string corresponding to one of the errors listed in @ref{POSIX
1870
Regular Expression Compiling}.
1873
@node GNU Matching, GNU Searching, GNU Regular Expression Compiling, GNU Regex Functions
1874
@subsection GNU Matching
1876
@cindex matching with GNU functions
1878
Matching the @sc{gnu} way means trying to match as much of a string as
1879
possible starting at a position within it you specify. Once you've compiled
1880
a pattern into a pattern buffer (@pxref{GNU Regular Expression
1881
Compiling}), you can ask the matcher to match that pattern against a
1887
re_match (struct re_pattern_buffer *@var{pattern_buffer},
1888
const char *@var{string}, const int @var{size},
1889
const int @var{start}, struct re_registers *@var{regs})
1893
@var{pattern_buffer} is the address of a pattern buffer containing a
1894
compiled pattern. @var{string} is the string you want to match; it can
1895
contain newline and null characters. @var{size} is the length of that
1896
string. @var{start} is the string index at which you want to
1897
begin matching; the first character of @var{string} is at index zero.
1898
@xref{Using Registers}, for a explanation of @var{regs}; you can safely
1901
@code{re_match} matches the regular expression in @var{pattern_buffer}
1902
against the string @var{string} according to the syntax in
1903
@var{pattern_buffers}'s @code{syntax} field. (@xref{GNU Regular
1904
Expression Compiling}, for how to set it.) The function returns
1905
@math{-1} if the compiled pattern does not match any part of
1906
@var{string} and @math{-2} if an internal error happens; otherwise, it
1907
returns how many (possibly zero) characters of @var{string} the pattern
1910
An example: suppose @var{pattern_buffer} points to a pattern buffer
1911
containing the compiled pattern for @samp{a*}, and @var{string} points
1912
to @samp{aaaaab} (whereupon @var{size} should be 6). Then if @var{start}
1913
is 2, @code{re_match} returns 3, i.e., @samp{a*} would have matched the
1914
last three @samp{a}s in @var{string}. If @var{start} is 0,
1915
@code{re_match} returns 5, i.e., @samp{a*} would have matched all the
1916
@samp{a}s in @var{string}. If @var{start} is either 5 or 6, it returns
1919
If @var{start} is not between zero and @var{size}, then
1920
@code{re_match} returns @math{-1}.
1923
@node GNU Searching, Matching/Searching with Split Data, GNU Matching, GNU Regex Functions
1924
@subsection GNU Searching
1926
@cindex searching with GNU functions
1928
@dfn{Searching} means trying to match starting at successive positions
1929
within a string. The function @code{re_search} does this.
1931
Before calling @code{re_search}, you must compile your regular
1932
expression. @xref{GNU Regular Expression Compiling}.
1934
Here is the function declaration:
1939
re_search (struct re_pattern_buffer *@var{pattern_buffer},
1940
const char *@var{string}, const int @var{size},
1941
const int @var{start}, const int @var{range},
1942
struct re_registers *@var{regs})
1946
@vindex start @r{argument to @code{re_search}}
1947
@vindex range @r{argument to @code{re_search}}
1948
whose arguments are the same as those to @code{re_match} (@pxref{GNU
1949
Matching}) except that the two arguments @var{start} and @var{range}
1950
replace @code{re_match}'s argument @var{start}.
1952
If @var{range} is positive, then @code{re_search} attempts a match
1953
starting first at index @var{start}, then at @math{@var{start} + 1} if
1954
that fails, and so on, up to @math{@var{start} + @var{range}}; if
1955
@var{range} is negative, then it attempts a match starting first at
1956
index @var{start}, then at @math{@var{start} -1} if that fails, and so
1959
If @var{start} is not between zero and @var{size}, then @code{re_search}
1960
returns @math{-1}. When @var{range} is positive, @code{re_search}
1961
adjusts @var{range} so that @math{@var{start} + @var{range} - 1} is
1962
between zero and @var{size}, if necessary; that way it won't search
1963
outside of @var{string}. Similarly, when @var{range} is negative,
1964
@code{re_search} adjusts @var{range} so that @math{@var{start} +
1965
@var{range} + 1} is between zero and @var{size}, if necessary.
1967
If the @code{fastmap} field of @var{pattern_buffer} is zero,
1968
@code{re_search} matches starting at consecutive positions; otherwise,
1969
it uses @code{fastmap} to make the search more efficient.
1970
@xref{Searching with Fastmaps}.
1972
If no match is found, @code{re_search} returns @math{-1}. If
1973
a match is found, it returns the index where the match began. If an
1974
internal error happens, it returns @math{-2}.
1977
@node Matching/Searching with Split Data, Searching with Fastmaps, GNU Searching, GNU Regex Functions
1978
@subsection Matching and Searching with Split Data
1980
Using the functions @code{re_match_2} and @code{re_search_2}, you can
1981
match or search in data that is divided into two strings.
1988
re_match_2 (struct re_pattern_buffer *@var{buffer},
1989
const char *@var{string1}, const int @var{size1},
1990
const char *@var{string2}, const int @var{size2},
1991
const int @var{start},
1992
struct re_registers *@var{regs},
1993
const int @var{stop})
1997
is similar to @code{re_match} (@pxref{GNU Matching}) except that you
1998
pass @emph{two} data strings and sizes, and an index @var{stop} beyond
1999
which you don't want the matcher to try matching. As with
2000
@code{re_match}, if it succeeds, @code{re_match_2} returns how many
2001
characters of @var{string} it matched. Regard @var{string1} and
2002
@var{string2} as concatenated when you set the arguments @var{start} and
2003
@var{stop} and use the contents of @var{regs}; @code{re_match_2} never
2004
returns a value larger than @math{@var{size1} + @var{size2}}.
2011
re_search_2 (struct re_pattern_buffer *@var{buffer},
2012
const char *@var{string1}, const int @var{size1},
2013
const char *@var{string2}, const int @var{size2},
2014
const int @var{start}, const int @var{range},
2015
struct re_registers *@var{regs},
2016
const int @var{stop})
2020
is similarly related to @code{re_search}.
2023
@node Searching with Fastmaps, GNU Translate Tables, Matching/Searching with Split Data, GNU Regex Functions
2024
@subsection Searching with Fastmaps
2027
If you're searching through a long string, you should use a fastmap.
2028
Without one, the searcher tries to match at consecutive positions in the
2029
string. Generally, most of the characters in the string could not start
2030
a match. It takes much longer to try matching at a given position in the
2031
string than it does to check in a table whether or not the character at
2032
that position could start a match. A @dfn{fastmap} is such a table.
2034
More specifically, a fastmap is an array indexed by the characters in
2035
your character set. Under the @sc{ascii} encoding, therefore, a fastmap
2036
has 256 elements. If you want the searcher to use a fastmap with a
2037
given pattern buffer, you must allocate the array and assign the array's
2038
address to the pattern buffer's @code{fastmap} field. You either can
2039
compile the fastmap yourself or have @code{re_search} do it for you;
2040
when @code{fastmap} is nonzero, it automatically compiles a fastmap the
2041
first time you search using a particular compiled pattern.
2043
To compile a fastmap yourself, use:
2045
@findex re_compile_fastmap
2048
re_compile_fastmap (struct re_pattern_buffer *@var{pattern_buffer})
2052
@var{pattern_buffer} is the address of a pattern buffer. If the
2053
character @var{c} could start a match for the pattern,
2054
@code{re_compile_fastmap} makes
2055
@code{@var{pattern_buffer}->fastmap[@var{c}]} nonzero. It returns
2056
@math{0} if it can compile a fastmap and @math{-2} if there is an
2057
internal error. For example, if @samp{|} is the alternation operator
2058
and @var{pattern_buffer} holds the compiled pattern for @samp{a|b}, then
2059
@code{re_compile_fastmap} sets @code{fastmap['a']} and
2060
@code{fastmap['b']} (and no others).
2062
@code{re_search} uses a fastmap as it moves along in the string: it
2063
checks the string's characters until it finds one that's in the fastmap.
2064
Then it tries matching at that character. If the match fails, it
2065
repeats the process. So, by using a fastmap, @code{re_search} doesn't
2066
waste time trying to match at positions in the string that couldn't
2069
If you don't want @code{re_search} to use a fastmap,
2070
store zero in the @code{fastmap} field of the pattern buffer before
2071
calling @code{re_search}.
2073
Once you've initialized a pattern buffer's @code{fastmap} field, you
2074
need never do so again---even if you compile a new pattern in
2075
it---provided the way the field is set still reflects whether or not you
2076
want a fastmap. @code{re_search} will still either do nothing if
2077
@code{fastmap} is null or, if it isn't, compile a new fastmap for the
2080
@node GNU Translate Tables, Using Registers, Searching with Fastmaps, GNU Regex Functions
2081
@subsection GNU Translate Tables
2083
If you set the @code{translate} field of a pattern buffer to a translate
2084
table, then the @sc{gnu} Regex functions to which you've passed that
2085
pattern buffer use it to apply a simple transformation
2086
to all the regular expression and string characters at which they look.
2088
A @dfn{translate table} is an array indexed by the characters in your
2089
character set. Under the @sc{ascii} encoding, therefore, a translate
2090
table has 256 elements. The array's elements are also characters in
2091
your character set. When the Regex functions see a character @var{c},
2092
they use @code{translate[@var{c}]} in its place, with one exception: the
2093
character after a @samp{\} is not translated. (This ensures that, the
2094
operators, e.g., @samp{\B} and @samp{\b}, are always distinguishable.)
2096
For example, a table that maps all lowercase letters to the
2097
corresponding uppercase ones would cause the matcher to ignore
2098
differences in case.@footnote{A table that maps all uppercase letters to
2099
the corresponding lowercase ones would work just as well for this
2100
purpose.} Such a table would map all characters except lowercase letters
2101
to themselves, and lowercase letters to the corresponding uppercase
2102
ones. Under the @sc{ascii} encoding, here's how you could initialize
2103
such a table (we'll call it @code{case_fold}):
2106
for (i = 0; i < 256; i++)
2108
for (i = 'a'; i <= 'z'; i++)
2109
case_fold[i] = i - ('a' - 'A');
2112
You tell Regex to use a translate table on a given pattern buffer by
2113
assigning that table's address to the @code{translate} field of that
2114
buffer. If you don't want Regex to do any translation, put zero into
2115
this field. You'll get weird results if you change the table's contents
2116
anytime between compiling the pattern buffer, compiling its fastmap, and
2117
matching or searching with the pattern buffer.
2119
@node Using Registers, Freeing GNU Pattern Buffers, GNU Translate Tables, GNU Regex Functions
2120
@subsection Using Registers
2122
A group in a regular expression can match a (posssibly empty) substring
2123
of the string that regular expression as a whole matched. The matcher
2124
remembers the beginning and end of the substring matched by
2127
To find out what they matched, pass a nonzero @var{regs} argument to a
2128
@sc{gnu} matching or searching function (@pxref{GNU Matching} and
2129
@ref{GNU Searching}), i.e., the address of a structure of this type, as
2130
defined in @file{regex.h}:
2132
@c We don't bother to include this directly from regex.h,
2133
@c since it changes so rarely.
2135
@tindex re_registers
2136
@vindex num_regs @r{in @code{struct re_registers}}
2137
@vindex start @r{in @code{struct re_registers}}
2138
@vindex end @r{in @code{struct re_registers}}
2147
Except for (possibly) the @var{num_regs}'th element (see below), the
2148
@var{i}th element of the @code{start} and @code{end} arrays records
2149
information about the @var{i}th group in the pattern. (They're declared
2150
as C pointers, but this is only because not all C compilers accept
2151
zero-length arrays; conceptually, it is simplest to think of them as
2154
The @code{start} and @code{end} arrays are allocated in various ways,
2155
depending on the value of the @code{regs_allocated}
2156
@vindex regs_allocated
2157
field in the pattern buffer passed to the matcher.
2159
The simplest and perhaps most useful is to let the matcher (re)allocate
2160
enough space to record information for all the groups in the regular
2161
expression. If @code{regs_allocated} is @code{REGS_UNALLOCATED},
2162
@vindex REGS_UNALLOCATED
2163
the matcher allocates @math{1 + @var{re_nsub}} (another field in the
2164
pattern buffer; @pxref{GNU Pattern Buffers}). The extra element is set
2165
to @math{-1}, and sets @code{regs_allocated} to @code{REGS_REALLOCATE}.
2166
@vindex REGS_REALLOCATE
2167
Then on subsequent calls with the same pattern buffer and @var{regs}
2168
arguments, the matcher reallocates more space if necessary.
2170
It would perhaps be more logical to make the @code{regs_allocated} field
2171
part of the @code{re_registers} structure, instead of part of the
2172
pattern buffer. But in that case the caller would be forced to
2173
initialize the structure before passing it. Much existing code doesn't
2174
do this initialization, and it's arguably better to avoid it anyway.
2176
@code{re_compile_pattern} sets @code{regs_allocated} to
2177
@code{REGS_UNALLOCATED},
2178
so if you use the GNU regular expression
2179
functions, you get this behavior by default.
2181
xx document re_set_registers
2183
@sc{posix}, on the other hand, requires a different interface: the
2184
caller is supposed to pass in a fixed-length array which the matcher
2185
fills. Therefore, if @code{regs_allocated} is @code{REGS_FIXED}
2187
the matcher simply fills that array.
2189
The following examples illustrate the information recorded in the
2190
@code{re_registers} structure. (In all of them, @samp{(} represents the
2191
open-group and @samp{)} the close-group operator. The first character
2192
in the string @var{string} is at index 0.)
2194
@c xx i'm not sure this is all true anymore.
2199
If the regular expression has an @w{@var{i}-th}
2200
group not contained within another group that matches a
2201
substring of @var{string}, then the function sets
2202
@code{@w{@var{regs}->}start[@var{i}]} to the index in @var{string} where
2203
the substring matched by the @w{@var{i}-th} group begins, and
2204
@code{@w{@var{regs}->}end[@var{i}]} to the index just beyond that
2205
substring's end. The function sets @code{@w{@var{regs}->}start[0]} and
2206
@code{@w{@var{regs}->}end[0]} to analogous information about the entire
2209
For example, when you match @samp{((a)(b))} against @samp{ab}, you get:
2213
0 in @code{@w{@var{regs}->}start[0]} and 2 in @code{@w{@var{regs}->}end[0]}
2216
0 in @code{@w{@var{regs}->}start[1]} and 2 in @code{@w{@var{regs}->}end[1]}
2219
0 in @code{@w{@var{regs}->}start[2]} and 1 in @code{@w{@var{regs}->}end[2]}
2222
1 in @code{@w{@var{regs}->}start[3]} and 2 in @code{@w{@var{regs}->}end[3]}
2226
If a group matches more than once (as it might if followed by,
2227
e.g., a repetition operator), then the function reports the information
2228
about what the group @emph{last} matched.
2230
For example, when you match the pattern @samp{(a)*} against the string
2235
0 in @code{@w{@var{regs}->}start[0]} and 2 in @code{@w{@var{regs}->}end[0]}
2238
1 in @code{@w{@var{regs}->}start[1]} and 2 in @code{@w{@var{regs}->}end[1]}
2242
If the @w{@var{i}-th} group does not participate in a
2243
successful match, e.g., it is an alternative not taken or a
2244
repetition operator allows zero repetitions of it, then the function
2245
sets @code{@w{@var{regs}->}start[@var{i}]} and
2246
@code{@w{@var{regs}->}end[@var{i}]} to @math{-1}.
2248
For example, when you match the pattern @samp{(a)*b} against
2249
the string @samp{b}, you get:
2253
0 in @code{@w{@var{regs}->}start[0]} and 1 in @code{@w{@var{regs}->}end[0]}
2256
@math{-1} in @code{@w{@var{regs}->}start[1]} and @math{-1} in @code{@w{@var{regs}->}end[1]}
2260
If the @w{@var{i}-th} group matches a zero-length string, then the
2261
function sets @code{@w{@var{regs}->}start[@var{i}]} and
2262
@code{@w{@var{regs}->}end[@var{i}]} to the index just beyond that
2265
For example, when you match the pattern @samp{(a*)b} against the string
2270
0 in @code{@w{@var{regs}->}start[0]} and 1 in @code{@w{@var{regs}->}end[0]}
2273
0 in @code{@w{@var{regs}->}start[1]} and 0 in @code{@w{@var{regs}->}end[1]}
2277
The function sets @code{@w{@var{regs}->}start[0]} and
2278
@code{@w{@var{regs}->}end[0]} to analogous information about the entire
2281
For example, when you match the pattern @samp{(a*)} against the empty
2286
0 in @code{@w{@var{regs}->}start[0]} and 0 in @code{@w{@var{regs}->}end[0]}
2289
0 in @code{@w{@var{regs}->}start[1]} and 0 in @code{@w{@var{regs}->}end[1]}
2294
If an @w{@var{i}-th} group contains a @w{@var{j}-th} group
2295
in turn not contained within any other group within group @var{i} and
2296
the function reports a match of the @w{@var{i}-th} group, then it
2297
records in @code{@w{@var{regs}->}start[@var{j}]} and
2298
@code{@w{@var{regs}->}end[@var{j}]} the last match (if it matched) of
2299
the @w{@var{j}-th} group.
2301
For example, when you match the pattern @samp{((a*)b)*} against the
2302
string @samp{abb}, @w{group 2} last matches the empty string, so you
2303
get what it previously matched:
2307
0 in @code{@w{@var{regs}->}start[0]} and 3 in @code{@w{@var{regs}->}end[0]}
2310
2 in @code{@w{@var{regs}->}start[1]} and 3 in @code{@w{@var{regs}->}end[1]}
2313
2 in @code{@w{@var{regs}->}start[2]} and 2 in @code{@w{@var{regs}->}end[2]}
2316
When you match the pattern @samp{((a)*b)*} against the string
2317
@samp{abb}, @w{group 2} doesn't participate in the last match, so you
2322
0 in @code{@w{@var{regs}->}start[0]} and 3 in @code{@w{@var{regs}->}end[0]}
2325
2 in @code{@w{@var{regs}->}start[1]} and 3 in @code{@w{@var{regs}->}end[1]}
2328
0 in @code{@w{@var{regs}->}start[2]} and 1 in @code{@w{@var{regs}->}end[2]}
2332
If an @w{@var{i}-th} group contains a @w{@var{j}-th} group
2333
in turn not contained within any other group within group @var{i}
2334
and the function sets
2335
@code{@w{@var{regs}->}start[@var{i}]} and
2336
@code{@w{@var{regs}->}end[@var{i}]} to @math{-1}, then it also sets
2337
@code{@w{@var{regs}->}start[@var{j}]} and
2338
@code{@w{@var{regs}->}end[@var{j}]} to @math{-1}.
2340
For example, when you match the pattern @samp{((a)*b)*c} against the
2341
string @samp{c}, you get:
2345
0 in @code{@w{@var{regs}->}start[0]} and 1 in @code{@w{@var{regs}->}end[0]}
2348
@math{-1} in @code{@w{@var{regs}->}start[1]} and @math{-1} in @code{@w{@var{regs}->}end[1]}
2351
@math{-1} in @code{@w{@var{regs}->}start[2]} and @math{-1} in @code{@w{@var{regs}->}end[2]}
2356
@node Freeing GNU Pattern Buffers, , Using Registers, GNU Regex Functions
2357
@subsection Freeing GNU Pattern Buffers
2359
To free any allocated fields of a pattern buffer, you can use the
2360
@sc{posix} function described in @ref{Freeing POSIX Pattern Buffers},
2361
since the type @code{regex_t}---the type for @sc{posix} pattern
2362
buffers---is equivalent to the type @code{re_pattern_buffer}. After
2363
freeing a pattern buffer, you need to again compile a regular expression
2364
in it (@pxref{GNU Regular Expression Compiling}) before passing it to
2365
a matching or searching function.
2368
@node POSIX Regex Functions, BSD Regex Functions, GNU Regex Functions, Programming with Regex
2369
@section POSIX Regex Functions
2371
If you're writing code that has to be @sc{posix} compatible, you'll need
2372
to use these functions. Their interfaces are as specified by @sc{posix},
2376
* POSIX Pattern Buffers:: The regex_t type.
2377
* POSIX Regular Expression Compiling:: regcomp ()
2378
* POSIX Matching:: regexec ()
2379
* Reporting Errors:: regerror ()
2380
* Using Byte Offsets:: The regmatch_t type.
2381
* Freeing POSIX Pattern Buffers:: regfree ()
2385
@node POSIX Pattern Buffers, POSIX Regular Expression Compiling, , POSIX Regex Functions
2386
@subsection POSIX Pattern Buffers
2388
To compile or match a given regular expression the @sc{posix} way, you
2389
must supply a pattern buffer exactly the way you do for @sc{gnu}
2390
(@pxref{GNU Pattern Buffers}). @sc{posix} pattern buffers have type
2391
@code{regex_t}, which is equivalent to the @sc{gnu} pattern buffer
2392
type @code{re_pattern_buffer}.
2395
@node POSIX Regular Expression Compiling, POSIX Matching, POSIX Pattern Buffers, POSIX Regex Functions
2396
@subsection POSIX Regular Expression Compiling
2398
With @sc{posix}, you can only search for a given regular expression; you
2399
can't match it. To do this, you must first compile it in a
2400
pattern buffer, using @code{regcomp}.
2403
Before calling @code{regcomp}, you must initialize this pattern buffer
2404
as you do for @sc{gnu} (@pxref{GNU Regular Expression Compiling}). See
2405
below, however, for how to choose a syntax with which to compile.
2408
To compile a pattern buffer, use:
2413
regcomp (regex_t *@var{preg}, const char *@var{regex}, int @var{cflags})
2417
@var{preg} is the initialized pattern buffer's address, @var{regex} is
2418
the regular expression's address, and @var{cflags} is the compilation
2419
flags, which Regex considers as a collection of bits. Here are the
2420
valid bits, as defined in @file{regex.h}:
2425
@vindex REG_EXTENDED
2426
says to use @sc{posix} Extended Regular Expression syntax; if this isn't
2427
set, then says to use @sc{posix} Basic Regular Expression syntax.
2428
@code{regcomp} sets @var{preg}'s @code{syntax} field accordingly.
2432
@cindex ignoring case
2433
says to ignore case; @code{regcomp} sets @var{preg}'s @code{translate}
2434
field to a translate table which ignores case, replacing anything you've
2439
says to set @var{preg}'s @code{no_sub} field; @pxref{POSIX Matching},
2440
for what this means.
2449
match-any-character operator (@pxref{Match-any-character
2450
Operator}) doesn't match a newline.
2453
nonmatching list not containing a newline (@pxref{List
2454
Operators}) matches a newline.
2457
match-beginning-of-line operator (@pxref{Match-beginning-of-line
2458
Operator}) matches the empty string immediately after a newline,
2459
regardless of how @code{REG_NOTBOL} is set (@pxref{POSIX Matching}, for
2460
an explanation of @code{REG_NOTBOL}).
2463
match-end-of-line operator (@pxref{Match-beginning-of-line
2464
Operator}) matches the empty string immediately before a newline,
2465
regardless of how @code{REG_NOTEOL} is set (@pxref{POSIX Matching},
2466
for an explanation of @code{REG_NOTEOL}).
2472
If @code{regcomp} successfully compiles the regular expression, it
2473
returns zero and sets @code{*@var{pattern_buffer}} to the compiled
2474
pattern. Except for @code{syntax} (which it sets as explained above), it
2475
also sets the same fields the same way as does the @sc{gnu} compiling
2476
function (@pxref{GNU Regular Expression Compiling}).
2478
If @code{regcomp} can't compile the regular expression, it returns one
2479
of the error codes listed here. (Except when noted differently, the
2480
syntax of in all examples below is basic regular expression syntax.)
2484
@comment repetitions
2486
For example, the consecutive repetition operators @samp{**} in
2487
@samp{a**} are invalid. As another example, if the syntax is extended
2488
regular expression syntax, then the repetition operator @samp{*} with
2489
nothing on which to operate in @samp{*} is invalid.
2492
For example, the @var{count} @samp{-1} in @samp{a\@{-1} is invalid.
2495
For example, @samp{a\@{1} is missing a close-interval operator.
2499
For example, @samp{[a} is missing a close-list operator.
2502
For example, the range ending point @samp{z} that collates lower than
2503
does its starting point @samp{a} in @samp{[z-a]} is invalid. Also, the
2504
range with the character class @samp{[:alpha:]} as its starting point in
2505
@samp{[[:alpha:]-|]}.
2508
For example, the character class name @samp{foo} in @samp{[[:foo:]} is
2513
For example, @samp{a\)} is missing an open-group operator and @samp{\(a}
2514
is missing a close-group operator.
2517
For example, the back reference @samp{\2} that refers to a nonexistent
2518
subexpression in @samp{\(a\)\2} is invalid.
2520
@comment unfinished business
2523
Returned when a regular expression causes no other more specific error.
2526
For example, the trailing backslash @samp{\} in @samp{a\} is invalid, as is the
2529
@comment kitchen sink
2531
For example, in the extended regular expression syntax, the empty group
2532
@samp{()} in @samp{a()b} is invalid.
2536
Returned when a regular expression needs a pattern buffer larger than
2540
Returned when a regular expression makes Regex to run out of memory.
2545
@node POSIX Matching, Reporting Errors, POSIX Regular Expression Compiling, POSIX Regex Functions
2546
@subsection POSIX Matching
2548
Matching the @sc{posix} way means trying to match a null-terminated
2549
string starting at its first character. Once you've compiled a pattern
2550
into a pattern buffer (@pxref{POSIX Regular Expression Compiling}), you
2551
can ask the matcher to match that pattern against a string using:
2556
regexec (const regex_t *@var{preg}, const char *@var{string},
2557
size_t @var{nmatch}, regmatch_t @var{pmatch}[], int @var{eflags})
2561
@var{preg} is the address of a pattern buffer for a compiled pattern.
2562
@var{string} is the string you want to match.
2564
@xref{Using Byte Offsets}, for an explanation of @var{pmatch}. If you
2565
pass zero for @var{nmatch} or you compiled @var{preg} with the
2566
compilation flag @code{REG_NOSUB} set, then @code{regexec} will ignore
2567
@var{pmatch}; otherwise, you must allocate it to have at least
2568
@var{nmatch} elements. @code{regexec} will record @var{nmatch} byte
2569
offsets in @var{pmatch}, and set to @math{-1} any unused elements up to
2570
@math{@var{pmatch}@code{[@var{nmatch}]} - 1}.
2572
@var{eflags} specifies @dfn{execution flags}---namely, the two bits
2573
@code{REG_NOTBOL} and @code{REG_NOTEOL} (defined in @file{regex.h}). If
2574
you set @code{REG_NOTBOL}, then the match-beginning-of-line operator
2575
(@pxref{Match-beginning-of-line Operator}) always fails to match.
2576
This lets you match against pieces of a line, as you would need to if,
2577
say, searching for repeated instances of a given pattern in a line; it
2578
would work correctly for patterns both with and without
2579
match-beginning-of-line operators. @code{REG_NOTEOL} works analogously
2580
for the match-end-of-line operator (@pxref{Match-end-of-line
2581
Operator}); it exists for symmetry.
2583
@code{regexec} tries to find a match for @var{preg} in @var{string}
2584
according to the syntax in @var{preg}'s @code{syntax} field.
2585
(@xref{POSIX Regular Expression Compiling}, for how to set it.) The
2586
function returns zero if the compiled pattern matches @var{string} and
2587
@code{REG_NOMATCH} (defined in @file{regex.h}) if it doesn't.
2589
@node Reporting Errors, Using Byte Offsets, POSIX Matching, POSIX Regex Functions
2590
@subsection Reporting Errors
2592
If either @code{regcomp} or @code{regexec} fail, they return a nonzero
2593
error code, the possibilities for which are defined in @file{regex.h}.
2594
@xref{POSIX Regular Expression Compiling}, and @ref{POSIX Matching}, for
2595
what these codes mean. To get an error string corresponding to these
2601
regerror (int @var{errcode},
2602
const regex_t *@var{preg},
2604
size_t @var{errbuf_size})
2608
@var{errcode} is an error code, @var{preg} is the address of the pattern
2609
buffer which provoked the error, @var{errbuf} is the error buffer, and
2610
@var{errbuf_size} is @var{errbuf}'s size.
2612
@code{regerror} returns the size in bytes of the error string
2613
corresponding to @var{errcode} (including its terminating null). If
2614
@var{errbuf} and @var{errbuf_size} are nonzero, it also returns in
2615
@var{errbuf} the first @math{@var{errbuf_size} - 1} characters of the
2616
error string, followed by a null.
2617
@var{errbuf_size} must be a nonnegative number less than or equal to the
2618
size in bytes of @var{errbuf}.
2620
You can call @code{regerror} with a null @var{errbuf} and a zero
2621
@var{errbuf_size} to determine how large @var{errbuf} need be to
2622
accommodate @code{regerror}'s error string.
2624
@node Using Byte Offsets, Freeing POSIX Pattern Buffers, Reporting Errors, POSIX Regex Functions
2625
@subsection Using Byte Offsets
2627
In @sc{posix}, variables of type @code{regmatch_t} hold analogous
2628
information, but are not identical to, @sc{gnu}'s registers (@pxref{Using
2629
Registers}). To get information about registers in @sc{posix}, pass to
2630
@code{regexec} a nonzero @var{pmatch} of type @code{regmatch_t}, i.e.,
2631
the address of a structure of this type, defined in
2643
When reading in @ref{Using Registers}, about how the matching function
2644
stores the information into the registers, substitute @var{pmatch} for
2645
@var{regs}, @code{@w{@var{pmatch}[@var{i}]->}rm_so} for
2646
@code{@w{@var{regs}->}start[@var{i}]} and
2647
@code{@w{@var{pmatch}[@var{i}]->}rm_eo} for
2648
@code{@w{@var{regs}->}end[@var{i}]}.
2650
@node Freeing POSIX Pattern Buffers, , Using Byte Offsets, POSIX Regex Functions
2651
@subsection Freeing POSIX Pattern Buffers
2653
To free any allocated fields of a pattern buffer, use:
2658
regfree (regex_t *@var{preg})
2662
@var{preg} is the pattern buffer whose allocated fields you want freed.
2663
@code{regfree} also sets @var{preg}'s @code{allocated} and @code{used}
2664
fields to zero. After freeing a pattern buffer, you need to again
2665
compile a regular expression in it (@pxref{POSIX Regular Expression
2666
Compiling}) before passing it to the matching function (@pxref{POSIX
2670
@node BSD Regex Functions, , POSIX Regex Functions, Programming with Regex
2671
@section BSD Regex Functions
2673
If you're writing code that has to be Berkeley @sc{unix} compatible,
2674
you'll need to use these functions whose interfaces are the same as those
2675
in Berkeley @sc{unix}.
2678
* BSD Regular Expression Compiling:: re_comp ()
2679
* BSD Searching:: re_exec ()
2682
@node BSD Regular Expression Compiling, BSD Searching, , BSD Regex Functions
2683
@subsection BSD Regular Expression Compiling
2685
With Berkeley @sc{unix}, you can only search for a given regular
2686
expression; you can't match one. To search for it, you must first
2687
compile it. Before you compile it, you must indicate the regular
2688
expression syntax you want it compiled according to by setting the
2689
variable @code{re_syntax_options} (declared in @file{regex.h} to some
2690
syntax (@pxref{Regular Expression Syntax}).
2692
To compile a regular expression use:
2697
re_comp (char *@var{regex})
2701
@var{regex} is the address of a null-terminated regular expression.
2702
@code{re_comp} uses an internal pattern buffer, so you can use only the
2703
most recently compiled pattern buffer. This means that if you want to
2704
use a given regular expression that you've already compiled---but it
2705
isn't the latest one you've compiled---you'll have to recompile it. If
2706
you call @code{re_comp} with the null string (@emph{not} the empty
2707
string) as the argument, it doesn't change the contents of the pattern
2710
If @code{re_comp} successfully compiles the regular expression, it
2711
returns zero. If it can't compile the regular expression, it returns
2712
an error string. @code{re_comp}'s error messages are identical to those
2713
of @code{re_compile_pattern} (@pxref{GNU Regular Expression
2716
@node BSD Searching, , BSD Regular Expression Compiling, BSD Regex Functions
2717
@subsection BSD Searching
2719
Searching the Berkeley @sc{unix} way means searching in a string
2720
starting at its first character and trying successive positions within
2721
it to find a match. Once you've compiled a pattern using @code{re_comp}
2722
(@pxref{BSD Regular Expression Compiling}), you can ask Regex
2723
to search for that pattern in a string using:
2728
re_exec (char *@var{string})
2732
@var{string} is the address of the null-terminated string in which you
2735
@code{re_exec} returns either 1 for success or 0 for failure. It
2736
automatically uses a @sc{gnu} fastmap (@pxref{Searching with Fastmaps}).
2739
@node Copying, Index, Programming with Regex, Top
2740
@appendix GNU GENERAL PUBLIC LICENSE
2741
@center Version 2, June 1991
2744
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
2745
675 Mass Ave, Cambridge, MA 02139, USA
2747
Everyone is permitted to copy and distribute verbatim copies
2748
of this license document, but changing it is not allowed.
2751
@unnumberedsec Preamble
2753
The licenses for most software are designed to take away your
2754
freedom to share and change it. By contrast, the GNU General Public
2755
License is intended to guarantee your freedom to share and change free
2756
software---to make sure the software is free for all its users. This
2757
General Public License applies to most of the Free Software
2758
Foundation's software and to any other program whose authors commit to
2759
using it. (Some other Free Software Foundation software is covered by
2760
the GNU Library General Public License instead.) You can apply it to
2763
When we speak of free software, we are referring to freedom, not
2764
price. Our General Public Licenses are designed to make sure that you
2765
have the freedom to distribute copies of free software (and charge for
2766
this service if you wish), that you receive source code or can get it
2767
if you want it, that you can change the software or use pieces of it
2768
in new free programs; and that you know you can do these things.
2770
To protect your rights, we need to make restrictions that forbid
2771
anyone to deny you these rights or to ask you to surrender the rights.
2772
These restrictions translate to certain responsibilities for you if you
2773
distribute copies of the software, or if you modify it.
2775
For example, if you distribute copies of such a program, whether
2776
gratis or for a fee, you must give the recipients all the rights that
2777
you have. You must make sure that they, too, receive or can get the
2778
source code. And you must show them these terms so they know their
2781
We protect your rights with two steps: (1) copyright the software, and
2782
(2) offer you this license which gives you legal permission to copy,
2783
distribute and/or modify the software.
2785
Also, for each author's protection and ours, we want to make certain
2786
that everyone understands that there is no warranty for this free
2787
software. If the software is modified by someone else and passed on, we
2788
want its recipients to know that what they have is not the original, so
2789
that any problems introduced by others will not reflect on the original
2790
authors' reputations.
2792
Finally, any free program is threatened constantly by software
2793
patents. We wish to avoid the danger that redistributors of a free
2794
program will individually obtain patent licenses, in effect making the
2795
program proprietary. To prevent this, we have made it clear that any
2796
patent must be licensed for everyone's free use or not licensed at all.
2798
The precise terms and conditions for copying, distribution and
2799
modification follow.
2802
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2805
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2810
This License applies to any program or other work which contains
2811
a notice placed by the copyright holder saying it may be distributed
2812
under the terms of this General Public License. The ``Program'', below,
2813
refers to any such program or work, and a ``work based on the Program''
2814
means either the Program or any derivative work under copyright law:
2815
that is to say, a work containing the Program or a portion of it,
2816
either verbatim or with modifications and/or translated into another
2817
language. (Hereinafter, translation is included without limitation in
2818
the term ``modification''.) Each licensee is addressed as ``you''.
2820
Activities other than copying, distribution and modification are not
2821
covered by this License; they are outside its scope. The act of
2822
running the Program is not restricted, and the output from the Program
2823
is covered only if its contents constitute a work based on the
2824
Program (independent of having been made by running the Program).
2825
Whether that is true depends on what the Program does.
2828
You may copy and distribute verbatim copies of the Program's
2829
source code as you receive it, in any medium, provided that you
2830
conspicuously and appropriately publish on each copy an appropriate
2831
copyright notice and disclaimer of warranty; keep intact all the
2832
notices that refer to this License and to the absence of any warranty;
2833
and give any other recipients of the Program a copy of this License
2834
along with the Program.
2836
You may charge a fee for the physical act of transferring a copy, and
2837
you may at your option offer warranty protection in exchange for a fee.
2840
You may modify your copy or copies of the Program or any portion
2841
of it, thus forming a work based on the Program, and copy and
2842
distribute such modifications or work under the terms of Section 1
2843
above, provided that you also meet all of these conditions:
2847
You must cause the modified files to carry prominent notices
2848
stating that you changed the files and the date of any change.
2851
You must cause any work that you distribute or publish, that in
2852
whole or in part contains or is derived from the Program or any
2853
part thereof, to be licensed as a whole at no charge to all third
2854
parties under the terms of this License.
2857
If the modified program normally reads commands interactively
2858
when run, you must cause it, when started running for such
2859
interactive use in the most ordinary way, to print or display an
2860
announcement including an appropriate copyright notice and a
2861
notice that there is no warranty (or else, saying that you provide
2862
a warranty) and that users may redistribute the program under
2863
these conditions, and telling the user how to view a copy of this
2864
License. (Exception: if the Program itself is interactive but
2865
does not normally print such an announcement, your work based on
2866
the Program is not required to print an announcement.)
2869
These requirements apply to the modified work as a whole. If
2870
identifiable sections of that work are not derived from the Program,
2871
and can be reasonably considered independent and separate works in
2872
themselves, then this License, and its terms, do not apply to those
2873
sections when you distribute them as separate works. But when you
2874
distribute the same sections as part of a whole which is a work based
2875
on the Program, the distribution of the whole must be on the terms of
2876
this License, whose permissions for other licensees extend to the
2877
entire whole, and thus to each and every part regardless of who wrote it.
2879
Thus, it is not the intent of this section to claim rights or contest
2880
your rights to work written entirely by you; rather, the intent is to
2881
exercise the right to control the distribution of derivative or
2882
collective works based on the Program.
2884
In addition, mere aggregation of another work not based on the Program
2885
with the Program (or with a work based on the Program) on a volume of
2886
a storage or distribution medium does not bring the other work under
2887
the scope of this License.
2890
You may copy and distribute the Program (or a work based on it,
2891
under Section 2) in object code or executable form under the terms of
2892
Sections 1 and 2 above provided that you also do one of the following:
2896
Accompany it with the complete corresponding machine-readable
2897
source code, which must be distributed under the terms of Sections
2898
1 and 2 above on a medium customarily used for software interchange; or,
2901
Accompany it with a written offer, valid for at least three
2902
years, to give any third party, for a charge no more than your
2903
cost of physically performing source distribution, a complete
2904
machine-readable copy of the corresponding source code, to be
2905
distributed under the terms of Sections 1 and 2 above on a medium
2906
customarily used for software interchange; or,
2909
Accompany it with the information you received as to the offer
2910
to distribute corresponding source code. (This alternative is
2911
allowed only for noncommercial distribution and only if you
2912
received the program in object code or executable form with such
2913
an offer, in accord with Subsection b above.)
2916
The source code for a work means the preferred form of the work for
2917
making modifications to it. For an executable work, complete source
2918
code means all the source code for all modules it contains, plus any
2919
associated interface definition files, plus the scripts used to
2920
control compilation and installation of the executable. However, as a
2921
special exception, the source code distributed need not include
2922
anything that is normally distributed (in either source or binary
2923
form) with the major components (compiler, kernel, and so on) of the
2924
operating system on which the executable runs, unless that component
2925
itself accompanies the executable.
2927
If distribution of executable or object code is made by offering
2928
access to copy from a designated place, then offering equivalent
2929
access to copy the source code from the same place counts as
2930
distribution of the source code, even though third parties are not
2931
compelled to copy the source along with the object code.
2934
You may not copy, modify, sublicense, or distribute the Program
2935
except as expressly provided under this License. Any attempt
2936
otherwise to copy, modify, sublicense or distribute the Program is
2937
void, and will automatically terminate your rights under this License.
2938
However, parties who have received copies, or rights, from you under
2939
this License will not have their licenses terminated so long as such
2940
parties remain in full compliance.
2943
You are not required to accept this License, since you have not
2944
signed it. However, nothing else grants you permission to modify or
2945
distribute the Program or its derivative works. These actions are
2946
prohibited by law if you do not accept this License. Therefore, by
2947
modifying or distributing the Program (or any work based on the
2948
Program), you indicate your acceptance of this License to do so, and
2949
all its terms and conditions for copying, distributing or modifying
2950
the Program or works based on it.
2953
Each time you redistribute the Program (or any work based on the
2954
Program), the recipient automatically receives a license from the
2955
original licensor to copy, distribute or modify the Program subject to
2956
these terms and conditions. You may not impose any further
2957
restrictions on the recipients' exercise of the rights granted herein.
2958
You are not responsible for enforcing compliance by third parties to
2962
If, as a consequence of a court judgment or allegation of patent
2963
infringement or for any other reason (not limited to patent issues),
2964
conditions are imposed on you (whether by court order, agreement or
2965
otherwise) that contradict the conditions of this License, they do not
2966
excuse you from the conditions of this License. If you cannot
2967
distribute so as to satisfy simultaneously your obligations under this
2968
License and any other pertinent obligations, then as a consequence you
2969
may not distribute the Program at all. For example, if a patent
2970
license would not permit royalty-free redistribution of the Program by
2971
all those who receive copies directly or indirectly through you, then
2972
the only way you could satisfy both it and this License would be to
2973
refrain entirely from distribution of the Program.
2975
If any portion of this section is held invalid or unenforceable under
2976
any particular circumstance, the balance of the section is intended to
2977
apply and the section as a whole is intended to apply in other
2980
It is not the purpose of this section to induce you to infringe any
2981
patents or other property right claims or to contest validity of any
2982
such claims; this section has the sole purpose of protecting the
2983
integrity of the free software distribution system, which is
2984
implemented by public license practices. Many people have made
2985
generous contributions to the wide range of software distributed
2986
through that system in reliance on consistent application of that
2987
system; it is up to the author/donor to decide if he or she is willing
2988
to distribute software through any other system and a licensee cannot
2991
This section is intended to make thoroughly clear what is believed to
2992
be a consequence of the rest of this License.
2995
If the distribution and/or use of the Program is restricted in
2996
certain countries either by patents or by copyrighted interfaces, the
2997
original copyright holder who places the Program under this License
2998
may add an explicit geographical distribution limitation excluding
2999
those countries, so that distribution is permitted only in or among
3000
countries not thus excluded. In such case, this License incorporates
3001
the limitation as if written in the body of this License.
3004
The Free Software Foundation may publish revised and/or new versions
3005
of the General Public License from time to time. Such new versions will
3006
be similar in spirit to the present version, but may differ in detail to
3007
address new problems or concerns.
3009
Each version is given a distinguishing version number. If the Program
3010
specifies a version number of this License which applies to it and ``any
3011
later version'', you have the option of following the terms and conditions
3012
either of that version or of any later version published by the Free
3013
Software Foundation. If the Program does not specify a version number of
3014
this License, you may choose any version ever published by the Free Software
3018
If you wish to incorporate parts of the Program into other free
3019
programs whose distribution conditions are different, write to the author
3020
to ask for permission. For software which is copyrighted by the Free
3021
Software Foundation, write to the Free Software Foundation; we sometimes
3022
make exceptions for this. Our decision will be guided by the two goals
3023
of preserving the free status of all derivatives of our free software and
3024
of promoting the sharing and reuse of software generally.
3027
@heading NO WARRANTY
3034
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
3035
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
3036
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
3037
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
3038
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
3039
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
3040
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
3041
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
3042
REPAIR OR CORRECTION.
3045
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
3046
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
3047
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
3048
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
3049
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
3050
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
3051
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
3052
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
3053
POSSIBILITY OF SUCH DAMAGES.
3057
@heading END OF TERMS AND CONDITIONS
3060
@center END OF TERMS AND CONDITIONS
3064
@unnumberedsec Appendix: How to Apply These Terms to Your New Programs
3066
If you develop a new program, and you want it to be of the greatest
3067
possible use to the public, the best way to achieve this is to make it
3068
free software which everyone can redistribute and change under these terms.
3070
To do so, attach the following notices to the program. It is safest
3071
to attach them to the start of each source file to most effectively
3072
convey the exclusion of warranty; and each file should have at least
3073
the ``copyright'' line and a pointer to where the full notice is found.
3076
@var{one line to give the program's name and a brief idea of what it does.}
3077
Copyright (C) 19@var{yy} @var{name of author}
3079
This program is free software; you can redistribute it and/or modify
3080
it under the terms of the GNU General Public License as published by
3081
the Free Software Foundation; either version 2 of the License, or
3082
(at your option) any later version.
3084
This program is distributed in the hope that it will be useful,
3085
but WITHOUT ANY WARRANTY; without even the implied warranty of
3086
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3087
GNU General Public License for more details.
3089
You should have received a copy of the GNU General Public License
3090
along with this program; if not, write to the Free Software
3091
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
3094
Also add information on how to contact you by electronic and paper mail.
3096
If the program is interactive, make it output a short notice like this
3097
when it starts in an interactive mode:
3100
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
3101
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
3102
This is free software, and you are welcome to redistribute it
3103
under certain conditions; type `show c' for details.
3106
The hypothetical commands @samp{show w} and @samp{show c} should show
3107
the appropriate parts of the General Public License. Of course, the
3108
commands you use may be called something other than @samp{show w} and
3109
@samp{show c}; they could even be mouse-clicks or menu items---whatever
3112
You should also get your employer (if you work as a programmer) or your
3113
school, if any, to sign a ``copyright disclaimer'' for the program, if
3114
necessary. Here is a sample; alter the names:
3117
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
3118
`Gnomovision' (which makes passes at compilers) written by James Hacker.
3120
@var{signature of Ty Coon}, 1 April 1989
3121
Ty Coon, President of Vice
3124
This General Public License does not permit incorporating your program into
3125
proprietary programs. If your program is a subroutine library, you may
3126
consider it more useful to permit linking proprietary applications with the
3127
library. If this is what you want to do, use the GNU Library General
3128
Public License instead of this License.
3131
@node Index, , Copying, Top
added
removed
lib/common_test/priv/rx-1.5/regex/doc/regex.texi
