Glob (de-unkrig-commons 1.1.4)

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

Fields
Modifier and Type	Field and Description
`static Glob`	`ANY` A `Glob` that `matches` any string (and thus `replace`s 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

Constructors
Constructor and Description

Glob()

Constructors
Constructor and Description
`Glob()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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<? super 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<? super 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 pattern)` Equivalent with `compile(regex, 0)`.
`static Glob`	`compile(java.lang.String pattern, int flags)` Similar to `Pattern.compile(String, int)`, but returns a `Glob` instead of a `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<? super 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

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

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 pattern)
```
  Equivalent with compile(regex, 0).
  
  See Also:
  
  compile(String, int)
- compile
```
public static Glob compile(java.lang.String pattern,
                           int flags)
```
  Similar to Pattern.compile(String, int), but returns a Glob instead of a Pattern.
  Iff the flag REPLACEMENT is set, then the pattern may include a "replacement".
  
  Iff a replacement is specified, then replace(String) will return the replacement, with "$1"... replaces with the match groups; otherwise the subject will be returned.
  
  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<? super 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<? super 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<? super java.lang.String> predicate)
```
  Returns:
  
  A glob that wraps the given predicate

Class Glob

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

REPLACEMENT

INCLUDES_EXCLUDES

ANY

NONE

Constructor Detail

Glob

Method Detail

matches

evaluate

replace

compileRegex

compileRegex

compile

compile

and

or

and

and

fromPredicate