java.lang.Object
- com.norconex.commons.lang.text.Regex

All Implemented Interfaces:

IXMLConfigurable
```
public class Regex
extends Object
implements IXMLConfigurable
```
Builder and utility methods making it easier to construct and use regular expressions. In addition, you can obtain a Matcher with support for empty or null values

Empty and null values

Since 3.0.0, you can force null and empty strings to be considered a positive match, regardless of the specified pattern. To do so, set matchEmpty to true. To have blank values (containing white spaces only) considered as positive matches, also set trim to true. When matching empties, doing replacement on a null value behaves as if the value is an empty string.

XML configuration usage:
```
ignoreCase="[false|true]"
     ignoreDiacritic="[false|true]"
     dotAll="[false|true]"
     unixLines="[false|true]"
     literal="[false|true]"
     comments="[false|true]"
     multiline="[false|true]"
     canonEq="[false|true]"
     unicodeCase="[false|true]"
     unicodeCharacterClass="[false|true]"
     trim="[false|true]"
     matchEmpty="[false|true]"
```
The above are configurable attributes consuming classes can expect. The actual regular expression is expected to be the tag content. Many of the available attributes on XML configuration represent the regular expression flags as defined in Pattern.

XML usage example:
```
<sampleConfig
    ignoreCase="true"
    dotAll="true">
  ^start.*end$
</sampleConfig>
```
The above will match any text that starts with "start" and ends with "ends", regardless if there are new line characters in between.
Since:

2.0.0

Author:

Pascal Essiembre

See Also:

Pattern

Field Summary

Fields
Modifier and Type	Field	Description
`static int`	`UNICODE_CASE_INSENSTIVE_FLAG`	Convenience flag that combines `Pattern.UNICODE_CASE` and `Pattern.CASE_INSENSITIVE`
`static int`	`UNICODE_MARK_INSENSTIVE_FLAG`	Flag that ignores diacritical marks when matching or replacing (e.g.

Constructor Summary

Constructors
Constructor Description

Regex()

Regex(String pattern)

Regex(String pattern, int... flags)

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`protected boolean`	`canEqual(Object other)`
`Regex`	`canonEq()`
`Regex`	`comments()`
`Pattern`	`compile()`	Compiles a previously set pattern.
`Pattern`	`compile(String pattern)`	Compiles the given pattern without assigning it to this object.
`static Pattern`	`compileDotAll(String regex, boolean ignoreCase)`	Compiles a "dotall" pattern (dots match all, including new lines) with optional case sensitivity.
`RegexFieldValueExtractor`	`createKeyValueExtractor()`
`RegexFieldValueExtractor`	`createKeyValueExtractor(int keyGroup, int valueGroup)`
`RegexFieldValueExtractor`	`createKeyValueExtractor(String key)`
`RegexFieldValueExtractor`	`createKeyValueExtractor(String key, int valueGroup)`
`Regex`	`dotAll()`
`boolean`	`equals(Object o)`
`static String`	`escape(String pattern)`	Escape special characters with a backslash (\) in a regular expression.
`Set<Integer>`	`getFlags()`
`String`	`getPattern()`
`int`	`hashCode()`
`Regex`	`ignoreCase()`
`Regex`	`ignoreDiacritic()`	Ignores diacritical marks when matching or replacing (e.g.
`boolean`	`isCanonEq()`
`boolean`	`isComments()`
`boolean`	`isDotAll()`
`boolean`	`isIgnoreCase()`
`boolean`	`isIgnoreDiacritic()`
`boolean`	`isLiteral()`
`boolean`	`isMatchEmpty()`	Gets whether `null` or empty strings should be considered a positive match.
`boolean`	`isMultiline()`
`boolean`	`isTrim()`	Gets whether values should be trimmed before being evaluated (as per `String.trim()`).
`boolean`	`isUnicodeCase()`
`boolean`	`isUnicodeCharacterClass()`
`boolean`	`isUnixLines()`
`Regex`	`literal()`
`void`	`loadFromXML(XML xml)`	Load XML configuration values and initialized this object with them.
`Regex`	`matchEmpty()`	Sets that `null` or empty strings should be considered a positive match.
`Matcher`	`matcher(CharSequence text)`	Matches the previously set pattern against the given text.
`Matcher`	`matcher(String pattern, CharSequence text)`	Matches the the given pattern against the given text without assigning the pattern to this object.
`Regex`	`multiline()`
`void`	`saveToXML(XML xml)`	Saves this object as XML.
`Regex`	`setCanonEq(boolean canonEq)`
`Regex`	`setComments(boolean comments)`
`Regex`	`setDotAll(boolean dotAll)`
`Regex`	`setFlags(int... flags)`
`Regex`	`setIgnoreCase(boolean ignoreCase)`
`Regex`	`setIgnoreDiacritic(boolean ignoreDiacritic)`
`Regex`	`setLiteral(boolean literal)`
`Regex`	`setMatchEmpty(boolean matchEmpty)`	Sets whether `null` or empty strings should be considered a positive match.
`Regex`	`setMultiline(boolean multiline)`
`Regex`	`setPattern(String pattern)`
`Regex`	`setTrim(boolean trim)`	Sets whether values should be trimmed before being evaluated (as per `String.trim()`).
`Regex`	`setUnicodeCase(boolean unicode)`
`Regex`	`setUnicodeCharacterClass(boolean unicode)`
`Regex`	`setUnixLines(boolean unixLines)`
`String`	`toString()`
`Regex`	`trim()`	Sets that values should be trimmed before being evaluated (as per `String.trim()`).
`Regex`	`unicodeCase()`
`Regex`	`unicodeCharacterClass()`
`Regex`	`unixLines()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - UNICODE_MARK_INSENSTIVE_FLAG
```
public static final int UNICODE_MARK_INSENSTIVE_FLAG
```
    Flag that ignores diacritical marks when matching or replacing (e.g. accents). This flag is not supported by Java Pattern and only works when used with this class.
    
    See Also:
    
    Constant Field Values
  - UNICODE_CASE_INSENSTIVE_FLAG
```
public static final int UNICODE_CASE_INSENSTIVE_FLAG
```
    Convenience flag that combines Pattern.UNICODE_CASE and Pattern.CASE_INSENSITIVE
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Regex
```
public Regex()
```
  - Regex
```
public Regex(String pattern)
```
  - Regex
```
public Regex(String pattern,
             int... flags)
```
- Method Detail
  - dotAll
```
public Regex dotAll()
```
  - setDotAll
```
public Regex setDotAll(boolean dotAll)
```
  - isDotAll
```
public boolean isDotAll()
```
  - ignoreCase
```
public Regex ignoreCase()
```
  - setIgnoreCase
```
public Regex setIgnoreCase(boolean ignoreCase)
```
  - isIgnoreCase
```
public boolean isIgnoreCase()
```
  - unixLines
```
public Regex unixLines()
```
  - setUnixLines
```
public Regex setUnixLines(boolean unixLines)
```
  - isUnixLines
```
public boolean isUnixLines()
```
  - literal
```
public Regex literal()
```
  - setLiteral
```
public Regex setLiteral(boolean literal)
```
  - isLiteral
```
public boolean isLiteral()
```
  - comments
```
public Regex comments()
```
  - setComments
```
public Regex setComments(boolean comments)
```
  - isComments
```
public boolean isComments()
```
  - multiline
```
public Regex multiline()
```
  - setMultiline
```
public Regex setMultiline(boolean multiline)
```
  - isMultiline
```
public boolean isMultiline()
```
  - canonEq
```
public Regex canonEq()
```
  - setCanonEq
```
public Regex setCanonEq(boolean canonEq)
```
  - isCanonEq
```
public boolean isCanonEq()
```
  - unicodeCase
```
public Regex unicodeCase()
```
  - setUnicodeCase
```
public Regex setUnicodeCase(boolean unicode)
```
  - isUnicodeCase
```
public boolean isUnicodeCase()
```
  - unicodeCharacterClass
```
public Regex unicodeCharacterClass()
```
  - setUnicodeCharacterClass
```
public Regex setUnicodeCharacterClass(boolean unicode)
```
  - isUnicodeCharacterClass
```
public boolean isUnicodeCharacterClass()
```
  - ignoreDiacritic
```
public Regex ignoreDiacritic()
```
    Ignores diacritical marks when matching or replacing (e.g. accents).
    
    Returns:
    
    this instance
  - setIgnoreDiacritic
```
public Regex setIgnoreDiacritic(boolean ignoreDiacritic)
```
  - isIgnoreDiacritic
```
public boolean isIgnoreDiacritic()
```
  - isMatchEmpty
```
public boolean isMatchEmpty()
```
    Gets whether null or empty strings should be considered a positive match.
    
    Returns:
    
    true if null and empty strings are considered a match
    
    Since:
    
    3.0.0
  - setMatchEmpty
```
public Regex setMatchEmpty(boolean matchEmpty)
```
    Sets whether null or empty strings should be considered a positive match. To also consider blank values as positive matches, use setTrim(boolean).
    
    Parameters:
    
    matchEmpty - true to have null and empty strings are considered a match.
    
    Returns:
    
    this instance
    
    Since:
    
    3.0.0
  - matchEmpty
```
public Regex matchEmpty()
```
    Sets that null or empty strings should be considered a positive match. Same as invoking setMatchEmpty(boolean) with true.
    
    Returns:
    
    this instance
    
    Since:
    
    3.0.0
  - isTrim
```
public boolean isTrim()
```
    Gets whether values should be trimmed before being evaluated (as per String.trim()).
    
    Returns:
    
    true if values are trimmed before evaluation
    
    Since:
    
    3.0.0
  - setTrim
```
public Regex setTrim(boolean trim)
```
    Sets whether values should be trimmed before being evaluated (as per String.trim()).
    
    Parameters:
    
    trim - true to trim values before evaluation
    
    Returns:
    
    this instance
    
    Since:
    
    3.0.0
  - trim
```
public Regex trim()
```
    Sets that values should be trimmed before being evaluated (as per String.trim()). Same as invoking setTrim(boolean) with true.
    
    Returns:
    
    this instance
    
    Since:
    
    3.0.0
  - setFlags
```
public Regex setFlags(int... flags)
```
  - getFlags
```
public Set<Integer> getFlags()
```
  - setPattern
```
public Regex setPattern(String pattern)
```
  - getPattern
```
public String getPattern()
```
  - compile
```
public Pattern compile()
```
    Compiles a previously set pattern.
    
    For text-matching with diacritical mark insensitivity support enabled, or for trim and matchEmpty support, use matcher(CharSequence) instead.
    
    Returns:
    
    compiled pattern
  - compile
```
public Pattern compile(String pattern)
```
    Compiles the given pattern without assigning it to this object.
    
    For text-matching with diacritical mark insensitivity support enabled, or for trim and matchEmpty support, use matcher(String, CharSequence) instead.
    
    Parameters:
    
    pattern - the pattern to compile
    
    Returns:
    
    compiled pattern
    
    Throws:
    
    IllegalArgumentException - if pattern is null
  - compileDotAll
```
public static Pattern compileDotAll(String regex,
                                    boolean ignoreCase)
```
    Compiles a "dotall" pattern (dots match all, including new lines) with optional case sensitivity.
    
    Parameters:
    
    regex - regular expression
    
    ignoreCase - true to ignore character case.
    
    Returns:
    
    compiled pattern
  - escape
```
public static String escape(String pattern)
```
    Escape special characters with a backslash (\) in a regular expression. This is an alternative to Pattern.quote(String) for when you do not want the string to be treated as a literal.
    
    Parameters:
    
    pattern - the pattern to escape
    
    Returns:
    
    escaped pattern
  - matcher
```
public Matcher matcher(CharSequence text)
```
    Matches the previously set pattern against the given text.
    
    Parameters:
    
    text - the text to match
    
    Returns:
    
    matcher
  - matcher
```
public Matcher matcher(String pattern,
                       CharSequence text)
```
    Matches the the given pattern against the given text without assigning the pattern to this object. Since 3.0.0, null or empty text will generate no match unless isMatchEmpty() is true, in which case it will match positively.
    
    Parameters:
    
    pattern - the pattern to match
    
    text - the text to match
    
    Returns:
    
    matcher
  - createKeyValueExtractor
```
public RegexFieldValueExtractor createKeyValueExtractor()
```
  - createKeyValueExtractor
```
public RegexFieldValueExtractor createKeyValueExtractor(String key)
```
  - createKeyValueExtractor
```
public RegexFieldValueExtractor createKeyValueExtractor(String key,
                                                        int valueGroup)
```
  - createKeyValueExtractor
```
public RegexFieldValueExtractor createKeyValueExtractor(int keyGroup,
                                                        int valueGroup)
```
  - loadFromXML
```
public void loadFromXML(XML xml)
```
    Description copied from interface: IXMLConfigurable
    
    Load XML configuration values and initialized this object with them.
    
    Specified by:
    
    loadFromXML in interface IXMLConfigurable
    
    Parameters:
    
    xml - the XML to load into this object
  - saveToXML
```
public void saveToXML(XML xml)
```
    Description copied from interface: IXMLConfigurable
    
    Saves this object as XML.
    
    Specified by:
    
    saveToXML in interface IXMLConfigurable
    
    Parameters:
    
    xml - the XML that will representing this object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - canEqual
```
protected boolean canEqual(Object other)
```
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object

Constructor	Description
`Regex()`
`Regex(String pattern)`
`Regex(String pattern, int... flags)`

Class Regex

Empty and null values

XML configuration usage:

XML usage example:

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNICODE_MARK_INSENSTIVE_FLAG

UNICODE_CASE_INSENSTIVE_FLAG

Constructor Detail

Regex

Regex

Regex

Method Detail

dotAll

setDotAll

isDotAll

ignoreCase

setIgnoreCase

isIgnoreCase

unixLines

setUnixLines

isUnixLines

literal

setLiteral

isLiteral

comments

setComments

isComments

multiline

setMultiline

isMultiline

canonEq

setCanonEq

isCanonEq

unicodeCase

setUnicodeCase

isUnicodeCase

unicodeCharacterClass

setUnicodeCharacterClass

isUnicodeCharacterClass

ignoreDiacritic

setIgnoreDiacritic

isIgnoreDiacritic

isMatchEmpty

setMatchEmpty

matchEmpty

isTrim

setTrim

trim

setFlags

getFlags

setPattern

getPattern

compile

compile

compileDotAll

escape

matcher

matcher

createKeyValueExtractor

createKeyValueExtractor

createKeyValueExtractor

createKeyValueExtractor

loadFromXML

saveToXML

toString

equals

canEqual

hashCode

Empty and `null` values