@need 3200

@node XML Regular Expressions
@chapter XML Regular Expressions

The W3C document @emph{XML Schema Part 2: Datatypes} defines a regular
expression language for use in XML Schema.  (See
@url{http://www.w3.org/TR/xmlschema-2} .)


This chapter presents C functions used for matching XML regular
expressions.  (See @ref{An Introduction to XML Regular Expressions}.)

@menu
* XML Regular Expression Functions::
* Using Rx in XML Processors::
@end menu

@need 3200

@node XML Regular Expression Functions
@section XML Regular Expression Functions
@noindent
@strong{#include <hackerlab/rx-unicode/re.h>}@*
@sp 1

@geindex XML regular expression

@geindex regular expression (XML)


@menu
* Compiling XML Regular Expressions::
* Compiling With Syntax Options::
* Freeing a Compiled XML Regular Expression::
* Comparing a String To An XML Regular Expression::
@end menu

@need 3200

@node Compiling XML Regular Expressions
@subsection Compiling XML Regular Expressions

The functions in this section compile regular expressions using the
syntax defined for XML Schema.  (See also @ref{Using Rx in XML Processors}.)

@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_recomp}@fuindex rx_xml_recomp
@*
@example
@group
enum rx_xml_recomp_errno
rx_xml_recomp (rx_xml_rebuf * re,
               enum uni_encoding_scheme encoding,
               uni_string * source,
               size_t length);
@end group
@group
@end group
@end example

Compile a regular expression using XML syntax.


@code{re} is an opaque output parameter which will be filled with
the compiled expression.


@code{encoding} describes the encoding scheme of the source expression.
It may be any of:

@example
@group
     uni_iso8859_1,          8-bit characters (u+0..u+255 only)
     uni_utf8,               UTF-8 encoding
     uni_utf16,              UTF-16 in native byte order
@end group
@group
@end group
@end example

Note that the encoding scheme of the source expression has no bearing
on the encoding scheme of strings tested for a match.


@code{source} points to the source for the regular expression, a string
encoded in the manner specified by @code{encoding}.  


@code{length} is the size of the source expression, measured in code units.


Return @code{0} upon success, an error code otherwise.  See
@code{<hackerlab/rx-unicode/re.h>} for the list of error codes.
The list of error codes is likely to change in future releaes.
Future releases will add a function for translating 
error codes to error messages.

@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_recomp_branch}@fuindex rx_xml_recomp_branch
@*
@example
@group
enum rx_xml_recomp_errno
rx_xml_recomp_branch (rx_xml_rebuf * re,
                      enum uni_encoding_scheme encoding,
                      uni_string source,
                      size_t length);
@end group
@group
@end group
@end example

Compile a Unicode regular expression in XML syntax adding an
alternative branch to an already compiled expression.


Parameters and return values are as to @strong{rx_xml_recomp} except
that @code{re} must contain an already compiled expression.


If, on entry, @code{re} contains a compiled form of expression @code{RE1},
and @code{source} points to expression @code{RE2}, the result is the same as
if the expression:

@example
@group
             (RE1)|(RE2)
@end group
@group
@end group
@end example

@noindent
were compiled.




@need 3200

@node Compiling With Syntax Options
@subsection Compiling With Syntax Options

@geindex syntax options

@geindex compiling regular expressions (any syntax)



The function in this section compiles Unicode regular expressions
using any of a variety of syntaxes which can be selected by
options provided to @code{rx_xml_recomp_opts}.

@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_recomp_opts}@fuindex rx_xml_recomp_opts
@*
@example
@group
enum rx_xml_recomp_errno
rx_xml_recomp_opts (rx_xml_rebuf * re,
                    enum uni_encoding_scheme encoding,
                    uni_string source,
                    size_t length,
                    t_ulong syntax_options,
                    bits cset);
@end group
@group
@end group
@end example

Compile a Unicode regular expression.


Parameters @code{re}, @code{encoding}, @code{source}, and @code{length} are as to
@strong{rx_xml_recomp} in @ref{Compiling XML Regular Expressions}.


@code{syntax_options} indicates what regular expression syntax to use
and how to interpret that syntax.  It is a bit-wise @emph{@strong{or}} of any of:

@example
@group
     rx_xml_syntax_unicode_escapes
         Permit numeric character escapes ("\u+xxxx" and "\v+xxxxxx")
@end group
@group
@end group
@end example
@example
@group
     rx_xml_syntax_consistent_metacharacters
         Require all special characters to be escaped in 
         character class expressions.  Ordinarily,
         some special characters do not need to be 
         escaped in character class expressions (as per
         XML syntax).
@end group
@group
@end group
@end example
@example
@group
     rx_xml_syntax_dot_dot_ranges
         Use ".." instead of "-" to indicate character ranges
         in character class expressions ("[a..z]")
@end group
@group
@end group
@end example
@example
@group
     rx_xml_syntax_carrot_set_difference
         Use "^" instead of "-" to indicate character set
         subtraction ("[\p@{L@}^[a..z]]")
@end group
@group
@end group
@end example
@example
@group
     rx_xml_syntax_add_branch
         `re' must contain a previously compiled expression.
         Compile this expression as an alternative branch.
@end group
@group
@end group
@end example
@example
@group
     rx_xml_syntax_no_newlines
     rx_xml_syntax_no_cr
     rx_xml_syntax_no_linesep
         Do not include newline (carriage return, line separator) 
         in the character set matched by `.' or (implicitly) in
         negated character set expressions.
@end group
@group
@end group
@end example
@example
@group
     rx_xml_syntax_dot_star_prefix
         Compile the expression as if it were prefixed by:
@end group
@group
@end group
@end example
@example
@group
             `(.*)'
@end group
@group
@end group
@end example

Passing @code{0} or @code{rx_xml_syntax_xml} for @code{syntax_options} 
causes XML syntax to be used.


@code{cset} is the set of all valid code code points.


Common choices for @code{cset} are:

@example
@group
     xml_charset     -- the set of code points permitted in 
                        XML documents (declared in 
                        <hackerlab/xml/charsets.h>
@end group
@group
@end group
@end example
@example
@group
     unidata_bitset_universal -- the set of all assigned
                        code points (declared in
                        <hackerlab/unicode/unicode.h>
@end group
@group
@end group
@end example



@need 3200

@node Freeing a Compiled XML Regular Expression
@subsection Freeing a Compiled XML Regular Expression
@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_free_re}@fuindex rx_xml_free_re
@*
@example
@group
void rx_xml_free_re (rx_xml_rebuf * re);
@end group
@group
@end group
@end example

Release all storage associated with a previously compiled expression.
This does not free the memory pointed to by @code{re}.




@need 3200

@node Comparing a String To An XML Regular Expression
@subsection Comparing a String To An XML Regular Expression
@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_is_match}@fuindex rx_xml_is_match
@*
@example
@group
int rx_xml_is_match (enum rx_xml_rematch_errno * errn,
                     rx_xml_rebuf * re,
                     enum uni_encoding_scheme encoding,
                     uni_string * string,
                     size_t length);
@end group
@group
@end group
@end example

Compare the compiled expression @code{re} to @code{string}.  Return @code{1} if the
entire string matches, @code{0} if it does not, and @code{-1} if an error
occurs.


@code{errn} is an output parameter that returns an error code if an
error occurs (see @code{<hackerlab/rx-unicode/re.h>} for the list of error
codes.  The list of error codes is likely to change in future
releaes.  Future releases will add a function for translating error
codes to error messages.


@code{re} is a previously compiled regular expression.


@code{encoding} describes the encoding scheme of @code{string}.
It may be any of:

@example
@group
     uni_iso8859_1,          8-bit characters (u+0..u+255 only)
     uni_utf8,               UTF-8 encoding
     uni_utf16,              UTF-16 in native byte order
@end group
@group
@end group
@end example

@code{string} is the string to test for a match, encoded according to
@code{encoding}.  


@code{length} is the length of that string in code units.

@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_longest_match}@fuindex rx_xml_longest_match
@*
@example
@group
enum rx_xml_longest_status
rx_xml_longest_match (enum rx_xml_rematch_errno * errn,
                      size_t * match_len,
                      rx_xml_rebuf * re,
                      enum uni_encoding_scheme encoding,
                      uni_string string,
                      size_t length)
@end group
@group
@end group
@end example

Look for the longest matching prefix of @code{string}.  There are
five possible return values:

@example
@group
    rx_xml_longest_error
             An error occured (check *errn).
@end group
@group
@end group
@end example
@example
@group
    rx_xml_longest_out_of_input_match
             A match was found.  If the string were longer,
             a longer match might be found.
@end group
@group
@end group
@end example
@example
@group
    rx_xml_longest_out_of_input_nomatch
             No match was found.  If the string were longer,
             a match might be found.
@end group
@group
@end group
@end example
@example
@group
    rx_xml_longest_found
             The longest possible match was found.
@end group
@group
@end group
@end example
@example
@group
    rx_xml_longest_nomatch
             No prefix matches.
@end group
@group
@end group
@end example

@code{errn} is an output parameter that returns an error code if an
error occurs (see @code{<hackerlab/rx-unicode/re.h>} for the list of error
codes).  The list of error codes is likely to change in future
releaes.  Future releases will add a function for translating error
codes to error messages.


@code{match_len} returns the length (in code units) of the longest match
found (if any).


@code{re} is a previously compiled regular expression.


@code{encoding} describes the encoding scheme of @code{string}.
It may be any of:

@example
@group
     uni_iso8859_1,          8-bit characters (u+0..u+255 only)
     uni_utf8,               UTF-8 encoding
     uni_utf16,              UTF-16 in native byte order
@end group
@group
@end group
@end example

@code{string} is the string to test for a match, encoded according to
@code{encoding}.  


@code{length} is the length of that string in code units.

@sp 1
@need 1750
@noindent
@b{* Function} @code{rx_xml_prefix_match}@fuindex rx_xml_prefix_match
@*
@example
@group
enum rx_xml_prefix_status
rx_xml_prefix_match (enum rx_xml_rematch_errno * errn,
                     rx_xml_rebuf * re,
                     enum uni_encoding_scheme encoding,
                     uni_string string,
                     size_t length);
@end group
@group
@end group
@end example

Look for any matching prefix of @code{string}.  Note that this
function does not look for the @emph{longest} matching prefix,
and does not return the length of the prefix found -- it
merely verifies the existence of @emph{some} matching prefix.


There are four possible return values:

@example
@group
    rx_xml_prefix_error
             An error occured (check *errn).
@end group
@group
@end group
@end example
@example
@group
    rx_xml_prefix_out_of_input
             No match was found.  If the string were longer,
             a match might be found.
@end group
@group
@end group
@end example
@example
@group
    rx_xml_prefix_found
             A matching prefix was found.
@end group
@group
@end group
@end example
@example
@group
    rx_xml_prefix_nomatch
             No prefix matches.
@end group
@group
@end group
@end example

@code{errn} is an output parameter that returns an error code if an
error occurs (see @code{<hackerlab/rx-unicode/re.h>} for the list of error
codes).  The list of error codes is likely to change in future
releaes.  Future releases will add a function for translating error
codes to error messages.


@code{re} is a previously compiled regular expression.


@code{encoding} describes the encoding scheme of @code{string}.
It may be any of:

@example
@group
     uni_iso8859_1,          8-bit characters (u+0..u+255 only)
     uni_utf8,               UTF-8 encoding
     uni_utf16,              UTF-16 in native byte order
@end group
@group
@end group
@end example

@code{string} is the string to test for a match, encoded according to
@code{encoding}.  


@code{length} is the length of that string in code units.







@need 3200

@node Using Rx in XML Processors
@section Using Rx in XML Processors

@geindex XML processors (using Rx in)

@geindex XML Schema



XML Schema datatype definitions can use regular expressions in
@code{pattern} facets to define the syntax of a value space.  For
information on this topic, see the @emph{W3C} document @emph{XML Schema: Part
2}, @url{http://www.w3.org/TR/xmlschema-2} .


The functions @strong{rx_xml_recomp} in @ref{Compiling XML Regular Expressions}, @strong{rx_xml_recomp_branch} in @ref{Compiling XML Regular Expressions}, and
@strong{rx_xml_is_match} in @ref{Comparing a String To An XML Regular Expression} were designed specifically for @code{pattern}
schema.


@code{rx_xml_recomp} compiles the regular expression syntax of @code{pattern}
facets.  (See @ref{Comments on the XML Schema Regular Expression Syntax}.)


If a @code{pattern} facet contains more than one regular expression, they
are supposed to be combined as alternative branches (see section @emph{5.2.4} of @emph{XML Schema: Part 2}).  The function @code{rx_xml_recomp_branch}
provides an easy implementation of this functionality.


Finally, @code{rx_xml_is_match} compares an entire string to a regular
expression -- the test required to validate a @code{pattern} constraint.







