added wxTopLevelWindow::RequestUserAttention(); documented it and implemented it...

[wxWidgets.git] / docs / latex / wx / re_syntax.tex

diff --git a/docs/latex/wx/re_syntax.tex b/docs/latex/wx/re_syntax.tex
index 677dad856f6551d115c962804282d2ed35581fb9..4732c9a3173be8992c2dff881b2830644079444c 100644 (file)
--- a/docs/latex/wx/re_syntax.tex
+++ b/docs/latex/wx/re_syntax.tex
@@ -10,7 +10,6 @@ pattern that matches certain strings and doesn't match others.
 
 \helpref{wxRegEx}{wxregex}
 
 
 \helpref{wxRegEx}{wxregex}
 

- 

 \subsection{Different Flavors of REs}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}
 \subsection{Different Flavors of REs}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -22,11 +21,10 @@ of the traditional {\it egrep}, while BREs are roughly those of the traditional
 EREs with some significant extensions. 
 
 This manual page primarily describes
 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.
+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}
 \subsection{Regular Expression Syntax}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -36,16 +34,14 @@ 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. 
 
 (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
+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. 
 
 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,
+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:
 
 it matches a match for the atom. The quantifiers, and what a so-quantified
 atom matches, are:
 


@@ -89,13 +85,12 @@ a digit, it is the beginning of a {\it bound} (see above)}
 character with no other significance, matches that character.}
 \end{twocollist}
 
 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
+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}
 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 \caret}}{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 \$}}{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}


@@ -108,14 +103,13 @@ The lookahead constraints may not contain back references
 
 An RE may not end with `{\bf $\backslash$}'.
 
 
 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
 \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
+the list (but see below). If the list begins with `{\bf \caret}', it matches any single

 character (but see below) {\it not} from the rest of the list. 
 
 If two characters
 character (but see below) {\it not} from the rest of the list. 
 
 If two characters


@@ -128,7 +122,7 @@ 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
 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$}'.
+a possible `{\bf \caret}'), 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
 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


@@ -142,7 +136,7 @@ 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.
 
 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.
+{\it wxWidgets}: 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
 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


@@ -152,7 +146,7 @@ the name of a character. For example, the following are both identical
 %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),
 %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
+%a bracket expression that starts with {\bf \caret} 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.) 
 %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.) 


@@ -168,8 +162,8 @@ 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}
 %(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 \caret} are the members of an
+%equivalence class, then `{\bf $[[$=o=$]]$}', `{\bf $[[$=\caret=$]]$}',

 %and `{\bf $[o^]$}' are all synonymous.
 An equivalence class may not be an endpoint of a range.
 
 %and `{\bf $[o^]$}' are all synonymous.
 An equivalence class may not be an endpoint of a range.
 


@@ -177,7 +171,7 @@ An equivalence class may not be an endpoint of a range.
 %implements only the Unicode locale. It doesn't define any equivalence classes.
 %The examples above are just illustrations.) 
 
 %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 
+{\it wxWidgets}: 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}.
 {\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}.


@@ -206,7 +200,7 @@ Standard character classes are:
 %implementation  has  only one locale: the Unicode locale.)
 A character class may not be used as an endpoint of a range. 
 
 %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
+{\it wxWidgets}: 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.
 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.


@@ -219,7 +213,6 @@ by word characters. A word character is an {\it alnum} character or an underscor
 ({\bf \_}). These special bracket expressions are deprecated; users of AREs should
 use constraint escapes instead (see \helpref{Escapes}{wxresynescapes} below). 
 
 ({\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}
 \subsection{Escapes}\label{wxresynescapes}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -309,7 +302,7 @@ escape:
 \begin{twocollist}\twocolwidtha{4cm}
 \twocolitem{{\bf $\backslash$A}}{matches only at the beginning of the string
 (see \helpref{Matching}{wxresynmatching}, below,
 \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 $^$}')}
+for how this differs from `{\bf \caret}')}

 \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$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}


@@ -346,7 +339,6 @@ 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. 
 
 (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}
 \subsection{Metasyntax}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -419,7 +411,6 @@ 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. 
 
 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}
 \subsection{Matching}\label{wxresynmatching}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -440,8 +431,7 @@ atom with other non-greedy quantifiers (including {\bf \{m,n\}?} with {\it m} eq
 quantified atom in it which has a preference. An RE consisting of two or
 more branches connected by the {\bf $|$} operator prefers longest match. 
 
 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
+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
 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


@@ -469,22 +459,21 @@ 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
 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
+matching is specified, {\bf .} and bracket expressions using {\bf \caret} will never match

 the newline character (so that matches will never cross newlines unless
 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
+the RE explicitly arranges it) and {\bf \caret} 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,
 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 \$}'. 
+but not {\bf \caret} and `{\bf \$}'. 

 
 If inverse partial newline-sensitive matching is specified,
 
 If inverse partial newline-sensitive matching is specified,

-this affects {\bf $^$} and {\bf \$} as with newline-sensitive matching, but not {\bf .} and bracket
+this affects {\bf \caret} and {\bf \$} as with newline-sensitive matching, but not {\bf .} and bracket

 expressions. This isn't very useful but is provided for symmetry. 
 
 expressions. This isn't very useful but is provided for symmetry. 
 

-

 \subsection{Limits And Compatibility}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}
 \subsection{Limits And Compatibility}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -519,27 +508,23 @@ Henry Spencer's original 1986 {\it regexp} package, still in widespread use,
 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
 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
+\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. 
 
 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
+\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. 
 
 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
+\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. 
 
 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
+\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
 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


@@ -549,7 +534,6 @@ order was exploited to deliberately  find a match which was {\it not} the longes
 will need rewriting.)  
 }
 
 will need rewriting.)  
 }
 

-

 \subsection{Basic Regular Expressions}\label{wxresynbre}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}
 \subsection{Basic Regular Expressions}\label{wxresynbre}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -560,17 +544,16 @@ 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
 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
+ordinary characters. {\bf \caret} 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
 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
+subexpression (after a possible leading `{\bf \caret}'). 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.  
 
 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}
 \subsection{Regular Expression Character Names}\label{wxresynchars}
 
 \helpref{Syntax of the builtin regular expression library}{wxresyn}


@@ -627,7 +610,7 @@ Note that the character names are case sensitive.
 \twocolitem{number-sign}{'\#'}
 \twocolitem{dollar-sign}{'\$'}
 \twocolitem{percent-sign}{'\%'}
 \twocolitem{number-sign}{'\#'}
 \twocolitem{dollar-sign}{'\$'}
 \twocolitem{percent-sign}{'\%'}

-\twocolitem{ampersand}{'&'}
+\twocolitem{ampersand}{'\&'}

 \twocolitem{apostrophe}{'$\backslash$''}
 \twocolitem{left-parenthesis}{'('}
 \twocolitem{right-parenthesis}{')'}
 \twocolitem{apostrophe}{'$\backslash$''}
 \twocolitem{left-parenthesis}{'('}
 \twocolitem{right-parenthesis}{')'}


@@ -661,16 +644,17 @@ Note that the character names are case sensitive.
 \twocolitem{backslash}{'$\backslash$'}
 \twocolitem{reverse-solidus}{'$\backslash$'}
 \twocolitem{right-square-bracket}{'$]$'}
 \twocolitem{backslash}{'$\backslash$'}
 \twocolitem{reverse-solidus}{'$\backslash$'}
 \twocolitem{right-square-bracket}{'$]$'}

-\twocolitem{circumflex}{'$^$'}
-\twocolitem{circumflex-accent}{'$^$'}
+\twocolitem{circumflex}{'\caret'}
+\twocolitem{circumflex-accent}{'\caret'}

 \twocolitem{underscore}{'\_'}
 \twocolitem{low-line}{'\_'}
 \twocolitem{grave-accent}{'`'}
 \twocolitem{left-brace}{'\{'}
 \twocolitem{left-curly-bracket}{'\{'}
 \twocolitem{underscore}{'\_'}
 \twocolitem{low-line}{'\_'}
 \twocolitem{grave-accent}{'`'}
 \twocolitem{left-brace}{'\{'}
 \twocolitem{left-curly-bracket}{'\{'}

-\twocolitem{vertical-line}{'\|'}
+\twocolitem{vertical-line}{'$|$'}

 \twocolitem{right-brace}{'\}'}
 \twocolitem{right-curly-bracket}{'\}'}
 \twocolitem{right-brace}{'\}'}
 \twocolitem{right-curly-bracket}{'\}'}

-\twocolitem{tilde}{'$~$'}
+\twocolitem{tilde}{'\destruct{}'}

 \twocolitem{DEL}{'$\backslash$177'}
 \end{twocollist}
 \twocolitem{DEL}{'$\backslash$177'}
 \end{twocollist}

+