util

## Class RE

- java.lang.Object
- - util.RE

-     public class RE
      extends java.lang.Object

  Utility data and method definitions for regular expression processing.

  NB Testing of this module is still somewhat PARTIAL.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RE.AV` A structure that records the result of a scan for an attribute='value' string.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `BOOL` RE for a boolean value tag `true` or `false`.
    `static java.lang.String` | `DQ_BODY` RE for the body of a double-quoted string, i.e.
    `static java.lang.String` | `DQ_STRING` RE for a double-quoted string (with no enclosed double quotes).
    `static java.lang.String` | `EQ` RE for `=` sign with optional space around it.
    `static java.lang.String` | `NAME` RE for a name, i.e.
    `static java.lang.String` | `NON_NEG_INT` RE for a non-negative intger.
    `static java.lang.String` | `NON_SPACE` RE for a non-empty sequence of non-whitespace characters.
    `static java.lang.String` | `NON_SPACE_OPT` RE for an optional sequence of non-whitespace characters.
    `static java.lang.String` | `NON_TABSP` RE for a non-empty sequence of non-tab, non-space characters.
    `static java.lang.String` | `NON_TABSP_OPT` RE for an optional sequence of non-tab, non-space characters.
    `static java.lang.String` | `ONE_NON_SPACE` RE for a single non-whitespace character.
    `static java.lang.String` | `ONE_NON_TABSP` RE for a single non-tab and non-space character.
    `static java.lang.String` | `ONE_SPACE` RE for a single whitespace character.
    `static java.lang.String` | `ONE_TABSP` RE for a single tab or space character.
    `static java.lang.String` | `SPACE` RE for a non-empty sequence of whitespace characters.
    `static java.lang.String` | `SPACE_OPT` RE for an optional sequence of whitespace characters.
    `static java.lang.String` | `SQ_BODY` RE for the body of a single-quoted string, i.e.
    `static java.lang.String` | `SQ_STRING` RE for a single-quoted string (with no enclosed single quotes).
    `static java.lang.String` | `STRING` RE for a single- or double- quoted string.
    `static java.lang.String` | `TABSP` RE for a non-empty sequence of tab and space characters.
    `static java.lang.String` | `TABSP_OPT` RE for an optional sequence of tab and space characters.
    `static java.lang.String` | `WORD` RE for a (natural language) word, i.e.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RE()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `boolResult(RE.AV av)` Returns the boolean value defined by the given `RE.AV` structure, or `false` if the given AV reference is null.
    `static boolean` | `boolResult(RE.AV av, boolean bdefault)` Returns the boolean value defined by the given `RE.AV` structure, or the given default value if the given AV reference is null.
    `static java.lang.String` | `dquote(java.lang.String re)` Returns the given RE wrapped in double quotes.
    `static java.lang.String` | `extract(java.lang.String re, java.lang.String text)` Searches the given text for the first substring that matches the given RE, and returns the first tagged group within that substring, or returns `null` if this is not possible..
    `static java.lang.String` | `extractHead(java.lang.String re, java.lang.String text)` If the given text has a prefix matching the given RE, then this method returns that prefix, or returns `null` otherwise.
    `static java.lang.String` | `extractTail(java.lang.String re, java.lang.String text)` If the given text has a prefix matching the given RE, then this method returns the complementary suffix, i.e.
    `static RE.AV` | `findAVq(java.lang.String avtext, java.lang.String are, java.lang.String qvre)` Scans the given text for an attribute='value' string characterized by the given attribute name and quoted value REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static RE.AV` | `getAV(java.lang.String avtext, java.lang.String are, java.lang.String vre)` Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name and unquoted value REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static RE.AV` | `getAVBool(java.lang.String avtext, java.lang.String are)` Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name RE and a boolean value, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static RE.AV` | `getAVInt(java.lang.String avtext, java.lang.String are)` Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name and a non-negative integer value, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static RE.AV` | `getAVq(java.lang.String avtext, java.lang.String are, java.lang.String qvre)` Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name and quoted value REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static RE.AV` | `getNameAV(java.lang.String avtext)` Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the standard `NAME` and `STRING` REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static RE.AV` | `getWordAV(java.lang.String avtext)` Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the standard `WORD` and `STRING` REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.
    `static int` | `intResult(RE.AV av)` Returns the non-negative integer value defined by the given `RE.AV` structure, or `-1` if the given AV reference is null.
    `static java.util.regex.Matcher` | `matcher(java.lang.String re, java.lang.String text)` Returns a new matcher for the given RE against the given text.
    `static java.lang.String` | `notChr(java.lang.String ch)` Returns a RE for any character other than the given one.
    `static java.lang.String` | `num(int width)` Returns the RE for a decimal digit string of the specified witdth.
    `static java.lang.String` | `opt(java.lang.String re)` Applies the `?` postfix operator to the given RE.
    `static java.lang.String` | `opttag(java.lang.String re)` Forms a tagged group for the given RE, and then applies the `?` postfix operator to it.
    `static java.lang.String` | `or(java.lang.String re0, java.lang.String re1)` Returns the RE for the union (`|`) of the two given REs.
    `static java.lang.String` | `quote(java.lang.String re)` Returns a RE for the given RE after it is wrapped in single or double quotes.
    `static java.lang.String` | `quote(java.lang.String sre, java.lang.String dre)` Wraps the first of the given REs in single quotes and the second in double quotes, and returns the RE for the union of this pair.
    `static java.lang.String` | `reAV(java.lang.String are)` Returns an attribute='value' RE for the given attribute name RE and a standard `STRING` value RE, tagging both of these in the result.
    `static java.lang.String` | `reAV(java.lang.String are, java.lang.String vre)` Returns an attribute='value' RE for the given attribute name and unquoted value REs, tagging both attribute and quoted value REs in the result.
    `static java.lang.String` | `reAV(java.lang.String are, java.lang.String svre, java.lang.String dvre)` Returns an attribute='value' RE for the given attribute name RE, and unquoted single- and double- quotable value REs tagging both attribute and quoted value REs in the result.
    `static java.lang.String` | `reTaggedAVq(java.lang.String are, java.lang.String qvre)` Returns an attribute='value' RE for the given attribute name and quoted value REs, tagging both of these in the result.
    `static java.lang.String` | `seq(java.lang.String re)` Applies the `*` postfix operator to the given RE.
    `static java.lang.String` | `seqNE(java.lang.String re)` Applies the `+` postfix operator to the given RE.
    `static java.lang.String` | `seqNEtag(java.lang.String re)` Forms a tagged group for the given RE, and then applies the `+` postfix operator to it.
    `static java.lang.String` | `seqtag(java.lang.String re)` Forms a tagged group for the given RE, and then applies the `*` postfix operator to it.
    `static java.lang.String` | `squote(java.lang.String re)` Returns the given RE wrapped in single quotes.
    `static java.lang.String` | `tag(java.lang.String re)` Returns a tagged group for the given RE, i.e.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ONE_SPACE

          public static final java.lang.String ONE_SPACE

      RE for a single whitespace character.
      See Also:
        Constant Field Values

    - #### ONE_NON_SPACE

          public static final java.lang.String ONE_NON_SPACE

      RE for a single non-whitespace character.
      See Also:
        Constant Field Values

    - #### SPACE_OPT

          public static final java.lang.String SPACE_OPT

      RE for an optional sequence of whitespace characters.

    - #### NON_SPACE_OPT

          public static final java.lang.String NON_SPACE_OPT

      RE for an optional sequence of non-whitespace characters.

    - #### SPACE

          public static final java.lang.String SPACE

      RE for a non-empty sequence of whitespace characters.

    - #### NON_SPACE

          public static final java.lang.String NON_SPACE

      RE for a non-empty sequence of non-whitespace characters.

    - #### ONE_TABSP

          public static final java.lang.String ONE_TABSP

      RE for a single tab or space character.
      See Also:
        Constant Field Values

    - #### ONE_NON_TABSP

          public static final java.lang.String ONE_NON_TABSP

      RE for a single non-tab and non-space character.
      See Also:
        Constant Field Values

    - #### TABSP_OPT

          public static final java.lang.String TABSP_OPT

      RE for an optional sequence of tab and space characters.

    - #### NON_TABSP_OPT

          public static final java.lang.String NON_TABSP_OPT

      RE for an optional sequence of non-tab, non-space characters.

    - #### TABSP

          public static final java.lang.String TABSP

      RE for a non-empty sequence of tab and space characters.

    - #### NON_TABSP

          public static final java.lang.String NON_TABSP

      RE for a non-empty sequence of non-tab, non-space characters.

    - #### WORD

          public static final java.lang.String WORD

      RE for a (natural language) word, i.e. a non-empty sequence of letters and digits.

    - #### NAME

          public static final java.lang.String NAME

      RE for a name, i.e. a non-empty sequence of `\w` characters.

    - #### NON_NEG_INT

          public static final java.lang.String NON_NEG_INT

      RE for a non-negative intger.

    - #### SQ_BODY

          public static final java.lang.String SQ_BODY

      RE for the body of a single-quoted string, i.e. for a sequence of non-single-quote characters.

    - #### DQ_BODY

          public static final java.lang.String DQ_BODY

      RE for the body of a double-quoted string, i.e. for a sequence of non-double-quote characters.

    - #### SQ_STRING

          public static final java.lang.String SQ_STRING

      RE for a single-quoted string (with no enclosed single quotes).

    - #### DQ_STRING

          public static final java.lang.String DQ_STRING

      RE for a double-quoted string (with no enclosed double quotes).

    - #### STRING

          public static final java.lang.String STRING

      RE for a single- or double- quoted string.

    - #### EQ

          public static final java.lang.String EQ

      RE for `=` sign with optional space around it.

    - #### BOOL

          public static final java.lang.String BOOL

      RE for a boolean value tag `true` or `false`.

  - ### Constructor Detail

    - #### RE

          public RE()

  - ### Method Detail

    - #### notChr

          public static final java.lang.String notChr(java.lang.String ch)

      Returns a RE for any character other than the given one.

    - #### tag

          public static final java.lang.String tag(java.lang.String re)

      Returns a tagged group for the given RE, i.e. wraps it in parentheses.

    - #### opt

          public static final java.lang.String opt(java.lang.String re)

      Applies the `?` postfix operator to the given RE.

    - #### seq

          public static final java.lang.String seq(java.lang.String re)

      Applies the `*` postfix operator to the given RE.

    - #### seqNE

          public static final java.lang.String seqNE(java.lang.String re)

      Applies the `+` postfix operator to the given RE.

    - #### opttag

          public static final java.lang.String opttag(java.lang.String re)

      Forms a tagged group for the given RE, and then applies the `?` postfix operator to it.

    - #### seqtag

          public static final java.lang.String seqtag(java.lang.String re)

      Forms a tagged group for the given RE, and then applies the `*` postfix operator to it.

    - #### seqNEtag

          public static final java.lang.String seqNEtag(java.lang.String re)

      Forms a tagged group for the given RE, and then applies the `+` postfix operator to it.

    - #### or

          public static final java.lang.String or(java.lang.String re0,
                                                  java.lang.String re1)

      Returns the RE for the union (`|`) of the two given REs.

    - #### num

          public static final java.lang.String num(int width)

      Returns the RE for a decimal digit string of the specified witdth.

    - #### squote

          public static final java.lang.String squote(java.lang.String re)

      Returns the given RE wrapped in single quotes.

    - #### dquote

          public static final java.lang.String dquote(java.lang.String re)

      Returns the given RE wrapped in double quotes.

    - #### quote

          public static final java.lang.String quote(java.lang.String re)

      Returns a RE for the given RE after it is wrapped in single or double quotes.

    - #### quote

          public static final java.lang.String quote(java.lang.String sre,
                                                     java.lang.String dre)

      Wraps the first of the given REs in single quotes and the second in double quotes, and returns the RE for the union of this pair.

    - #### matcher

          public static final java.util.regex.Matcher matcher(java.lang.String re,
                                                              java.lang.String text)

      Returns a new matcher for the given RE against the given text.

    - #### extract

          public static final java.lang.String extract(java.lang.String re,
                                                       java.lang.String text)

      Searches the given text for the first substring that matches the given RE, and returns the first tagged group within that substring, or returns `null` if this is not possible..

    - #### extractHead

          public static final java.lang.String extractHead(java.lang.String re,
                                                           java.lang.String text)

      If the given text has a prefix matching the given RE, then this method returns that prefix, or returns `null` otherwise.

    - #### extractTail

          public static final java.lang.String extractTail(java.lang.String re,
                                                           java.lang.String text)

      If the given text has a prefix matching the given RE, then this method returns the complementary suffix, i.e. the result of stripping the matching prefix from the text, or returns `null` otherwise.

    - #### reAV

          public static final java.lang.String reAV(java.lang.String are)

      Returns an attribute='value' RE for the given attribute name RE and a standard `STRING` value RE, tagging both of these in the result.

    - #### reAV

          public static final java.lang.String reAV(java.lang.String are,
                                                    java.lang.String vre)

      Returns an attribute='value' RE for the given attribute name and unquoted value REs, tagging both attribute and quoted value REs in the result.

    - #### reAV

          public static final java.lang.String reAV(java.lang.String are,
                                                    java.lang.String svre,
                                                    java.lang.String dvre)

      Returns an attribute='value' RE for the given attribute name RE, and unquoted single- and double- quotable value REs tagging both attribute and quoted value REs in the result.

    - #### reTaggedAVq

          public static final java.lang.String reTaggedAVq(java.lang.String are,
                                                           java.lang.String qvre)

      Returns an attribute='value' RE for the given attribute name and quoted value REs, tagging both of these in the result.

    - #### findAVq

          public static RE.AV findAVq(java.lang.String avtext,
                                      java.lang.String are,
                                      java.lang.String qvre)

      Scans the given text for an attribute='value' string characterized by the given attribute name and quoted value REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### getAVq

          public static RE.AV getAVq(java.lang.String avtext,
                                     java.lang.String are,
                                     java.lang.String qvre)

      Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name and quoted value REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### getAV

          public static RE.AV getAV(java.lang.String avtext,
                                    java.lang.String are,
                                    java.lang.String vre)

      Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name and unquoted value REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### getWordAV

          public static RE.AV getWordAV(java.lang.String avtext)

      Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the standard `WORD` and `STRING` REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### getNameAV

          public static RE.AV getNameAV(java.lang.String avtext)

      Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the standard `NAME` and `STRING` REs, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### getAVBool

          public static RE.AV getAVBool(java.lang.String avtext,
                                        java.lang.String are)

      Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name RE and a boolean value, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### boolResult

          public static boolean boolResult(RE.AV av,
                                           boolean bdefault)

      Returns the boolean value defined by the given `RE.AV` structure, or the given default value if the given AV reference is null.

    - #### boolResult

          public static boolean boolResult(RE.AV av)

      Returns the boolean value defined by the given `RE.AV` structure, or `false` if the given AV reference is null.

    - #### getAVInt

          public static RE.AV getAVInt(java.lang.String avtext,
                                       java.lang.String are)

      Attempts to parse the given text (in its entirety) as an attribute='value' string characterized by the given attribute name and a non-negative integer value, returning an appropriate `RE.AV` pair if successful, or `null` otherwise.

    - #### intResult

          public static int intResult(RE.AV av)

      Returns the non-negative integer value defined by the given `RE.AV` structure, or `-1` if the given AV reference is null.