From: Václav Slavík Date: Thu, 19 Feb 2004 18:02:48 +0000 (+0000) Subject: applied patch 890642: wxRE_ADVANCED flag and docs X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/0aa7fa9afdd1499d06b56bcff8adcd4adb6ca3f7?hp=4996f26121bacb8ce4dc4a0f00c638f6b6b802bb applied patch 890642: wxRE_ADVANCED flag and docs git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@25870 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/autoconf_inc.m4 b/autoconf_inc.m4 index 476509c6fc..1e7be34afa 100644 --- a/autoconf_inc.m4 +++ b/autoconf_inc.m4 @@ -2,9 +2,6 @@ dnl This macro was generated by dnl Bakefile 0.1.3 (http://bakefile.sourceforge.net) dnl Do not modify, all changes will be overwritten! - -dnl Conditions: - dnl ### begin block 0_AC_BAKEFILE_PRECOMP_HEADERS ### AC_BAKEFILE_PRECOMP_HEADERS diff --git a/docs/latex/wx/re_syntax.tex b/docs/latex/wx/re_syntax.tex new file mode 100644 index 0000000000..677dad856f --- /dev/null +++ b/docs/latex/wx/re_syntax.tex @@ -0,0 +1,676 @@ +% manual page source format generated by PolyglotMan v3.0.9, +% available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z + +\section{Syntax of the builtin regular expression library}\label{wxresyn} + +A {\it regular expression} describes strings of characters. It's a +pattern that matches certain strings and doesn't match others. + +\wxheading{See also} + +\helpref{wxRegEx}{wxregex} + + +\subsection{Different Flavors of REs} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +Regular expressions (``RE''s), as defined by POSIX, come in two +flavors: {\it extended} REs (``EREs'') and {\it basic} REs (``BREs''). EREs are roughly those +of the traditional {\it egrep}, while BREs are roughly those of the traditional + {\it ed}. This implementation adds a third flavor, {\it advanced} REs (``AREs''), basically +EREs with some significant extensions. + +This manual page primarily describes +AREs. BREs mostly exist for backward compatibility in some old programs; +they will be discussed at the \helpref{end}{wxresynbre}. POSIX EREs are almost an exact subset +of AREs. Features of AREs that are not present in EREs will be indicated. + + +\subsection{Regular Expression Syntax} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +These regular expressions are implemented using +the package written by Henry Spencer, based on the 1003.2 spec and some +(not quite all) of the Perl5 extensions (thanks, Henry!). Much of the description +of regular expressions below is copied verbatim from his manual entry. + +An +ARE is one or more {\it branches}, separated by `{\bf $|$}', matching anything that matches +any of the branches. + +A branch is zero or more {\it constraints} or {\it quantified +atoms}, concatenated. It matches a match for the first, followed by a match +for the second, etc; an empty branch matches the empty string. + +A quantified +atom is an {\it atom} possibly followed by a single {\it quantifier}. Without a quantifier, +it matches a match for the atom. The quantifiers, and what a so-quantified +atom matches, are: + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf *}}{a sequence of 0 or more matches of the atom} +\twocolitem{{\bf +}}{a sequence of 1 or more matches of the atom} +\twocolitem{{\bf ?}}{a sequence of 0 or 1 matches of the atom} +\twocolitem{{\bf \{m\}}}{a sequence of exactly {\it m} matches of the atom} +\twocolitem{{\bf \{m,\}}}{a sequence of {\it m} or more matches of the atom} +\twocolitem{{\bf \{m,n\}}}{a sequence of {\it m} through {\it n} (inclusive) +matches of the atom; {\it m} may not exceed {\it n}} +\twocolitem{{\bf *? +? ?? \{m\}? \{m,\}? \{m,n\}?}}{{\it non-greedy} quantifiers, +which match the same possibilities, but prefer the +smallest number rather than the largest number of matches (see \helpref{Matching}{wxresynmatching})} +\end{twocollist} + +The forms using {\bf \{} and {\bf \}} are known as {\it bound}s. The numbers {\it m} and {\it n} are unsigned +decimal integers with permissible values from 0 to 255 inclusive. +An atom is one of: + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf (re)}}{(where {\it re} is any regular expression) matches a match for + {\it re}, with the match noted for possible reporting} +\twocolitem{{\bf (?:re)}}{as previous, but +does no reporting (a ``non-capturing'' set of parentheses)} +\twocolitem{{\bf ()}}{matches an empty +string, noted for possible reporting} +\twocolitem{{\bf (?:)}}{matches an empty string, without reporting} +\twocolitem{{\bf $[chars]$}}{a {\it bracket expression}, matching any one of the {\it chars} +(see \helpref{Bracket Expressions}{wxresynbracket} for more detail)} +\twocolitem{{\bf .}}{matches any single character } +\twocolitem{{\bf $\backslash$k}}{(where {\it k} is a non-alphanumeric character) +matches that character taken as an ordinary character, e.g. $\backslash\backslash$ matches a backslash +character} +\twocolitem{{\bf $\backslash$c}}{where {\it c} is alphanumeric (possibly followed by other characters), +an {\it escape} (AREs only), see \helpref{Escapes}{wxresynescapes} below} +\twocolitem{{\bf \{}}{when followed by a character +other than a digit, matches the left-brace character `{\bf \{}'; when followed by +a digit, it is the beginning of a {\it bound} (see above)} +\twocolitem{{\bf x}}{where {\it x} is a single +character with no other significance, matches that character.} +\end{twocollist} + +A {\it constraint} +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 later, under \helpref{Escapes}{wxresynescapes}. + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf $^$}}{matches at the beginning of a line} +\twocolitem{{\bf \$}}{matches at the end of a line} +\twocolitem{{\bf (?=re)}}{{\it positive lookahead} +(AREs only), matches at any point where a substring matching {\it re} begins} +\twocolitem{{\bf (?!re)}}{{\it negative lookahead} (AREs only), +matches at any point where no substring matching {\it re} begins} +\end{twocollist} + +The lookahead constraints may not contain back references +(see later), and all parentheses within them are considered non-capturing. + +An RE may not end with `{\bf $\backslash$}'. + + +\subsection{Bracket Expressions}\label{wxresynbracket} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +A {\it bracket expression} is a list +of characters enclosed in `{\bf $[]$}'. It normally matches any single character from +the list (but see below). If the list begins with `{\bf $^$}', it matches any single +character (but see below) {\it not} from the rest of the list. + +If two characters +in the list are separated by `{\bf -}', this is shorthand for the full {\it range} of +characters between those two (inclusive) in the collating sequence, e.g. + {\bf $[0-9]$} in ASCII matches any decimal digit. Two ranges may not share an endpoint, +so e.g. {\bf a-c-e} is illegal. Ranges are very collating-sequence-dependent, and portable +programs should avoid relying on them. + +To include a literal {\bf $]$} or {\bf -} in the +list, the simplest method is to enclose it in {\bf $[.$} and {\bf $.]$} to make it a collating +element (see below). Alternatively, make it the first character (following +a possible `{\bf $^$}'), or (AREs only) precede it with `{\bf $\backslash$}'. +Alternatively, for `{\bf -}', make +it the last character, or the second endpoint of a range. To use a literal + {\bf -} as the first endpoint of a range, make it a collating element or (AREs +only) precede it with `{\bf $\backslash$}'. With the exception of these, some combinations using + {\bf $[$} (see next paragraphs), and escapes, all other special characters lose +their special significance within a bracket expression. + +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 {\bf $[.$} and {\bf $.]$} stands for the +sequence of characters of that collating element. + +{\it wxWindows}: Currently no multi-character collating elements are defined. +So in {\bf $[.X.]$}, {\it X} can either be a single character literal or +the name of a character. For example, the following are both identical + {\bf $[[.0.]-[.9.]]$} and {\bf $[[.zero.]-[.nine.]]$} and mean the same as + {\bf $[0-9]$}. + See \helpref{Character Names}{wxresynchars}. + +%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 {\bf $^$} can match multi-character collating +%elements even if none of them appear in the bracket expression! ({\it Note:} +%Tcl currently has no multi-character collating elements. This information +%is only for illustration.) +% +%For example, assume the collating sequence includes +%a {\bf ch} multi-character collating element. Then the RE {\bf $[[.ch.]]*c$} (zero or more +% {\bf ch}'s followed by {\bf c}) matches the first five characters of `{\bf chchcc}'. Also, the +%RE {\bf $[^c]b$} matches all of `{\bf chb}' (because {\bf $[^c]$} matches the multi-character {\bf ch}). + +Within a bracket expression, a collating element enclosed in {\bf $[=$} and {\bf $=]$} +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 `{\bf $[.$}' and `{\bf $.]$}'.) For example, if {\bf o} +%and {\bf $^$} are the members of an +%equivalence class, then `{\bf $[[$=o=$]]$}', `{\bf $[[$=$^$=$]]$}', +%and `{\bf $[o^]$}' are all synonymous. +An equivalence class may not be an endpoint of a range. + +%({\it Note:} Tcl currently +%implements only the Unicode locale. It doesn't define any equivalence classes. +%The examples above are just illustrations.) + +{\it wxWindows}: Currently no equivalence classes are defined, so +{\bf $[=X=]$} stands for just the single character {\it X}. + {\it X} can either be a single character literal or the name of a character, +see \helpref{Character Names}{wxresynchars}. + +Within a bracket expression, +the name of a {\it character class} enclosed in {\bf $[:$} and {\bf $:]$} stands for the list +of all characters (not all collating elements!) belonging to that class. +Standard character classes are: + +\begin{twocollist}\twocolwidtha{3cm} +\twocolitem{{\bf alpha}}{A letter.} +\twocolitem{{\bf upper}}{An upper-case letter.} +\twocolitem{{\bf lower}}{A lower-case letter.} +\twocolitem{{\bf digit}}{A decimal digit.} +\twocolitem{{\bf xdigit}}{A hexadecimal digit.} +\twocolitem{{\bf alnum}}{An alphanumeric (letter or digit).} +\twocolitem{{\bf print}}{An alphanumeric (same as alnum).} +\twocolitem{{\bf blank}}{A space or tab character.} +\twocolitem{{\bf space}}{A character producing white space in displayed text.} +\twocolitem{{\bf punct}}{A punctuation character.} +\twocolitem{{\bf graph}}{A character with a visible representation.} +\twocolitem{{\bf cntrl}}{A control character.} +\end{twocollist} + +%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. + +{\it wxWindows:} In a non-Unicode build, these character classifications depend on the +current locale, and correspond to the values return by the ANSI C 'is' +functions: isalpha, isupper, etc. In Unicode mode they are based on +Unicode classifications, and are not affected by the current locale. + +There are two special cases of bracket expressions: +the bracket expressions {\bf $[[:$<$:]]$} and {\bf $[[:$>$:]]$} are constraints, matching empty +strings at the beginning and end of a word respectively. A word is defined +as a sequence of word characters that is neither preceded nor followed +by word characters. A word character is an {\it alnum} character or an underscore +({\bf \_}). These special bracket expressions are deprecated; users of AREs should +use constraint escapes instead (see \helpref{Escapes}{wxresynescapes} below). + + +\subsection{Escapes}\label{wxresynescapes} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +Escapes (AREs only), +which begin with a {\bf $\backslash$} followed by an alphanumeric character, come in several +varieties: character entry, class shorthands, constraint escapes, and back +references. A {\bf $\backslash$} followed by an alphanumeric character but not constituting +a valid escape is illegal in AREs. In EREs, there are no escapes: outside +a bracket expression, a {\bf $\backslash$} followed by an alphanumeric character merely stands +for that character as an ordinary character, and inside a bracket expression, + {\bf $\backslash$} is an ordinary character. (The latter is the one actual incompatibility +between EREs and AREs.) + +Character-entry escapes (AREs only) exist to make +it easier to specify non-printing and otherwise inconvenient characters +in REs: + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf $\backslash$a}}{alert (bell) character, as in C} +\twocolitem{{\bf $\backslash$b}}{backspace, as in C} +\twocolitem{{\bf $\backslash$B}}{synonym +for {\bf $\backslash$} to help reduce backslash doubling in some applications where there +are multiple levels of backslash processing} +\twocolitem{{\bf $\backslash$c{\it X}}}{(where X is any character) +the character whose low-order 5 bits are the same as those of {\it X}, and whose +other bits are all zero} +\twocolitem{{\bf $\backslash$e}}{the character whose collating-sequence name is +`{\bf ESC}', or failing that, the character with octal value 033} +\twocolitem{{\bf $\backslash$f}}{formfeed, as in C} +\twocolitem{{\bf $\backslash$n}}{newline, as in C} +\twocolitem{{\bf $\backslash$r}}{carriage return, as in C} +\twocolitem{{\bf $\backslash$t}}{horizontal tab, as in C} +\twocolitem{{\bf $\backslash$u{\it wxyz}}}{(where {\it wxyz} is exactly four hexadecimal digits) +the Unicode +character {\bf U+{\it wxyz}} in the local byte ordering} +\twocolitem{{\bf $\backslash$U{\it stuvwxyz}}}{(where {\it stuvwxyz} is +exactly eight hexadecimal digits) reserved for a somewhat-hypothetical Unicode +extension to 32 bits} +\twocolitem{{\bf $\backslash$v}}{vertical tab, as in C are all available.} +\twocolitem{{\bf $\backslash$x{\it hhh}}}{(where + {\it hhh} is any sequence of hexadecimal digits) the character whose hexadecimal +value is {\bf 0x{\it hhh}} (a single character no matter how many hexadecimal digits +are used).} +\twocolitem{{\bf $\backslash$0}}{the character whose value is {\bf 0}} +\twocolitem{{\bf $\backslash${\it xy}}}{(where {\it xy} is exactly two +octal digits, and is not a {\it back reference} (see below)) the character whose +octal value is {\bf 0{\it xy}}} +\twocolitem{{\bf $\backslash${\it xyz}}}{(where {\it xyz} is exactly three octal digits, and is +not a back reference (see below)) +the character whose octal value is {\bf 0{\it xyz}}} +\end{twocollist} + +Hexadecimal digits are `{\bf 0}'-`{\bf 9}', `{\bf a}'-`{\bf f}', and `{\bf A}'-`{\bf F}'. Octal +digits are `{\bf 0}'-`{\bf 7}'. + +The character-entry +escapes are always taken as ordinary characters. For example, {\bf $\backslash$135} is {\bf ]} in +ASCII, but {\bf $\backslash$135} does not terminate a bracket expression. Beware, however, +that some applications (e.g., C compilers) interpret such sequences themselves +before the regular-expression package gets to see them, which may require +doubling (quadrupling, etc.) the `{\bf $\backslash$}'. + +Class-shorthand escapes (AREs only) provide +shorthands for certain commonly-used character classes: + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf $\backslash$d}}{{\bf $[[:digit:]]$}} +\twocolitem{{\bf $\backslash$s}}{{\bf $[[:space:]]$}} +\twocolitem{{\bf $\backslash$w}}{{\bf $[[:alnum:]\_]$} (note underscore)} +\twocolitem{{\bf $\backslash$D}}{{\bf $[^[:digit:]]$}} +\twocolitem{{\bf $\backslash$S}}{{\bf $[^[:space:]]$}} +\twocolitem{{\bf $\backslash$W}}{{\bf $[^[:alnum:]\_]$} (note underscore)} +\end{twocollist} + +Within bracket expressions, `{\bf $\backslash$d}', `{\bf $\backslash$s}', and +`{\bf $\backslash$w}' lose their outer brackets, and `{\bf $\backslash$D}', +`{\bf $\backslash$S}', and `{\bf $\backslash$W}' are illegal. (So, for example, + {\bf $[$a-c$\backslash$d$]$} is equivalent to {\bf $[a-c[:digit:]]$}. +Also, {\bf $[$a-c$\backslash$D$]$}, which is equivalent to + {\bf $[a-c^[:digit:]]$}, is illegal.) + +A constraint escape (AREs only) is a constraint, +matching the empty string if specific conditions are met, written as an +escape: + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf $\backslash$A}}{matches only at the beginning of the string +(see \helpref{Matching}{wxresynmatching}, below, +for how this differs from `{\bf $^$}')} +\twocolitem{{\bf $\backslash$m}}{matches only at the beginning of a word} +\twocolitem{{\bf $\backslash$M}}{matches only at the end of a word} +\twocolitem{{\bf $\backslash$y}}{matches only at the beginning or end of a word} +\twocolitem{{\bf $\backslash$Y}}{matches only at a point that is not the beginning or end of +a word} +\twocolitem{{\bf $\backslash$Z}}{matches only at the end of the string +(see \helpref{Matching}{wxresynmatching}, below, for +how this differs from `{\bf \$}')} +\twocolitem{{\bf $\backslash${\it m}}}{(where {\it m} is a nonzero digit) a {\it back reference}, +see below} +\twocolitem{{\bf $\backslash${\it mnn}}}{(where {\it m} is a nonzero digit, and {\it nn} is some more digits, +and the decimal value {\it mnn} is not greater than the number of closing capturing +parentheses seen so far) a {\it back reference}, see below} +\end{twocollist} + +A word is defined +as in the specification of {\bf $[[:$<$:]]$} and {\bf $[[:$>$:]]$} above. Constraint escapes are +illegal within bracket expressions. + +A back reference (AREs only) matches +the same string matched by the parenthesized subexpression specified by +the number, so that (e.g.) {\bf ($[bc]$)$\backslash$1} matches {\bf bb} or {\bf cc} but not `{\bf bc}'. +The subexpression +must entirely precede the back reference in the RE. Subexpressions are numbered +in the order of their leading parentheses. Non-capturing parentheses do not +define subexpressions. + +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 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. + + +\subsection{Metasyntax} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +In addition to the main syntax described above, +there are some special forms and miscellaneous syntactic facilities available. + +Normally the flavor of RE being used is specified by application-dependent +means. However, this can be overridden by a {\it director}. If an RE of any flavor +begins with `{\bf ***:}', the rest of the RE is an ARE. If an RE of any flavor begins +with `{\bf ***=}', the rest of the RE is taken to be a literal string, with all +characters considered ordinary characters. + +An ARE may begin with {\it embedded options}: a sequence {\bf (?xyz)} +(where {\it xyz} is one or more alphabetic characters) +specifies options affecting the rest of the RE. These supplement, and can +override, any options specified by the application. The available option +letters are: + +\begin{twocollist}\twocolwidtha{4cm} +\twocolitem{{\bf b}}{rest of RE is a BRE} +\twocolitem{{\bf c}}{case-sensitive matching (usual default)} +\twocolitem{{\bf e}}{rest of RE is an ERE} +\twocolitem{{\bf i}}{case-insensitive matching (see \helpref{Matching}{wxresynmatching}, below)} +\twocolitem{{\bf m}}{historical synonym for {\bf n}} +\twocolitem{{\bf n}}{newline-sensitive matching (see \helpref{Matching}{wxresynmatching}, below)} +\twocolitem{{\bf p}}{partial newline-sensitive matching (see \helpref{Matching}{wxresynmatching}, below)} +\twocolitem{{\bf q}}{rest of RE +is a literal (``quoted'') string, all ordinary characters} +\twocolitem{{\bf s}}{non-newline-sensitive matching (usual default)} +\twocolitem{{\bf t}}{tight syntax (usual default; see below)} +\twocolitem{{\bf w}}{inverse +partial newline-sensitive (``weird'') matching (see \helpref{Matching}{wxresynmatching}, below)} +\twocolitem{{\bf x}}{expanded syntax (see below)} +\end{twocollist} + +Embedded options take effect at the {\bf )} terminating the +sequence. They are available only at the start of an ARE, and may not be +used later within it. + +In addition to the usual ({\it tight}) RE syntax, in which +all characters are significant, there is an {\it expanded} syntax, available +%in all flavors of RE with the {\bf -expanded} switch, or +in AREs with the embedded +x option. In the expanded syntax, white-space characters are ignored and +all characters between a {\bf \#} and the following newline (or the end of the +RE) are ignored, permitting paragraphing and commenting a complex RE. There +are three exceptions to that basic rule: +{\itemize +\item% +a white-space character or `{\bf \#}' preceded +by `{\bf $\backslash$}' is retained +\item% +white space or `{\bf \#}' within a bracket expression is retained +\item% +white space and comments are illegal within multi-character symbols like +the ARE `{\bf (?:}' or the BRE `{\bf $\backslash$(}' +} +Expanded-syntax white-space characters are blank, +tab, newline, and any character that belongs to the {\it space} character class. + +Finally, in an ARE, outside bracket expressions, the sequence `{\bf (?\#ttt)}' (where + {\it ttt} is any text not containing a `{\bf )}') is a comment, completely ignored. Again, +this is not allowed between the characters of multi-character symbols like +`{\bf (?:}'. Such comments are more a historical artifact than a useful facility, +and their use is deprecated; use the expanded syntax instead. + +{\it None} of these +metasyntax extensions is available if the application (or an initial {\bf ***=} +director) has specified that the user's input be treated as a literal string +rather than as an RE. + + +\subsection{Matching}\label{wxresynmatching} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +In the event that an RE could match more than +one substring of a given string, the RE matches the one starting earliest +in the string. If the RE could match more than one substring starting at +that point, its choice is determined by its {\it preference}: either the longest +substring, or the shortest. + +Most atoms, and all constraints, have no preference. +A parenthesized RE has the same preference (possibly none) as the RE. A +quantified atom with quantifier {\bf \{m\}} or {\bf \{m\}?} has the same preference (possibly +none) as the atom itself. A quantified atom with other normal quantifiers +(including {\bf \{m,n\}} with {\it m} equal to {\it n}) prefers longest match. A quantified +atom with other non-greedy quantifiers (including {\bf \{m,n\}?} with {\it m} equal to + {\it n}) prefers shortest match. A branch has the same preference as the first +quantified atom in it which has a preference. An RE consisting of two or +more branches connected by the {\bf $|$} operator prefers longest match. + +Subject +to the constraints imposed by the rules for matching the whole RE, subexpressions +also match the longest or shortest possible substrings, based on their +preferences, with subexpressions starting earlier in the RE taking priority +over ones starting later. Note that outer subexpressions thus take priority +over their component subexpressions. + +Note that the quantifiers {\bf \{1,1\}} and + {\bf \{1,1\}?} can be used to force longest and shortest preference, respectively, +on a subexpression or a whole RE. + +Match lengths are measured in characters, +not collating elements. An empty string is considered longer than no match +at all. For example, {\bf bb*} matches the three middle characters +of `{\bf abbbc}', {\bf (week$|$wee)(night$|$knights)} +matches all ten characters of `{\bf weeknights}', when {\bf (.*).*} is matched against + {\bf abc} the parenthesized subexpression matches all three characters, and when + {\bf (a*)*} is matched against {\bf bc} both the whole RE and the parenthesized subexpression +match an empty string. + +If case-independent matching is specified, the effect +is much as if all case distinctions had vanished from the alphabet. When +an alphabetic that exists in multiple cases appears as an ordinary character +outside a bracket expression, it is effectively transformed into a bracket +expression containing both cases, so that {\bf x} becomes `{\bf $[xX]$}'. When it appears +inside a bracket expression, all case counterparts of it are added to the +bracket expression, so that {\bf $[x]$} becomes {\bf $[xX]$} and {\bf $[^x]$} becomes `{\bf $[^xX]$}'. + +If newline-sensitive +matching is specified, {\bf .} and bracket expressions using {\bf $^$} will never match +the newline character (so that matches will never cross newlines unless +the RE explicitly arranges it) and {\bf $^$} and {\bf \$} will match the empty string after +and before a newline respectively, in addition to matching at beginning +and end of string respectively. ARE {\bf $\backslash$A} and {\bf $\backslash$Z} continue to match beginning +or end of string {\it only}. + +If partial newline-sensitive matching is specified, +this affects {\bf .} and bracket expressions as with newline-sensitive matching, +but not {\bf $^$} and `{\bf \$}'. + +If inverse partial newline-sensitive matching is specified, +this affects {\bf $^$} and {\bf \$} as with newline-sensitive matching, but not {\bf .} and bracket +expressions. This isn't very useful but is provided for symmetry. + + +\subsection{Limits And Compatibility} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +No particular limit is imposed on the length of REs. Programs +intended to be highly portable should not employ REs longer than 256 bytes, +as a POSIX-compliant implementation can refuse to accept such REs. + +The only +feature of AREs that is actually incompatible with POSIX EREs is that {\bf $\backslash$} +does not lose its special significance inside bracket expressions. All other +ARE features use syntax which is illegal or has undefined or unspecified +effects in POSIX EREs; the {\bf ***} syntax of directors likewise is outside +the POSIX syntax for both BREs and EREs. + +Many of the ARE extensions are +borrowed from Perl, but some have been changed to clean them up, and a +few Perl extensions are not present. Incompatibilities of note include `{\bf $\backslash$b}', +`{\bf $\backslash$B}', the lack of special treatment for a trailing newline, the addition of +complemented bracket expressions to the things affected by newline-sensitive +matching, the restrictions on parentheses and back references in lookahead +constraints, and the longest/shortest-match (rather than first-match) matching +semantics. + +The matching rules for REs containing both normal and non-greedy +quantifiers have changed since early beta-test versions of this package. +(The new rules are much simpler and cleaner, but don't work as hard at guessing +the user's real intentions.) + +Henry Spencer's original 1986 {\it regexp} package, still in widespread use, +%(e.g., in pre-8.1 releases of Tcl), +implemented an early version of today's EREs. There are four incompatibilities between {\it regexp}'s +near-EREs (`RREs' for short) and AREs. In roughly increasing order of significance: +{\itemize +\item +In AREs, {\bf $\backslash$} followed by an alphanumeric character is either an escape or +an error, while in RREs, it was just another way of writing the alphanumeric. +This should not be a problem because there was no reason to write such +a sequence in RREs. + +\item% +{\bf \{} followed by a digit in an ARE is the beginning of +a bound, while in RREs, {\bf \{} was always an ordinary character. Such sequences +should be rare, and will often result in an error because following characters +will not look like a valid bound. + +\item% +In AREs, {\bf $\backslash$} remains a special character +within `{\bf $[]$}', so a literal {\bf $\backslash$} within {\bf $[]$} must be +written `{\bf $\backslash\backslash$}'. {\bf $\backslash\backslash$} also gives a literal + {\bf $\backslash$} within {\bf $[]$} in RREs, but only truly paranoid programmers routinely doubled +the backslash. + +\item% +AREs report the longest/shortest match for the RE, rather +than the first found in a specified search order. This may affect some RREs +which were written in the expectation that the first match would be reported. +(The careful crafting of RREs to optimize the search order for fast matching +is obsolete (AREs examine all possible matches in parallel, and their performance +is largely insensitive to their complexity) but cases where the search +order was exploited to deliberately find a match which was {\it not} the longest/shortest +will need rewriting.) +} + + +\subsection{Basic Regular Expressions}\label{wxresynbre} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +BREs differ from EREs in +several respects. `{\bf $|$}', `{\bf +}', and {\bf ?} are ordinary characters and there is no equivalent +for their functionality. The delimiters for bounds +are {\bf $\backslash$\{} and `{\bf $\backslash$\}}', with {\bf \{} and + {\bf \}} by themselves ordinary characters. The parentheses for nested subexpressions +are {\bf $\backslash$(} and `{\bf $\backslash$)}', with {\bf (} and {\bf )} by themselves +ordinary characters. {\bf $^$} is an ordinary +character except at the beginning of the RE or the beginning of a parenthesized +subexpression, {\bf \$} is an ordinary character except at the end of the RE or +the end of a parenthesized subexpression, and {\bf *} is an ordinary character +if it appears at the beginning of the RE or the beginning of a parenthesized +subexpression (after a possible leading `{\bf $^$}'). Finally, single-digit back references +are available, and {\bf $\backslash<$} and {\bf $\backslash>$} are synonyms +for {\bf $[[:<:]]$} and {\bf $[[:>:]]$} respectively; +no other escapes are available. + + +\subsection{Regular Expression Character Names}\label{wxresynchars} + +\helpref{Syntax of the builtin regular expression library}{wxresyn} + +Note that the character names are case sensitive. + +\begin{twocollist} +\twocolitem{NUL}{'$\backslash$0'} +\twocolitem{SOH}{'$\backslash$001'} +\twocolitem{STX}{'$\backslash$002'} +\twocolitem{ETX}{'$\backslash$003'} +\twocolitem{EOT}{'$\backslash$004'} +\twocolitem{ENQ}{'$\backslash$005'} +\twocolitem{ACK}{'$\backslash$006'} +\twocolitem{BEL}{'$\backslash$007'} +\twocolitem{alert}{'$\backslash$007'} +\twocolitem{BS}{'$\backslash$010'} +\twocolitem{backspace}{'$\backslash$b'} +\twocolitem{HT}{'$\backslash$011'} +\twocolitem{tab}{'$\backslash$t'} +\twocolitem{LF}{'$\backslash$012'} +\twocolitem{newline}{'$\backslash$n'} +\twocolitem{VT}{'$\backslash$013'} +\twocolitem{vertical-tab}{'$\backslash$v'} +\twocolitem{FF}{'$\backslash$014'} +\twocolitem{form-feed}{'$\backslash$f'} +\twocolitem{CR}{'$\backslash$015'} +\twocolitem{carriage-return}{'$\backslash$r'} +\twocolitem{SO}{'$\backslash$016'} +\twocolitem{SI}{'$\backslash$017'} +\twocolitem{DLE}{'$\backslash$020'} +\twocolitem{DC1}{'$\backslash$021'} +\twocolitem{DC2}{'$\backslash$022'} +\twocolitem{DC3}{'$\backslash$023'} +\twocolitem{DC4}{'$\backslash$024'} +\twocolitem{NAK}{'$\backslash$025'} +\twocolitem{SYN}{'$\backslash$026'} +\twocolitem{ETB}{'$\backslash$027'} +\twocolitem{CAN}{'$\backslash$030'} +\twocolitem{EM}{'$\backslash$031'} +\twocolitem{SUB}{'$\backslash$032'} +\twocolitem{ESC}{'$\backslash$033'} +\twocolitem{IS4}{'$\backslash$034'} +\twocolitem{FS}{'$\backslash$034'} +\twocolitem{IS3}{'$\backslash$035'} +\twocolitem{GS}{'$\backslash$035'} +\twocolitem{IS2}{'$\backslash$036'} +\twocolitem{RS}{'$\backslash$036'} +\twocolitem{IS1}{'$\backslash$037'} +\twocolitem{US}{'$\backslash$037'} +\twocolitem{space}{' '} +\twocolitem{exclamation-mark}{'!'} +\twocolitem{quotation-mark}{'"'} +\twocolitem{number-sign}{'\#'} +\twocolitem{dollar-sign}{'\$'} +\twocolitem{percent-sign}{'\%'} +\twocolitem{ampersand}{'&'} +\twocolitem{apostrophe}{'$\backslash$''} +\twocolitem{left-parenthesis}{'('} +\twocolitem{right-parenthesis}{')'} +\twocolitem{asterisk}{'*'} +\twocolitem{plus-sign}{'+'} +\twocolitem{comma}{','} +\twocolitem{hyphen}{'-'} +\twocolitem{hyphen-minus}{'-'} +\twocolitem{period}{'.'} +\twocolitem{full-stop}{'.'} +\twocolitem{slash}{'/'} +\twocolitem{solidus}{'/'} +\twocolitem{zero}{'0'} +\twocolitem{one}{'1'} +\twocolitem{two}{'2'} +\twocolitem{three}{'3'} +\twocolitem{four}{'4'} +\twocolitem{five}{'5'} +\twocolitem{six}{'6'} +\twocolitem{seven}{'7'} +\twocolitem{eight}{'8'} +\twocolitem{nine}{'9'} +\twocolitem{colon}{':'} +\twocolitem{semicolon}{';'} +\twocolitem{less-than-sign}{'<'} +\twocolitem{equals-sign}{'='} +\twocolitem{greater-than-sign}{'>'} +\twocolitem{question-mark}{'?'} +\twocolitem{commercial-at}{'@'} +\twocolitem{left-square-bracket}{'$[$'} +\twocolitem{backslash}{'$\backslash$'} +\twocolitem{reverse-solidus}{'$\backslash$'} +\twocolitem{right-square-bracket}{'$]$'} +\twocolitem{circumflex}{'$^$'} +\twocolitem{circumflex-accent}{'$^$'} +\twocolitem{underscore}{'\_'} +\twocolitem{low-line}{'\_'} +\twocolitem{grave-accent}{'`'} +\twocolitem{left-brace}{'\{'} +\twocolitem{left-curly-bracket}{'\{'} +\twocolitem{vertical-line}{'\|'} +\twocolitem{right-brace}{'\}'} +\twocolitem{right-curly-bracket}{'\}'} +\twocolitem{tilde}{'$~$'} +\twocolitem{DEL}{'$\backslash$177'} +\end{twocollist} diff --git a/docs/latex/wx/regex.tex b/docs/latex/wx/regex.tex index 025d01e411..89542cff7c 100644 --- a/docs/latex/wx/regex.tex +++ b/docs/latex/wx/regex.tex @@ -11,14 +11,29 @@ \section{\class{wxRegEx}}\label{wxregex} -wxRegEx represents a regular expression. The regular expressions syntax -supported is the POSIX one. Both basic and extended regular expressions are -supported but, unlike POSIX C API, the extended ones are used by default. - -This class provides support for regular expressions matching and also -replacement. It is built on top of either the system library (if it has support -for POSIX regular expressions - which is the case of the most modern Unices) or -uses a version of Henry Spencer's library from tcl. +wxRegEx represents a regular expression. This class provides support +for regular expressions matching and also replacement. + +It is built on top of either the system library (if it has support +for POSIX regular expressions - which is the case of the most modern +Unices) or uses the built in Henry Spencer's library. Henry Spencer +would appreciate being given credit in the documentation of software +which uses his library, but that is not a requirement. + +Regular expressions, as defined by POSIX, come in two flavours: {\it extended} +and {\it basic}. The builtin library also adds a third flavour +of expression \helpref{advanced}{wxresyn}, which is not available +when using the system library. + +Unicode is fully supported only when using the builtin library. +When using the system library in Unicode mode, the expressions and data +are translated to the default 8-bit encoding before being passed to +the library. + +On platforms where a system library is available, the default is to use +the builtin library for Unicode builds, and the system library otherwise. +It is possible to use the other if preferred by selecting it when building +the wxWindows. \wxheading{Derived from} @@ -31,8 +46,13 @@ Flags for regex compilation to be used with \helpref{Compile()}{wxregexcompile}: \begin{verbatim} enum { - // use extended regex syntax (default) + // use extended regex syntax wxRE_EXTENDED = 0, + + // use advanced RE syntax (built-in regex only) +#ifdef wxHAS_REGEX_ADVANCED + wxRE_ADVANCED = 1, +#endif // use basic RE syntax wxRE_BASIC = 2, diff --git a/docs/latex/wx/topics.tex b/docs/latex/wx/topics.tex index bae331270e..89eca18461 100644 --- a/docs/latex/wx/topics.tex +++ b/docs/latex/wx/topics.tex @@ -58,4 +58,4 @@ This chapter contains a selection of topic overviews, first things first: \input wxhtml.tex \input tenvvars.tex \input wxPython.tex - +\input re_syntax.tex diff --git a/setup.h.in b/setup.h.in index fb78a521b1..8c7a2988ae 100644 --- a/setup.h.in +++ b/setup.h.in @@ -182,6 +182,12 @@ * Use regex support */ #define wxUSE_REGEX 0 +/* + * The built-in regex supports advanced REs in additional to POSIX's basic + * and extended. Your system regex probably won't support this, and in this + * case WX_NO_REGEX_ADVANCED should be defined. + */ +#undef WX_NO_REGEX_ADVANCED /* * Use XML support */ diff --git a/setup.h_vms b/setup.h_vms index e533df83e8..30d52a5731 100644 --- a/setup.h_vms +++ b/setup.h_vms @@ -191,6 +191,12 @@ * Use regex support */ #define wxUSE_REGEX 0 +/* + * The built-in regex supports advanced REs in additional to POSIX's basic + * and extended. Your system regex probably won't support this, and in this + * case WX_NO_REGEX_ADVANCED should be defined. + */ +#undef WX_NO_REGEX_ADVANCED /* * Use XML support */