summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/re_syntax.n204
1 files changed, 123 insertions, 81 deletions
diff --git a/doc/re_syntax.n b/doc/re_syntax.n
index eebda51..f1eabbc 100644
--- a/doc/re_syntax.n
+++ b/doc/re_syntax.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: re_syntax.n,v 1.15 2007/11/14 11:13:32 dkf Exp $
+'\" RCS: @(#) $Id: re_syntax.n,v 1.16 2007/11/15 12:02:56 dkf Exp $
'\"
.so man.macros
.TH re_syntax n "8.1" Tcl "Tcl Built-In Commands"
@@ -50,7 +50,7 @@ A branch is zero or more \fIconstraints\fR or \fIquantified atoms\fR,
concatenated.
It matches a match for the first, followed by a match for the second, etc;
an empty branch matches the empty string.
-.PP
+.SS QUANTIFIERS
A quantified atom is an \fIatom\fR possibly followed
by a single \fIquantifier\fR.
Without a quantifier, it matches a single match for the atom.
@@ -93,7 +93,7 @@ of matches (see \fBMATCHING\fR)
The forms using \fB{\fR and \fB}\fR are known as \fIbound\fRs. The
numbers \fIm\fR and \fIn\fR are unsigned decimal integers with
permissible values from 0 to 255 inclusive.
-.PP
+.SS ATOMS
An atom is one of:
.RS 2
.IP \fB(\fIre\fB)\fR 6
@@ -128,7 +128,7 @@ when followed by a digit, it is the beginning of a \fIbound\fR (see above)
where \fIx\fR is a single character with no other significance,
matches that character.
.RE
-.PP
+.SS CONSTRAINTS
A \fIconstraint\fR matches an empty string when specific conditions
are met. A constraint may not be followed by a quantifier. The
simple constraints are as follows; some more constraints are described
@@ -163,7 +163,7 @@ An RE may not end with
A \fIbracket expression\fR is a list of characters enclosed in
.QW \fB[\|]\fR .
It normally matches any single character from the list
-(but see below). If the list begins with
+(but see below). If the list begins with
.QW \fB^\fR ,
it matches any single character (but see below) \fInot\fR from the
rest of the list.
@@ -171,22 +171,25 @@ rest of the list.
If two characters in the list are separated by
.QW \fB\-\fR ,
this is shorthand for the full \fIrange\fR of characters between those two
-(inclusive) in the collating sequence, e.g. \fB[0\-9]\fR in Unicode
-matches any conventional decimal digit. Two ranges may not share an
-endpoint, so e.g. \fBa\-c\-e\fR is illegal. Ranges in Tcl always use the
+(inclusive) in the collating sequence, e.g.
+.QW \fB[0\-9]\fR
+in Unicode matches any conventional decimal digit. Two ranges may not share an
+endpoint, so e.g.
+.QW \fBa\-c\-e\fR
+is illegal. Ranges in Tcl always use the
Unicode collating sequence, but other programs may use other collating
sequences and this can be a source of incompatability between programs.
.PP
To include a literal \fB]\fR or \fB\-\fR in the list, the simplest
method is to enclose it in \fB[.\fR and \fB.]\fR to make it a
-collating element (see below). Alternatively, make it the first
+collating element (see below). Alternatively, make it the first
character (following a possible
.QW \fB^\fR ),
or (AREs only) precede it with
.QW \fB\e\fR .
Alternatively, for
.QW \fB\-\fR ,
-make it the last character, or the second endpoint of a range. To use
+make it the last character, or the second endpoint of a range. To use
a literal \fB\-\fR as the first endpoint of a range, make it a
collating element or (AREs only) precede it with
.QW \fB\e\fR .
@@ -194,48 +197,7 @@ With the exception of
these, some combinations using \fB[\fR (see next paragraphs), and
escapes, all other special characters lose their special significance
within a bracket expression.
-.PP
-Within a bracket expression, a collating element (a character, a
-multi-character sequence that collates as if it were a single
-character, or a collating-sequence name for either) enclosed in
-\fB[.\fR and \fB.]\fR stands for the sequence of characters of that
-collating element. The sequence is a single element of the bracket
-expression's list. A bracket expression in a locale that has
-multi-character collating elements can thus match more than one
-character. So (insidiously), a bracket expression that starts with
-\fB^\fR can match multi-character collating elements even if none of
-them appear in the bracket expression! (\fINote:\fR Tcl has
-no multi-character collating elements. This information is only for
-illustration.)
-.PP
-For example, assume the collating sequence includes a \fBch\fR
-multi-character collating element. Then the RE \fB[[.ch.]]*c\fR (zero
-or more \fBch\fRs followed by \fBc\fR) matches the first five
-characters of
-.QW \fBchchcc\fR .
-Also, the RE \fB[^c]b\fR matches all of
-.QW \fBchb\fR
-(because \fB[^c]\fR matches the multi-character \fBch\fR).
-.PP
-Within a bracket expression, a collating element enclosed in \fB[=\fR
-and \fB=]\fR is an equivalence class, standing for the sequences of
-characters of all collating elements equivalent to that one, including
-itself. (If there are no other equivalent collating elements, the
-treatment is as if the enclosing delimiters were
-.QW \fB[.\fR \&
-and
-.QW \fB.]\fR .)
-For example, if \fBo\fR and \fB\N'244'\fR are the members of an
-equivalence class, then
-.QW \fB[[=o=]]\fR ,
-.QW \fB[[=\N'244'=]]\fR ,
-and
-.QW \fB[o\N'244']\fR \&
-are all synonymous. An equivalence class may
-not be an endpoint of a range. (\fINote:\fR Tcl implements only the
-Unicode locale. It does not define any equivalence classes. The
-examples above are just illustrations.)
-.PP
+.SS "CHARACTER CLASSES"
Within a bracket expression, the name of a \fIcharacter class\fR
enclosed in \fB[:\fR and \fB:]\fR stands for the list of all
characters (not all collating elements!) belonging to that class.
@@ -265,30 +227,94 @@ A character with a visible representation (includes both alnum and punct).
.IP \fBcntrl\fR 8
A control character.
.PP
-A locale may provide others. (Note that the current Tcl
-implementation has only one locale: the Unicode locale.) A character
-class may not be used as an endpoint of a range.
+A locale may provide others. A character class may not be used as an endpoint
+of a range.
+.RS
.PP
+(\fINote:\fR the current Tcl implementation has only one locale, the Unicode
+locale, which supports exactly the above classes.)
+.RE
+.SS "BRACKETED CONSTRAINTS"
There are two special cases of bracket expressions: the bracket
-expressions \fB[[:<:]]\fR and \fB[[:>:]]\fR are constraints, matching
-empty strings at the beginning and end of a word respectively.
-'\" note, discussion of escapes below references this definition of word
-A word is defined as a sequence of word characters that is neither
-preceded nor followed by word characters. A word character is an
-\fIalnum\fR character or an underscore (\fB_\fR). These special
-bracket expressions are deprecated; users of AREs should use
+expressions
+.QW \fB[[:<:]]\fR
+and
+.QW \fB[[:>:]]\fR
+are constraints, matching empty strings at the beginning and end of a word
+respectively.
+.\" note, discussion of escapes below references this definition of word
+A word is defined as a sequence of word characters that is neither preceded
+nor followed by word characters. A word character is an \fIalnum\fR character
+or an underscore
+.PQ \fB_\fR "" .
+These special bracket expressions are deprecated; users of AREs should use
constraint escapes instead (see below).
+.SS "COLLATING ELEMENTS"
+Within a bracket expression, a collating element (a character, a
+multi-character sequence that collates as if it were a single
+character, or a collating-sequence name for either) enclosed in
+\fB[.\fR and \fB.]\fR stands for the sequence of characters of that
+collating element. The sequence is a single element of the bracket
+expression's list. A bracket expression in a locale that has
+multi-character collating elements can thus match more than one
+character. So (insidiously), a bracket expression that starts with
+\fB^\fR can match multi-character collating elements even if none of
+them appear in the bracket expression!
+.RS
+.PP
+(\fINote:\fR Tcl has no multi-character collating elements. This information
+is only for illustration.)
+.RE
+.PP
+For example, assume the collating sequence includes a \fBch\fR multi-character
+collating element. Then the RE
+.QW \fB[[.ch.]]*c\fR
+(zero or more
+.QW \fBch\fRs
+followed by
+.QW \fBc\fR )
+matches the first five characters of
+.QW \fBchchcc\fR .
+Also, the RE
+.QW \fB[^c]b\fR
+matches all of
+.QW \fBchb\fR
+(because
+.QW \fB[^c]\fR
+matches the multi-character
+.QW \fBch\fR ).
+.SS "EQUIVALENCE CLASSES"
+Within a bracket expression, a collating element enclosed in \fB[=\fR
+and \fB=]\fR is an equivalence class, standing for the sequences of
+characters of all collating elements equivalent to that one, including
+itself. (If there are no other equivalent collating elements, the
+treatment is as if the enclosing delimiters were
+.QW \fB[.\fR \&
+and
+.QW \fB.]\fR .)
+For example, if \fBo\fR and \fB\N'244'\fR are the members of an
+equivalence class, then
+.QW \fB[[=o=]]\fR ,
+.QW \fB[[=\N'244'=]]\fR ,
+and
+.QW \fB[o\N'244']\fR \&
+are all synonymous. An equivalence class may not be an endpoint of a range.
+.RS
+.PP
+(\fINote:\fR Tcl implements only the Unicode locale. It does not define any
+equivalence classes. The examples above are just illustrations.)
+.RE
.SH ESCAPES
Escapes (AREs only), which begin with a \fB\e\fR followed by an
alphanumeric character, come in several varieties: character entry,
-class shorthands, constraint escapes, and back references. A \fB\e\fR
+class shorthands, constraint escapes, and back references. A \fB\e\fR
followed by an alphanumeric character but not constituting a valid
-escape is illegal in AREs. In EREs, there are no escapes: outside a
+escape is illegal in AREs. In EREs, there are no escapes: outside a
bracket expression, a \fB\e\fR followed by an alphanumeric character
merely stands for that character as an ordinary character, and inside
-a bracket expression, \fB\e\fR is an ordinary character. (The latter
+a bracket expression, \fB\e\fR is an ordinary character. (The latter
is the one actual incompatibility between EREs and AREs.)
-.PP
+.SS "CHARACTER-ENTRY ESCAPES"
Character-entry escapes (AREs only) exist to make it easier to specify
non-printing and otherwise inconvenient characters in REs:
.RS 2
@@ -380,13 +406,13 @@ Octal digits are
.PP
The character-entry escapes are always taken as ordinary characters.
For example, \fB\e135\fR is \fB]\fR in Unicode, but \fB\e135\fR does
-not terminate a bracket expression. Beware, however, that some
+not terminate a bracket expression. Beware, however, that some
applications (e.g., C compilers and the Tcl interpreter if the regular
expression is not quoted with braces) interpret such sequences
themselves before the regular-expression package gets to see them,
which may require doubling (quadrupling, etc.) the
.QW \fB\e\fR .
-.PP
+.SS "CLASS-SHORTHAND ESCAPES"
Class-shorthand escapes (AREs only) provide shorthands for certain
commonly-used character classes:
.RS 2
@@ -426,10 +452,16 @@ lose their outer brackets, and
.QW \fB\eS\fR ,
and
.QW \fB\eW\fR \&
-are illegal. (So, for example, \fB[a-c\ed]\fR is
-equivalent to \fB[a-c[:digit:]]\fR. Also, \fB[a-c\eD]\fR, which is
-equivalent to \fB[a-c^[:digit:]]\fR, is illegal.)
-.PP
+are illegal. (So, for example,
+.QW \fB[a-c\ed]\fR
+is equivalent to
+.QW \fB[a-c[:digit:]]\fR .
+Also,
+.QW \fB[a-c\eD]\fR ,
+which is equivalent to
+.QW \fB[a-c^[:digit:]]\fR ,
+is illegal.)
+.SS "CONSTRAINT ESCAPES"
A constraint escape (AREs only) is a constraint, matching the empty
string if specific conditions are met, written as an escape:
.RS 2
@@ -474,13 +506,20 @@ closing capturing parentheses seen so far) a \fIback reference\fR, see
below
.RE
.PP
-A word is defined as in the specification of \fB[[:<:]]\fR and
-\fB[[:>:]]\fR above. Constraint escapes are illegal within bracket
-expressions.
-.PP
+A word is defined as in the specification of
+.QW \fB[[:<:]]\fR
+and
+.QW \fB[[:>:]]\fR
+above. Constraint escapes are illegal within bracket expressions.
+.SS "BACK REFERENCES"
A back reference (AREs only) matches the same string matched by the
parenthesized subexpression specified by the number, so that (e.g.)
-\fB([bc])\e1\fR matches \fBbb\fR or \fBcc\fR but not
+.QW \fB([bc])\e1\fR
+matches
+.QW \fBbb\fR
+or
+.QW \fBcc\fR
+but not
.QW \fBbc\fR .
The subexpression must entirely precede the back reference in the RE.
Subexpressions are numbered in the order of their leading parentheses.
@@ -488,9 +527,9 @@ Non-capturing parentheses do not define subexpressions.
.PP
There is an inherent historical ambiguity between octal
character-entry escapes and back references, which is resolved by
-heuristics, as hinted at above. A leading zero always indicates an
-octal escape. A single non-zero digit, not followed by another digit,
-is always taken as a back reference. A multi-digit sequence not
+heuristics, as hinted at above. A leading zero always indicates an
+octal escape. A single non-zero digit, not followed by another digit,
+is always taken as a back reference. A multi-digit sequence not
starting with a zero is taken as a back reference if it comes after a
suitable subexpression (i.e. the number is in the legal range for a
back reference), and otherwise is taken as octal.
@@ -762,7 +801,10 @@ it appears at the beginning of the RE or the beginning of a
parenthesized subexpression (after a possible leading
.QW \fB^\fR ).
Finally, single-digit back references are available, and \fB\e<\fR and
-\fB\e>\fR are synonyms for \fB[[:<:]]\fR and \fB[[:>:]]\fR
+\fB\e>\fR are synonyms for
+.QW \fB[[:<:]]\fR
+and
+.QW \fB[[:>:]]\fR
respectively; no other escapes are available.
.SH "SEE ALSO"
RegExp(3), regexp(n), regsub(n), lsearch(n), switch(n), text(n)