+@b x
+
+expanded syntax (see below)
+
+
+
+Embedded options take effect at the @b ) 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 (@e tight) RE syntax, in which
+all characters are significant, there is an @e expanded syntax, available
+in AREs with the embedded
+x option. In the expanded syntax, white-space characters are ignored and
+all characters between a @b # 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:
+
+
+a white-space character or '@b #' preceded
+by '@b \' is retained
+white space or '@b #' within a bracket expression is retained
+white space and comments are illegal within multi-character symbols like
+the ARE '@b (?:' or the BRE '@b \('
+
+
+Expanded-syntax white-space characters are blank,
+tab, newline, and any character that belongs to the @e space character class.
+Finally, in an ARE, outside bracket expressions, the sequence '@b (?#ttt)' (where
+@e ttt is any text not containing a '@b )') is a comment, completely ignored. Again,
+this is not allowed between the characters of multi-character symbols like
+'@b (?:'. Such comments are more a historical artifact than a useful facility,
+and their use is deprecated; use the expanded syntax instead.
+@e None of these
+metasyntax extensions is available if the application (or an initial @b ***=
+director) has specified that the user's input be treated as a literal string
+rather than as an RE.
+
+
+@section overview_resyntax_matching Matching
+
+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 @e 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 @b {m} or @b {m}? has the same preference (possibly
+none) as the atom itself. A quantified atom with other normal quantifiers
+(including @b {m,n} with @e m equal to @e n) prefers longest match. A quantified
+atom with other non-greedy quantifiers (including @b {m,n}? with @e m equal to
+@e 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 @b | 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 @b {1,1} and
+@b {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, @b bb* matches the three middle characters
+of '@b abbbc', @b (week|wee)(night|knights)
+matches all ten characters of '@b weeknights', when @b (.*).* is matched against
+@b abc the parenthesized subexpression matches all three characters, and when
+@b (a*)* is matched against @b 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 @b x becomes '@b [xX]'. When it appears
+inside a bracket expression, all case counterparts of it are added to the
+bracket expression, so that @b [x] becomes @b [xX] and @b [^x] becomes '@b [^xX]'.
+If newline-sensitive
+matching is specified, @b . and bracket expressions using @b ^ will never match
+the newline character (so that matches will never cross newlines unless
+the RE explicitly arranges it) and @b ^ and @b $ will match the empty string after
+and before a newline respectively, in addition to matching at beginning
+and end of string respectively. ARE @b \A and @b \Z continue to match beginning
+or end of string @e only.
+If partial newline-sensitive matching is specified,
+this affects @b . and bracket expressions as with newline-sensitive matching,
+but not @b ^ and '@b $'.
+If inverse partial newline-sensitive matching is specified,
+this affects @b ^ and @b $ as with newline-sensitive matching, but not @b . and bracket
+expressions. This isn't very useful but is provided for symmetry.
+
+
+@section overview_resyntax_limits Limits and Compatibility
+
+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 @b \
+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 @b *** 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 '@b \b',
+'@b \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 @e regexp package, still in widespread use,
+implemented an early version of today's EREs. There are four incompatibilities between @e regexp's
+near-EREs ('RREs' for short) and AREs. In roughly increasing order of significance:
projects / wxWidgets.git / commitdiff
