/******************************************************************************
 CBRegexHelpText.cc

	Copyright © 1997-98 by John Lindal. All rights reserved.

 ******************************************************************************/

#include "JXRegexHelpText.h"

const JCharacter* kRegexHelpName  = "JXRegexHelp";
const JCharacter* kRegexHelpTitle = "Regex searching";

const JCharacter* kRegexHelpText =

"<html>"
"<h3> Regex searching </h3>"

"When you check the \"Regex search (egrep)\" checkbox in the Search Text window, "
"you turn on the full power of Extended Regular Expressions.  "
"Most strings that you enter will work just as before, matching exactly what you typed "
"in, but some characters attain special meaning, as described below."
"<p>"
"To guarantee that a non-alphabetic character does not have a special meaning, "
"precede it with a backslash (\\).  This also works for backslash itself, "
"so \\\\ matches a single backslash."

"<dl>"
"<dt> <b> Matching characters </b>"
"<p>"
"<dt> <tt>.</tt> (period)"
"<dd> Matches any single character."
"<dd> <tt>a.c</tt> can match <tt>abc</tt> or <tt>axc</tt> but not <tt>axyc</tt>."

"<p>"
"<dt> <tt>[ ]</tt> (square brackets)"
"<dd> This defines a \"character class\" and matches any single character out of the "
"     characters listed between the brackets (e.g. <tt>[abc]</tt> can match any one of "
"     <tt>a</tt>, <tt>b</tt>, or <tt>c</tt>), with the exception of the following:"
  "<p>"
  "<dl>"
  "<dt> <tt>-</tt> (dash)"
  "<dd> The most common use of character classes is to specify ranges of characters "
  "     <em>in the ASCII table</em> by using a dash, as in <tt>[0-9]</tt>, which can "
  "     match any character between 0 and 9.  Note that, since it is based on the ASCII table, "
  "     <tt>[A-z]</tt> will match A through Z, [, \\, ], ^, _, `, and a through z.  To "
  "     match any alphabetic character, regardless of case, use <tt>[A-Za-z]</tt> or "
  "     turn on the \"Ignore case\" checkbox in the Search window."
  "<p>"
  "<dd> To include a dash as a regular character to be matched, place it first "
  "     (but after any leading caret), last, or as the <em>second</em> endpoint of "
  "     a range.  (<tt>[.-.]</tt> allows a dash to be the first character in a range.)"
  "<p>"
  "<dt> <tt>^</tt> (caret)"
  "<dd> This is only special when it is the first character after the open bracket.  "
  "     It then means \"match any single character <em>other</em> than what follows.\" "
  "     As an example, <tt>[^abc]</tt> can match <tt>d</tt>.  "
  "     Note that, since it is based on the ASCII table, <tt>[^0-9]</tt> will match any "
  "     ASCII character other than 0 through 9, including newlines and weird binary noise!"
  "<p>"
  "<dt> Character classes cannot be nested, so <tt>[</tt> is not a special character."
  "<p>"
  "<dt> Since <tt>]</tt> normally ends the list, it must be listed first (but after any "
  "     leading caret) in order to include it as a regular character."
  "</dl>"

"<p>"
"<dt> <b>Whitespace characters</b> (usable inside character classes)"
"<p>"

"<dt> <tt>\\t</tt>"
"<dd> Matches a horizontal tab character."
"<dt> <tt>\\n</tt>"
"<dd> Matches a newline character."
"<dt> <tt>\\r</tt>"
"<dd> Matches a carriage return character, which cannot be typed in the Code Crusader text editor."
"<dt> <tt>\\f</tt>"
"<dd> Matches a form feed character, which cannot be typed in the Code Crusader text editor."
"<dt> <tt>\\v</tt>"
"<dd> Matches a vertical tab character, which cannot be typed in the Code Crusader text editor."

"<p>"
"<dt> <b>Perl extensions</b> (<em>not</em> usable inside character classes)"
"<p>"

"<dt> <tt>\\w</tt>"
"<dd> Matches any single character that can legally be used in a variable name in the C "
"     programming language.  Equivalent to <tt>[a-zA-Z0-9_]</tt>."
"<dt> <tt>\\W</tt>"
"<dd> The opposite of <tt>\\w</tt>.  Equivalent to <tt>[^a-zA-Z0-9_]</tt>."

"<p>"
"<dt> <tt>\\s</tt>"
"<dd> Matches a single whitespace character.  Equivalent to <tt>[ \\t\\n\\r\\f\\v]</tt>.  "
"     (Note the space at the front.)"
"<dt> <tt>\\S</tt>"
"<dd> The opposite of <tt>\\s</tt>.  Equivalent to <tt>[^ \\t\\n\\r\\f\\v]</tt>.  "
"     (Note the space at the front.)"

"<p>"
"<dt> <tt>\\d</tt>"
"<dd> Matches a single decimal digit.  Equivalent to <tt>[0-9]</tt>."
"<dt> <tt>\\D</tt>"
"<dd> The opposite of <tt>\\d</tt>. Matches any single character other than a decimal "
"     digit.  Equivalent to <tt>[^0-9]</tt>."

"<p>"
"<dt> <b> Suffixes that specify the number of matches </b>"
"<p>"
"These suffixes are called \"quantifiers\" and act on the sub-expression "
"that they follow."
"<p>"
"<dt> <tt>?</tt> (question mark)"
"<dd> Matches zero on one occurrence."
"<dd> <tt>ab?</tt> can match both <tt>a</tt> and <tt>ab</tt>"
"<p>"
"<dt> <tt>*</tt> (asterisk)"
"<dd> Matches zero on more occurrences."
"<dd> <tt>ab*</tt> can match <tt>a</tt>, <tt>ab</tt>, <tt>abb</tt>, <tt>abbb</tt>, etc."
"<p>"
"<dt> <tt>+</tt> (plus)"
"<dd> Matches one on more occurrences."
"<dd> <tt>ab+</tt> can match <tt>ab</tt>, <tt>abb</tt>, <tt>abbb</tt>, etc."
"<p>"
"<dt> <tt>{min,max}</tt>"
"<dd> Matches at least <tt>min</tt> occurrences and at most <tt>max</tt> occurrences."
"<dd> <tt>ab{2,4}</tt> can match <tt>abb</tt>, <tt>abbb</tt>, and <tt>abbbb</tt>"
"<p>"
"<dt> <tt>{n}</tt>"
"<dd> Matches exactly <tt>n</tt> occurrences."
"<p>"
"<dt> <tt>{min,}</tt>"
"<dd> Matches at least <tt>min</tt> occurrences."
"<p>"
"<dt> Note:  A single open brace (<tt>{</tt>) that is <em>not</em> part of one "
"            of the above expressions is treated as an ordinary character."

"<p>"
"<dt> <b> Combining expressions </b> (logical or)"
"<p>"
"<dt> <tt>|</tt> (vertical bar)"
"<dd> Either one expression or the other"
"<dd> <tt>a[xy]|b[xy]</tt> can match <tt>ax</tt>, <tt>ay</tt>, <tt>bx</tt>, and <tt>by</tt>"

"<p>"
"<dt> <b> Grouping </b> (parentheses)"
"<p>"
"<dt> Parentheses define a subexpression.  They act as grouping symbols, so that "
"     quantifiers and the vertical bar act on the complete expression rather than on "
"     a single character or character class."
"<dd> <tt>(ab){1,2}</tt> can match <tt>ab</tt> and <tt>abab</tt>, while "
"     <tt>ab{1,2}</tt> can match <tt>ab</tt> and <tt>abb</tt>."
"<p>"
"<dt> Parentheses also \"capture\" what they match so that it can later be used in "
"     a replace string (see Regex Replacement, below)."
"<dd> <tt>([ab])([cd])</tt> matches exactly the same strings that <tt>[ab][cd]</tt>, "
"     except that what each character class matched can be extracted individually "
"     and used in the replace pattern."

"<p>"
"<dt> <b> Matching special positions </b> (anchors)"
"<p>"
"<dt> <tt>^</tt> (caret)"
"<dd> Forces the following expression to match only at the beginning of a line."
"<dd> <tt>^a</tt> can match the <tt>a</tt> at the beginning of a line"
"<p>"
"<dt> <tt>$</tt> (dollar sign)"
"<dd> Forces the preceding expression to match only at the end of a line."
"<dd> <tt>a$</tt> can match the <tt>a</tt> at the end of a line"

"<p>"
"<dt> <tt>\\&lt</tt>"
"<dd> Forces the following expression to match only at the beginning of a word, "
"     between a character matching <tt>\\W</tt> and a character matching <tt>\\w</tt>."
"<dd> <tt>\\&lta</tt> can match the <tt>a</tt> in <tt>bad <u>a</u>rt</tt>."
"<p>"
"<dt> <tt>\\&gt</tt>"
"<dd> Forces the preceding expression to match only at the end of a word, between "
"     a character matching <tt>\\w</tt> and a character matching <tt>\\W</tt>."
"<dd> <tt>d\\&gt</tt> can match the <tt>d</tt> in <tt>ba<u>d</u> art</tt>."
"<p>"
"<dt> Note: These tags do not yet work properly."
"</dl>"

"<p>"
"<b> Special expressions </b>"
"<p>"

"There are several \"shorthands\" that can be used inside character classes:"

"<pre>"
"[:alnum:]    [A-Za-z0-9]\n"
"[:alpha:]    [A-Za-z]\n"
"[:blank:]    space or tab\n"
"[:cntrl:]    any control character\n"
"[:digit:]    [0-9] or \\d\n"
"[:graph:]    any printable character except space\n"
"[:lower:]    [a-z]\n"
"[:print:]    any printable character including space\n"
"[:punct:]    any printable character except [ A-Za-z0-9]\n"
"[:space:]    space, tab, newline, carriage return, form feed, vertical tab\n"
"[:upper:]    [A-Z]\n"
"[:xdigit:]   any hexadecimal digit: [0-9A-Fa-f]\n"
"</pre>"

"As an example, <tt>[^abc[:digit:]]</tt> can match any character other than "
"a, b, c, and 0 through 9."

"<p>"
"<font size=-1>"
"Paraphrased from <cite>Mastering Regular Expressions</cite>, by Jeffrey Friedl, "
"O'Reilly, 1997"
"</font>"

"<h3> Regex replacement </h3>"

"When you check the \"Regex replace\" checkbox in the Search Text window, "
"you get more flexibility for specifying how to perform replacement after a "
"successful search.  The syntax is much simpler than for searching.  Every character "
"other than backslash (\\) acts the same as before."

"<p>"
"When a backslash is followed by one of the following characters, it is translated "
"just like in the search pattern:"

"<p>"
"<tt>t</tt> -> horizontal tab <br>"
"<tt>n</tt> -> newline <br>"
"<tt>r</tt> -> carriage return (which is removed by the Code Crusader text editor) <br>"
"<tt>f</tt> -> form feed (which is removed by the Code Crusader text editor) <br>"
"<tt>v</tt> -> vertical tab (which is removed by the Code Crusader text editor)"

"<p>"
"When a backslash is followed by "
"a positive integer N, this is converted into the string that the Nth "
"pair of parentheses in the search string matched.  \\0 represents the entire match, "
"even if it was not enclosed in parentheses.  To get a single backslash in the result, "
"use a double backslash (\\\\).  As an example:"
"<blockquote>"
"<dl>"
"<dt> <tt>ab(c[ef])gh</tt>"
"<dd> This can match <tt>abcegh</tt> and <tt>abcfgh</tt>."
"<p>"
"<dt> <tt>wx\\1yz</tt>"
"<dd> This converts the above matches as follows:"
"<p>"
"		<tt>abcegh</tt> -> <tt>wxceyz</tt>"
"<br>"
"		<tt>abcfgh</tt> -> <tt>wxcfyz</tt>"
"</dl>"
"</blockquote>"
"For the hackers out there, you can also use negative integers after a backslash.  "
"\\-1 is converted into the string that the <em>last</em> pair of parentheses in the search "
"string matched, \\-2 is converted into the string that the next to last pair of parentheses "
"in the search string matched, etc. This can be useful if you want to count from the end "
"of the string.  Complicated regex's with nested parentheses can make you want to do this!"

"<h3> For the experts... </h3>"

"The best book on the subject is:"

"<blockquote>"
"<cite>Mastering Regular Expressions</cite>, by Jeffrey Friedl, O'Reilly, 1997."
"</blockquote>"

"In Friedl's terminology, Code Crusader uses a POSIX DFA engine and an egrep-like "
"expression flavor, based on Henry Spencer's DFA regex package.  The man page "
"(<tt>regex.7</tt>) is included in the Code Crusader distribution as the final "
"authority on how regex behaves.  (If your system already has a regex man page "
"installed, be sure that it describes Spencer's regex package and not the GNU "
"NFA regex package.)"

"<p>"
"<b> Backreferences </b>"
"<p>"

"Backreferences are not support because Spencer's extended regular expression "
"package does not yet provide them.  We eagerly await their arrival!"

"<p>"
"<b> Matching ambiguities </b> (the longest of the leftmost)"
"<p>"

"It is easy to write a regular expression that can match a given string "
"in many ways at many positions.  The rule that avoids such ambiguities is that "
"the match that starts closest to the beginning of the string wins.  If more "
"than one match is possible at this position, the longest possible match wins."

"<p>"
"<b> Operator precedence </b>"
"<p>"

"When more than one operator can apply to a subexpression, they are applied "
"in the following order of precedence:"

"<pre>"
"    (highest precedence, applied first)\n"
"\n"
"    () [] ^ $ \\\n"
"    * + ? {,}\n"
"    catenation\n"
"    |\n"
"\n"
"    (lowest precedence, applied last)\n"
"</pre>"

"As an example, <tt>a|b*</tt> is equivalent to <tt>(a)|(b*)</tt> and matches a "
"single <tt>a</tt> or any number of <tt>b</tt>'s rather than being equivalent to "
"<tt>(a|b)*</tt> and matching any number of consecutive <tt>a</tt>'s and <tt>b</tt>'s."

"</html>"
;
