<?xml version="1.0" encoding="UTF-8"?>
<appendix id="regexps">
    <title>Regular Expressions</title>
    <!-- jEdit buffer-local properties: -->
    <!-- :indentSize=2:noTabs=yes: -->
    <!-- :xml.root=users-guide.xml: -->

    <para>jEdit uses regular expressions from <ulink
    url="http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html">java.util.regex.Pattern</ulink>
    to implement inexact search and replace. Click there to see a complete
    reference guide to all supported meta-characters.</para>

    <para>A regular expression consists of a string where some characters are
    given special meaning with regard to pattern matching.</para>

    <note>
        <title>Inside XML files</title>

        <para>Inside XML files (such as jEdit mode files), it is important that
        you escape XML special characters, such as &amp;, &lt;, &gt;, etc. You
        can use the XML plugin's "characters to entities" to perform this
        mapping.</para>
    </note>

    <note>
        <title>Inside Java / beanshell / properties files</title>

        <para>Java strings are always parsed by java before they are processed
        by the regular expression engine, so you must make sure that backslashes
        are escaped by an extra backslash (<literal>\\</literal>)</para>
    </note>

    <para>Within a regular expression, the following characters have special
    meaning:</para>

    <bridgehead>Positional Operators</bridgehead>

    <itemizedlist>
        <listitem>
            <para><literal>^</literal> matches at the beginning of a line</para>
        </listitem>

        <listitem>
            <para><literal>$</literal> matches at the end of a line</para>
        </listitem>

        <listitem>
            <para><literal>\B</literal> matches at a non-word break</para>
        </listitem>

        <listitem>
            <para><literal>\b</literal> matches at a word boundary</para>
        </listitem>
    </itemizedlist>

    <bridgehead>One-Character Operators</bridgehead>

    <itemizedlist>
        <listitem>
            <para><literal>.</literal> matches any single character</para>
        </listitem>

        <listitem>
            <para><literal>\d</literal> matches any decimal digit</para>
        </listitem>

        <listitem>
            <para><literal>\D</literal> matches any non-digit</para>
        </listitem>

        <listitem>
            <para><literal>\n</literal> matches the newline character</para>
        </listitem>

        <listitem>
            <para><literal>\s</literal> matches any whitespace character</para>
        </listitem>

        <listitem>
            <para><literal>\xNN</literal> matches hexadecimal character code <literal>NN</literal></para>
        </listitem>


        <listitem>
            <para><literal>\S</literal> matches any non-whitespace
            character</para>
        </listitem>

        <listitem>
            <para><literal>\t</literal> matches a horizontal tab
            character</para>
        </listitem>

        <listitem>
            <para><literal>\w</literal> matches any word (alphanumeric)
            character</para>
        </listitem>

        <listitem>
            <para><literal>\W</literal> matches any non-word (alphanumeric)
            character</para>
        </listitem>

        <listitem>
            <para><literal>\\</literal> matches the backslash (<quote>\</quote>)
            character</para>
        </listitem>
    </itemizedlist>

    <bridgehead>Character Class Operator</bridgehead>

    <itemizedlist>
        <listitem>
            <para><literal>[<replaceable>abc</replaceable>]</literal> matches
            any character in the set <replaceable>a</replaceable>,
            <replaceable>b</replaceable> or <replaceable>c</replaceable></para>
        </listitem>

        <listitem>
            <para><literal>[^<replaceable>abc</replaceable>]</literal> matches
            any character not in the set <replaceable>a</replaceable>,
            <replaceable>b</replaceable> or <replaceable>c</replaceable></para>
        </listitem>

        <listitem>
            <para><literal>[<replaceable>a-z</replaceable>]</literal> matches
            any character in the range <replaceable>a</replaceable> to
            <replaceable>z</replaceable>, inclusive. A leading or trailing dash
            will be interpreted literally</para>
        </listitem>
    </itemizedlist>

    <bridgehead>Subexpressions and Backreferences</bridgehead>

    <itemizedlist>
        <listitem>
            <para><literal>(<replaceable>abc</replaceable>)</literal> matches
            whatever the expression <replaceable>abc</replaceable> would match,
            and saves it as a subexpression. Also used for grouping</para>
        </listitem>

        <listitem>
            <para><literal>(?:<replaceable>...</replaceable>)</literal> pure
            grouping operator, does not save contents</para>
        </listitem>

        <listitem>
            <para><literal>(?#<replaceable>...</replaceable>)</literal> embedded
            comment, ignored by engine</para>
        </listitem>

        <listitem>
            <para><literal>(?=<replaceable>...</replaceable>)</literal> positive
            lookahead; the regular expression will match if the text in the
            brackets matches, but that text will not be considered part of the
            match</para>
        </listitem>

        <listitem>
            <para><literal>(?!<replaceable>...</replaceable>)</literal> negative
            lookahead; the regular expression will match if the text in the
            brackets does not match, and that text will not be considered part
            of the match</para>
        </listitem>

        <listitem>
            <para><literal>\<replaceable>n</replaceable></literal> where 0 &lt;
            <replaceable>n</replaceable> &lt; 10, matches the same thing the
            <replaceable>n</replaceable>th subexpression matched. Can only be
            used in the search string</para>
        </listitem>

        <listitem>
            <para><literal>$<replaceable>n</replaceable></literal> where 0 &lt;
            <replaceable>n</replaceable> &lt; 10, substituted with the text
            matched by the <replaceable>n</replaceable>th subexpression. Can
            only be used in the replacement string</para>
        </listitem>
    </itemizedlist>

    <bridgehead>Branching (Alternation) Operator</bridgehead>

    <itemizedlist>
        <listitem>
            <para><literal><replaceable>a</replaceable>|<replaceable>b</replaceable></literal>
            matches whatever the expression <replaceable>a</replaceable> would
            match, or whatever the expression <replaceable>b</replaceable> would
            match.</para>
        </listitem>
    </itemizedlist>

    <bridgehead>Repeating Operators</bridgehead>

    <para>These symbols operate on the previous atomic expression.</para>

    <itemizedlist>
        <listitem>
            <para><literal>?</literal> matches the preceding expression or the
            null string</para>
        </listitem>

        <listitem>
            <para><literal>*</literal> matches the null string or any number of
            repetitions of the preceding expression</para>
        </listitem>

        <listitem>
            <para><literal>+</literal> matches one or more repetitions of the
            preceding expression</para>
        </listitem>

        <listitem>
            <para><literal>{<replaceable>m</replaceable>}</literal> matches
            exactly <replaceable>m</replaceable> repetitions of the
            one-character expression</para>
        </listitem>

        <listitem>
            <para><literal>{<replaceable>m</replaceable>,<replaceable>n</replaceable>}</literal>
            matches between <replaceable>m</replaceable> and
            <replaceable>n</replaceable> repetitions of the preceding
            expression, inclusive</para>
        </listitem>

        <listitem>
            <para><literal>{<replaceable>m</replaceable>,}</literal> matches
            <replaceable>m</replaceable> or more repetitions of the preceding
            expression</para>
        </listitem>
    </itemizedlist>

    <bridgehead>Stingy (Minimal) Matching</bridgehead>

    <para>If a repeating operator (above) is immediately followed by a
    <literal>?</literal>, the repeating operator will stop at the smallest
    number of repetitions that can complete the rest of the match.</para>
     <note>
                <title>On regex search</title>

                <para>There are some known issues with the
                <literal>java.util.regex</literal> library, as it stands in
                Java. In particular, it is possible to create
                regular expressions that hang the JVM, or cause stack overflow
                errors, which was not as easy to accomplish using the legacy
                <literal>gnu.regexp</literal> library. If you find that
                <literal>gnu.regexp</literal>, used in jEdit 4.2 and earlier, is
                more suitable for your search/replace needs, you can try the
                <emphasis role="bold">XSearch plugin</emphasis>, which still
                uses it and can provide a replacement to the built-in search
                dialog.</para>
            </note>

</appendix>