@need 3200

@node An Introduction to XML Regular Expressions
@appendix An Introduction to XML Regular Expressions

@geindex XML regular expression

@geindex regular expression (XML)



This chapter informally describes "XML regular expressions" as
supported by Rx.


A @geindex regular expression
@dfn{regular expression} describes a textual pattern: a string of
characters either matches (fits the pattern) or does not match (does
not fit the pattern).  Regular expressions have many applications
associated with searching, editing, and parsing text.  Typically, a
program allows users to specify a regular expression, then it searches
for text that matches that expression.  In XML Schema, regular
expressions are used to define "lexical spaces" (the set of valid
literals for a datatype).


@geindex XML

@geindex W3C

@geindex Schema (XML)

@geindex XML Schema



The syntax and semantics of XML regular expressions is defined in the
W3C document @emph{XML Schema Part 2: Datatypes}
(@url{http://www.w3.org/TR/xmlschema-2} ).

@menu
* Literal and Special Characters::
* Single Character Escapes::
* Dot::
* Multi-character Escapes::
* Category Escapes::
* Character Sets::
* Parenthesized Expressions::
* Repeated Expressions::
* Optional Expressions::
* Counted Iteration::
* Alternative Expressions::
* A Summary of Regular Expression Syntax::
@end menu

@need 3200

@node Literal and Special Characters
@section Literal and Special Characters

@geindex literal characters (in XML regexps)

@geindex special characters (in XML regexps)



In the simplest cases, a regular expression is just a literal string
that must match exactly.  For example, the pattern:

@example
@group
     regular expression
@end group
@group
@end group
@end example

@noindent
matches the string "regular expression" and no others.


Some characters have a special meaning when they occur in a regular
expression.  They aren't matched literally as in the previous example,
but instead denote a more general pattern.  For example, the character
@code{*} is used to indicate that the preceding element of a regular
expression may be repeated @code{0}, @code{1}, or more times.  In the pattern:

@example
@group
     smooo*th
@end group
@group
@end group
@end example

@noindent
the @code{*} indicates that the preceding @code{o} can be repeated @code{0} or more
times.  So the pattern matches:

@example
@group
     smooth
     smoooth
     smooooth
     smoooooth
     ...
@end group
@group
@end group
@end example

The same pattern does not match these examples:

@example
@group
     smoth      -- The pattern requires at least two o's
     smoo*th    -- The pattern doesn't match the *
@end group
@group
@end group
@end example

Suppose you want to write a pattern that literally matches a special
character like @code{*}; in other words, you don't want to @code{*} to indicate
a permissible repetition, but to match @code{*} literally.  This is
accomplished by quoting @geindex quoting (in XML regexps)
 the special character with a backslash.  The
pattern:

@example
@group
     smoo\*th
@end group
@group
@end group
@end example

@noindent
matches the string:

@example
@group
     smoo*th
@end group
@group
@end group
@end example

@noindent
and no other strings.


These characters are special (their meaning is described in this
chapter):

@example
@group
     . \ | ? * + @{ @} ( ) [ ]
@end group
@group
@end group
@end example

The remaining sections of this chapter introduce and explain the
various special characters that can occur in regular expressions.




@need 3200

@node Single Character Escapes
@section Single Character Escapes

@geindex single character escapes (in XML regular expressions)

@geindex \t (in XML regular expressions)

@geindex \n (in XML regular expressions)

@geindex \r (in XML regular expressions)



These three expressions each match a single, literal character:

@example
@group
        \t      -- matches tab (U+0008)
        \n      -- matches newline (U+000A)
        \r      -- matches carriage return (U+000D)
@end group
@group
@end group
@end example



@need 3200

@node Dot
@section Dot

@geindex dot operator (in XML regular expressions)

@geindex . (in XML regular expressions)



@code{.} ordinarily matches nearly any character.

@example
@group
     p.ck
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     pick
     pack
     puck
     pbck
     pcck
     p.ck
@end group
@group
@end group
@end example

@noindent
etc.


To be more specific, @code{.} matches any character which is valid in an
XML document except for newline (U+000A) and carriage return (U+000D).




@need 3200

@node Multi-character Escapes
@section Multi-character Escapes

@geindex multi-character escapes (in XML regular expressions)

@geindex \s  (in XML regular expressions)

@geindex \i (in XML regular expressions)

@geindex \c (in XML regular expressions)

@geindex \d (in XML regular expressions)

@geindex \w (in XML regular expressions)

@geindex \S (in XML regular expressions)

@geindex \I (in XML regular expressions)

@geindex \C (in XML regular expressions)

@geindex \D (in XML regular expressions)

@geindex \W (in XML regular expressions)

@geindex name characters (in XML regular expressions)

@geindex digits (in XML regular expressions)

@geindex spaces (in XML regular expressions)

@geindex word characters (in XML regular expressions)



Literal characters match a specific character.  Multi-character
escapes match any of a set of characters.  The multi-character escapes
understood by Rx are:

@example
@group
        \s      -- spaces
        \i      -- first character of a "name"
        \c      -- subsequent character of a "name"
        \d      -- digits
        \w      -- word characters
@end group
@group
@end group
@end example

@code{\s} matches a single space, tab, newline, or carriage return.


The set of characters valid as the first or subsequent characters in a
name (matched by @code{\i} and @code{\c} respectively) are as defined in XML.


The set of characters matched by @code{\d} is as defined in XML and
includes most Unicode characters with general category @code{Nd}.


The set of characters matched by @code{\w} includes all characters which
are valid in an XML document except those with a general category in
class @code{P} (punctuation), @code{Z} (separators), and @code{C} (other, such as
control characters and unassigned code points).


Each of the multi-character escapes can be negated by writing it
as a capital letter:

@example
@group
        \S      -- non-spaces
        \I      -- not the first character of a "name"
        \C      -- not a subsequent character of a "name"
        \D      -- non-digits
        \W      -- non-word characters
@end group
@group
@end group
@end example



@need 3200

@node Category Escapes
@section Category Escapes

@geindex category escapes (in XML regular expressions)

@geindex Unicode categories (in XML regular expressions)

@geindex categories (Unicode categories in XML regular expressions)

@geindex Unicode blocks (in XML regular expressions)

@geindex \p@{@} (in XML regular expressions)

@geindex \P@{@} (in XML regular expressions)



Category escapes are similar to multi-character escapes: they match
any of a set of characters.  The default set of category escapes refer
to the character categories and block names of Unicode.  (For
information about categories and blocks, see a recent version of @emph{The
Unicode Standard} or visit @url{http://www.unicode.org} ).


A category escape based on a Unicode category is be written:

@example
@group
        \p@{<category name>@}
@end group
@group
@end group
@end example

@noindent
for example:

@example
@group
        \p@{L@}           -- letters
        \p@{Lu@}          -- upper case letters
        \p@{Nd@}          -- digits
@end group
@group
@end group
@end example

A category escape based on a Unicode block name can is written:

@example
@group
        \p@{is<block name>@}
@end group
@group
@end group
@end example

@noindent
for example:

@example
@group
        \p@{isBasicLatin@}
        \p@{isCherokee@}
        \p@{isUnifiedCanadianAboriginalSyllabics@}
@end group
@group
@end group
@end example

Any category can be negated by use '\P' instead of '\p':

@example
@group
        \P@{L@}           -- non-Letters
        \P@{isCherokee@}  -- characters which are not in
                           the Cherokee block
@end group
@group
@end group
@end example

In all cases, the set of characters is further restricted to include
only characters that are valid in XML documents.




@need 3200

@node Character Sets
@section Character Sets

@geindex character set operator (in XML regular expressions)

@geindex [...] (in XML regular expressions)



@code{[} begins a "character set".  A character set matches any of a set
of characters which are explicitly enumerated in the regular
expression.


There are two basic forms a character set can take.


The first form is a plain character set:

@example
@group
     [<cset-spec>]      -- every character in <cset-spec> is in the set.
@end group
@group
@end group
@end example

@noindent
the second form is a negated character set: 


@geindex negated character set (in XML regular expressions)


@example
@group
     [^<cset-spec>]     -- every character *not* in <cset-spec>
                           is in the set.
@end group
@group
@end group
@end example

A @code{<cset-spec>} is a more or less an explicit enumeration of a set of
characters.  It can be written as a string of individual characters:

@example
@group
     [ABC]              -- matches 'A', 'B', or 'C'
@end group
@group
@end group
@end example

@geindex character ranges (in XML regular expressions)

@geindex range of characters (in XML regular expressions)



@noindent
or as a range of characters:

@example
@group
     [0-9]              -- matches any decimal digit
@end group
@group
@end group
@end example

These two forms can be mixed:

@example
@group
     [A-za-z0-9_$]      -- any Basic Latin letter (either case), 
                           any Basic Latin digit, `_' or `$'
@end group
@group
@end group
@end example

Negation allows you to specify which characters are not in the set:

@example
@group
     [^0-9]             -- match any character which is not a 
                           Basic Latin digit
@end group
@group
@end group
@end example

Special characters can be included within a character set, in the
usual way, by quoting them with @code{\}:

@example
@group
     [\-abc]            -- match '-', 'a', 'b', or 'c'
@end group
@group
@end group
@end example

Single character escapes, multi-character escapes, and category
escapes can all be used in a @code{<cset-spec>}:

@example
@group
    [\t\n\r]            -- match tab, newline, or return 
@end group
@group
@end group
@end example
@example
@group
    [\s\d]              -- match any space character or digit
@end group
@group
@end group
@end example
@example
@group
    [^\p@{Nd@}\p@{Ll@}]     -- match all but digits and lowercase 
                           letters
@end group
@group
@end group
@end example

@geindex character set subtraction (in XML regular expressions)

@geindex subtraction (character set subtraction in XML regular expressions)



From the two basic forms of character set, two additional forms
of character set can be formed, called "character set subtractions":

@example
@group
     [<cset-spec>-<character set>]
                        -- every character in <cset-spec> except
                           those in in <character set>
@end group
@group
@end group
@end example
@example
@group
     [^<cset-spec>-<character set>]
                        -- every character not in <cset-spec> 
                           except those in <character set>
@end group
@group
@end group
@end example

For example:

@example
@group
     [\p@{L@}-[\p@{isBasicLatin@}\p@{isGreek@}]]
                        -- match any letter except for letters
                           in the Basic Latin or Greek blocks
@end group
@group
@end group
@end example
@example
@group
     [^\p@{L@}-[\p@{isBasicLatin@}\p@{isGreek@}]]
                        -- match any non-letter except for
                           non-letters in the Basic Latin or
                           Greek blocks
@end group
@group
@end group
@end example



@need 3200

@node Parenthesized Expressions
@section Parenthesized Expressions

@geindex parenthesized subexpression (in XML regular expressions)

@geindex (...) (in XML regular expressions)



A subexpression is a regular expression enclosed in @code{(} and @code{)}.  A
subexpression can be used anywhere a single character or character set
can be used.


Subexpressions are useful for grouping regular expression constructs.  For
example, the repeat operator, @code{*}, usually applies to just the
preceding character.  Recall that:

@example
@group
     smooo*th
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     smooth
     smoooth
     ...
@end group
@group
@end group
@end example

Using a subexpression, we can apply @code{*} to a longer string:

@example
@group
     banan(an)*a
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     banana
     bananana
     banananana
     ...
@end group
@group
@end group
@end example



@need 3200

@node Repeated Expressions
@section Repeated Expressions

@geindex repeated subexpression (in XML regular expressions)

@geindex * (in XML regular expressions)



As previously explained, @code{*} is the repeat operator.  It applies to
the preceding character, character set, or subexpression.  It
indicates that the preceding element can be matched @code{0} or more times:

@example
@group
     bana(na)*
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     bana
     banana
     bananana
     banananana
     ...
@end group
@group
@end group
@end example

@geindex + (in XML regular expressions)

@code{+} is similar to @code{*} except that @code{+} requires the preceding element
to be matched at least once.  So on the one hand:

@example
@group
     bana(na)*
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     bana
@end group
@group
@end group
@end example

@noindent
but

@example
@group
     bana(na)+
@end group
@group
@end group
@end example

@noindent
does not.   Both match

@example
@group
     banana
     bananana
     banananana
     ...
@end group
@group
@end group
@end example



@need 3200

@node Optional Expressions
@section Optional Expressions

@geindex optional subexpression (in XML regular expressions)

@geindex ? (in XML regular expressions)



@code{?} indicates that the preceding character, character set, or
subexpression is optional.  It is permitted to match, or to be
skipped:

@example
@group
     CSNY?
@end group
@group
@end group
@end example

@noindent
matches both

@example
@group
     CSN
@end group
@group
@end group
@end example

@noindent
and

@example
@group
     CSNY
@end group
@group
@end group
@end example



@need 3200

@node Counted Iteration
@section Counted Iteration

@geindex counted iteration (in XML regular expressions)

@geindex interval expression (in XML regular expressions)

@geindex @{...@} (in XML regular expressions)



The interval operator, @code{@{m,n@}} (where @code{m} and @code{n} are decimal integers
and @code{0 <= m <= n}) indicates that the preceding character, character
set, or subexpression must match at least @code{m} times and may match as
many as @code{n} times.


For example:

@example
@group
     c([ad])@{1,4@}r
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     car
     cdr
     caar
     cdar
     ...
@end group
@group
     caaar
     cdaar
     ...
     cadddr
     cddddr
@end group
@group
@end group
@end example

@noindent
but it doesn't match:

@example
@group
     cdddddr
@end group
@group
@end group
@end example

@noindent
because that has five d's, and the pattern only permits four, and it
doesn't match

@example
@group
     cr
@end group
@group
@end group
@end example

@noindent
because the pattern requires at least one @code{a} or @code{d}.


A pattern of the form:

@example
@group
        R@{M,@}
@end group
@group
@end group
@end example

@noindent
matches @code{M} or more iterations of @code{R}.


A pattern of the form:

@example
@group
        R@{M@}
@end group
@group
@end group
@end example

@noindent
matches exactly 'M' iterations of 'R'.




@need 3200

@node Alternative Expressions
@section Alternative Expressions

@geindex alternative subexpressions (in XML regular expressions)

@geindex | (in XML regular expressions)



An alternative is written:

@example
@group
     regular expression-1|regular expression-2|regular expression-3|...
@end group
@group
@end group
@end example

It matches anything matched by some @code{regular expression-n}.  For example:

@example
@group
     Crosby, Stills, (and Nash|Nash, and Young)
@end group
@group
@end group
@end example

@noindent
matches

@example
@group
     Crosby, Stills, and Nash
@end group
@group
@end group
@end example

@noindent
and also

@example
@group
     Crosby, Stills, Nash, and Young
@end group
@group
@end group
@end example



@need 3200

@node A Summary of Regular Expression Syntax
@section A Summary of Regular Expression Syntax

@geindex regular expression syntax summary (XML)



In summary, regular expressions can be:

@example
@group
   `abcd'               - a string literal
@end group
@group
@end group
@end example
@example
@group
   `\*'                 - an escaped special character
@end group
@group
@end group
@end example
@example
@group
   `\n'                 - a single character escape
@end group
@group
@end group
@end example
@example
@group
   `\s'                 - a multi-character escape
@end group
@group
@end group
@end example
@example
@group
   `\p@{isCherokee@}'     - a category escape
@end group
@group
@end group
@end example
@example
@group
   `.'                  - the universal character set.
@end group
@group
@end group
@end example
@example
@group
   `[a-z_?]'            - a character set
@end group
@group
@end group
@end example
@example
@group
   `[^abz_?]'           - an negated character set
@end group
@group
@end group
@end example
@example
@group
   `[\p@{L@}-[\p@{isBasicLatin@}\p@{isGreek@}]]' -
                          character set subtraction
@end group
@group
@end group
@end example
@example
@group
   `(subexp)'           - an expression grouped to form a
                          parenthesized subexpression. 
@end group
@group
@end group
@end example

The following special characters and sequences can be applied to a
character, character set, or subexpression:

@example
@group
   `*'                  - repeat the preceding element 0 
                          or more times.
@end group
@group
@end group
@end example
@example
@group
   `+'                  - repeat the preceding element 1 
                          or more times.
@end group
@group
@end group
@end example
@example
@group
   `?'                  - match the preceding element 0 
                          or 1 time.
@end group
@group
@end group
@end example
@example
@group
   `@{m,n@}'              - match the preceding element at 
                          least `m', and as many as `n' times,
                          where 0 <= m <= n
@end group
@group
@end group
@end example
@example
@group
   `@{m,@}'               - match the preceding element at 
                          least `m' times, where 0 <= m 
@end group
@group
@end group
@end example
@example
@group
   `@{m@}'                - match the preceding element exactly
                          `m' times, where 0 <= m 
@end group
@group
@end group
@end example

Finally, a list of patterns built from the preceeding operators can be
combined using @code{|}:

@example
@group
   `regular expression-1|regular expression-2|..' 
                        - match regular expression-1 or regex-2 or ...
@end group
@group
@end group
@end example

A special character, like @code{.} or @code{*} can be made into a literal by
prefixing it with @code{\}.


A special sequence, like @code{+} or @code{?} can be made into a literal
character by dropping the @code{\}.







