de.unkrig.commons.text.pattern
Class Glob

java.lang.Object
  de.unkrig.commons.text.pattern.Glob

All Implemented Interfaces:

Predicate<java.lang.String>

Direct Known Subclasses:

IncludeExclude

public abstract class Glob
extends java.lang.Object
implements Predicate<java.lang.String>

This class extends the concepts of the JDK java.util.regex.Pattern and de.unkrig.commons.util.pattern.Pattern2 classes as follows:

• Pattern defines the both the interface of pattern matching and its implementation (regular expressions). This makes it impossible to have different pattern matchers with the same interface. Glob is that new interface, and Glob.compile() compiles a regular expression into a Glob, just like Pattern2.compile() compiles it into a Pattern.
• Glob replaces the powerful (yet huge) API of java.util.regex with a simple one: matches(String) and replace(String). Pattern finding (as opposed to matching) and repeated substitution are no longer supported. However, this approach is much more generic than (highly regex-specific) concepts of "groups", "anchors", "lookaheads" and "lookbehinds".
• The new REPLACEMENT compilation flag modifies the pattern compilation such that a "replacement string" can be defined in the pattern, which is often convenient.
• The new INCLUDES_EXCLUDES compilation flag modifies the pattern compilation such that a pattern can be composed from a sequence of patterns, which are combined logically.

See Also:

compile(String), compile(String, int), compileRegex(Pattern), compileRegex(Pattern, String)

Field Summary

static Glob	ANY A Glob that matches any string (and thus replaces it with itself).
static int	INCLUDES_EXCLUDES Modifies the pattern compilation as follows: ',' and '~' are now metacharacters, i.e. to include them literally in the pattern, they must be escaped with a backslash.
static Glob	NONE A Glob that matches no string.
static int	REPLACEMENT Modifies the pattern compilation as follows: '=' is now a metacharacter, i.e. to include it literally in the pattern, it must be escaped with a backslash.

Constructor Summary

Glob()

Method Summary

static Glob	and(Glob pattern1, Glob pattern2) The matches(String) method of the returned Glob returns whether its subject argument matches both pattern1 and pattern2.
static Glob	and(Glob pattern, Predicate<java.lang.String> predicate) The matches(String) method of the returned Glob returns whether the subject argument matches the pattern and the predicate evaluates to true.
static Glob	and(Predicate<java.lang.String> predicate, Glob pattern) The matches(String) method of the returned Glob returns whether the predicate evaluates to true and the subject argument matches the pattern.
static Glob	compile(java.lang.String regex) Equivalent with compile(regex, 0).
static Glob	compile(java.lang.String pattern, int flags) Like compile(String), but with a flags parameter that modifies the compilation of the pattern.
static Glob	compileRegex(java.util.regex.Pattern regex) Returns a Glob who's replace(String) method will return its subject argument if the subject matches the given regular expression.
static Glob	compileRegex(java.util.regex.Pattern regex, java.lang.String replacement) The behavior of the matches(String) method of the returned Glob is as follows: If the regex matches the subject, then true is returned.
boolean	evaluate(java.lang.String subject) Implementation of Predicate.evaluate(T); calls {#matches}.
static Glob	fromPredicate(Predicate<java.lang.String> predicate)
abstract boolean	matches(java.lang.String subject)
static Glob	or(Glob pattern1, Glob pattern2) The matches(String) method of the returned Glob returns whether its subject argument matches pattern1 or, if not, pattern2.
java.lang.String	replace(java.lang.String subject) Iff the subject matches this Glob, then a non-null string ist returned; the algorithm that computes that string depends on the concrete Glob implementation; the default implementation simply returns the subject.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REPLACEMENT

public static final int REPLACEMENT

Modifies the pattern compilation as follows:

'=' is now a metacharacter, i.e. to include it literally in the pattern, it must be escaped with a backslash.

The semantics of '=' is as follows:

Replacement
a=b	If a subject matches a, then the replace(String) method does not return the subject, but b. The replacement string b may contain references to captured subsequences as in the Matcher.appendReplacement(java.lang.StringBuffer, java.lang.String) method.

See Also:

Constant Field Values

INCLUDES_EXCLUDES

public static final int INCLUDES_EXCLUDES

Modifies the pattern compilation as follows:

',' and '~' are now metacharacters, i.e. to include them literally in the pattern, they must be escaped with a backslash.

The semantics of ',' and '~' are as follows:

Construct	Matches
Includes and excludes
a,b	Any subject that matches a or b
a~b	Any subject that matches a, but not b

Patterns are applied right-to-left, i.e. the rightmost pattern that matches determines the result. This is particularly relevant in conjunction with REPLACEMENT.

See Also:

Constant Field Values

ANY

public static final Glob ANY

A Glob that matches any string (and thus replaces it with itself).

NONE

public static final Glob NONE

A Glob that matches no string.

Constructor Detail

Glob

public Glob()

Method Detail

matches

public abstract boolean matches(java.lang.String subject)

Returns:

Whether the subject matches this Glob.

evaluate

public boolean evaluate(@Nullable
                        java.lang.String subject)

Implementation of Predicate.evaluate(T); calls {#matches}.

If your code uses only Glob and not Predicate, you should favor calling matches(java.lang.String), because that method name is more expressive.

A subject value null evaluates to false.

Specified by:

evaluate in interface Predicate<java.lang.String>

Returns:

Whether the subject fulfils a particular condition

replace

@Nullable
public java.lang.String replace(java.lang.String subject)

Iff the subject matches this Glob, then a non-null string ist returned; the algorithm that computes that string depends on the concrete Glob implementation; the default implementation simply returns the subject.

Otherwise, null is returned.

compileRegex

public static Glob compileRegex(java.util.regex.Pattern regex)

Returns a Glob who's replace(String) method will return its subject argument if the subject matches the given regular expression.

compileRegex

public static Glob compileRegex(java.util.regex.Pattern regex,
                                @Nullable
                                java.lang.String replacement)

The behavior of the matches(String) method of the returned Glob is as follows:

• If the regex matches the subject, then true is returned.
• Otherwise, if the regex matches a prefix of subject, and that prefix is followed by '/' or '!', then true is returned. (Effectively, a glob 'dir' or 'dir/file.zip' matches all members and entries under 'dir' resp. 'dir/file.zip'.)
• Otherwise, if the subject ends with "!" or "/", and the regex could match the concatenation of the subject and another string, then true is returned. (Example: The subject "dir/" is matched by regexs "dir", "dir/", "dir/anything" and "**.c", but not by regexs "dirr/anything", "file", "*.c" and "file.zip!file".)
• Otherwise false is returned.

The behavior of the replace(String) method of the returned Glob is as follows:

• If the subject matches the regex, then a non-null string is returned:
  • If replacement is null, then the subject is returned.
  • Otherwise, replacement is returned with '$1', '$2', ... substituted with the regex's "capturing groups" (see Pattern).

See Also:

Matcher.appendReplacement(StringBuffer, String)

compile

public static Glob compile(java.lang.String regex)

Equivalent with compile(regex, 0).

See Also:

compile(String, int)

compile

public static Glob compile(java.lang.String pattern,
                           int flags)

Like compile(String), but with a flags parameter that modifies the compilation of the pattern.

Parameters:

flags - Modifies the semantics of the pattern, e.g. Pattern2.WILDCARD switches from regular expressions to wildcards

See Also:

INCLUDES_EXCLUDES, REPLACEMENT, Pattern2.WILDCARD, Pattern.CANON_EQ, Pattern.CASE_INSENSITIVE, Pattern.COMMENTS, Pattern.DOTALL, Pattern.LITERAL, Pattern.MULTILINE, Pattern.UNICODE_CASE, Pattern.UNIX_LINES

and

public static Glob and(Glob pattern1,
                       Glob pattern2)

The matches(String) method of the returned Glob returns whether its subject argument matches both pattern1 and pattern2.

The replace(String) method of the returned Glob returns checks whether the subject matches pattern1; if so, it calls replace(String) on pattern2 and returns the result; otherwise it returns null.

or

public static Glob or(Glob pattern1,
                      Glob pattern2)

The matches(String) method of the returned Glob returns whether its subject argument matches pattern1 or, if not, pattern2.

The replace(String) method of the returned Glob returns calls replace(String) on pattern1 and returns the result if it is not null; otherwise it calls replace(String) on pattern2 and returns the result.

and

public static Glob and(Predicate<java.lang.String> predicate,
                       Glob pattern)

The matches(String) method of the returned Glob returns whether the predicate evaluates to true and the subject argument matches the pattern.

The replace(String) method of the returned Glob returns checks whether the predicate evaluates to true; if so, it calls replace(String) on pattern and returns the result; otherwise it returns null.

and

public static Glob and(Glob pattern,
                       Predicate<java.lang.String> predicate)

The matches(String) method of the returned Glob returns whether the subject argument matches the pattern and the predicate evaluates to true.

The replace(String) method of the returned Glob returns checks whether the replace(String) on the pattern returns nuon-null and the predicate evaluates to true; if so, it returns the result of the replace(String) call; otherwise it returns null.

fromPredicate

public static Glob fromPredicate(Predicate<java.lang.String> predicate)

Returns:

A glob that wraps the given predicate