Admin: Created page with "This article documents the "Globs" feature implemented in [http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/package-summary.html commons.unkrig.de]. === Introduction === Surely you have used globs before (maybe even without knowing that they call them "globs"): .txt dir/.doc execut?r.txt Globs are a widely spread concept that is used throughout the UNIX, MICROSOFT and other "worlds". All implementations support at least th..."

2024-05-01T20:18:28Z

Created page with "This article documents the "Globs" feature implemented in [http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/package-summary.html commons.unkrig.de]. === Introduction === Surely you have used globs before (maybe even without knowing that they call them "globs"): *.txt dir/*.doc execut?r.txt Globs are a widely spread concept that is used throughout the UNIX, MICROSOFT and other "worlds". All implementations support at least th..."

New page

This article documents the "Globs" feature implemented in [http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/package-summary.html commons.unkrig.de].

=== Introduction ===

Surely you have used globs before (maybe even without knowing that they call them "globs"):

*.txt
dir/*.doc
execut?r.txt

Globs are a widely spread concept that is used throughout the UNIX, MICROSOFT and other "worlds".

All implementations support at least the following elements:

{| class="wikitable"
!Construct !!Matches
|-
|<tt>?</tt> ||Any character except the file separator ("<code>/</code>" and/or "<code>\</code>")
|-
|<tt>*</tt> ||Zero or more characters except the file separator
|-
|<tt>''x''</tt>||The character <tt>''x''</tt>
|}

Some implementations add more features:

{| class="wikitable"
!Construct !!Matches
|-
|<tt>[abc]</tt> ||Exactly one of the characters "<tt>a</tt>", "<tt>b</tt>" and "<tt>c</tt>"
|-
|<tt>[^abc]</tt><br />or<br /><tt>[!abc]</tt>||Any character ''except'' "<tt>a</tt>", "<tt>b</tt>" or "<tt>c</tt>"
|-
|<tt>[A-Za-z]</tt> ||Any (latin) letter
|-
|<tt>**</tt> ||Zero or more characters (''including'' the file separator)
|-
|<tt>\''X''</tt> ||"<tt>''X''</tt>", even if "<tt>''X''</tt>" is a meta character
|}

Since version 1.7 JAVA provides [http://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher%28java.lang.String%29 its own implementation] of "glob matching", which adds another (quite uncommon) construct:

{| class="wikitable"
!Construct !!Matches
|-
|<tt>{''alpha'',''beta'',''gamma''}</tt>||Any of "<tt>alpha</tt>", "<tt>beta</tt>" or "<tt>gamma</tt>"
|}

All in all, globs are very practical, though not very powerful. This is why <code>de.unkrig.commons</code> provides yet another implementation, as follows:

=== Regular expressions features ===

First,
[http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/Pattern2.html <code>de.unkrig.commons.text.pattern.Pattern2</code>]
combines the simplicity of globs with the full power of
[http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/Pattern.html JAVA regular expressions].
It does so by modifying a few characters in the glob before feeding it to <code>java.util.text.pattern.Pattern.compile()</code>, making that effectively a glob compiler:

{| class="wikitable"
!Glob construct!!Regex construct !!Matches
|-
|<tt>?</tt> ||<tt>[^/\\!]*</tt>||Any character except the file separator and "!"
|-
|<tt>*</tt> ||<tt>[^/\\!]*</tt>||Zero or more characters except the file separator and "!"
|-
|<tt>**</tt> ||<tt>[^!]*</tt> ||Zero or more characters except "!"
|-
|<tt>***</tt> ||<tt>.*</tt> ||Zero or more characters
|-
|<tt>.</tt>||<tt>\.</tt>||The dot is a literal (not a character class as in a regular expression)
|-
|}

If you have not yet worked with regular expressions: JAVA regular expressions are very powerful and introduce many constructs and meta characters. Find the complete reference documentation [http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/Pattern.html here].

Since "<tt>?</tt>" and "<tt>*</tt>" are not quantifiers as in regular expression ("<tt>?</tt>" == zero-or-one, "<tt>*</tt>" == zero-or-more), one has to use "<tt>{0,1}</tt>" and "<tt>{0,}</tt>" instead. The alternative notation for "<tt>.</tt>" ("any character") is "<tt>[^]</tt>".

Find the reference documentation [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Pattern2.html here].

The API of
[http://commons.unkrig.de/commons-text/apidocs/index.html?de/unkrig/commons/text/pattern/Pattern2.html <code>de.unkrig.commons.text.pattern.Pattern2</code>]
is totally compatible with that of
[http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/Pattern.html <code>java.util.pattern.Pattern</code>],
plus it adds a new compilation Flag <code>Pattern2.WILDCARD</code> that modifies the expression syntax from regex to globs.

=== Includes-Excludes ===

Second, it adds ''includes-excludes''. This involves two new meta characters, "<code>,</code>" and "<code>~</code>":
{| class="wikitable"
!Construct !!Matches
|-
|<tt>''pattern1'',''pattern2''</tt>||Any string that matches ''pattern1'' or ''pattern2''
|-
|<tt>''pattern1''~''pattern2''</tt>||Any string that matches ''pattern1'', but not ''pattern2''
|-
|<tt>~''pattern1''</tt> ||Any string that does ''not'' match ''pattern1''
|-
|<tt>''pattern1'',''pattern2''~''pattern3''~''pattern4'',''pattern5''</tt>||Any string that matches ''pattern1'' or ''pattern2'', but not ''pattern3'' nor ''pattern4''; plus any string that matches ''pattern5''
|}

This may sound complicated, but the very simple rule is: The patterns are applied ''right-to-left'', and the first match determines the result.

This comes with [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Glob.html <tt>de.unkrig.commons.text.pattern.Glob.compile()</tt>] and the new [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Glob.html <tt>INCLUDES_EXCLUDES</tt>] compilation flag.

=== Replacements ===

Third, it adds ''replacements''. This involves one new meta character, "<tt>=</tt>":

{| class="wikitable"
!Construct !!Matches !!Replaces with
|-
|<tt>*.c=$0.bak</tt> ||Any string ending with "<tt>.c</tt>"||The original string plus "<tt>.bak</tt>" ("<tt>$0</tt>" represents the "entire match")
|-
|<tt>(*).(*)=$1.$2$2</tt>||Any string containing a dot ||The original string, with the file name extension doubled
|}

This comes with the [http://commons.unkrig.de/javadoc/index.html?de/unkrig/commons/text/pattern/Glob.html <tt>Glob.replace()</tt>] API.

Notice that "<tt>$</tt>" is a meta character ''only in the replacement''.

Also notice that when combining replacements with includes-excludes (see above), replacements are specific for ''each'' include (while it does not make any sense to use replacements with excludes, though).

=== Conclusion ===

All these features can be combined mercilessly, e.g.:

*=$0$0~*.bak
(*).docx{0,1}=$1.txt~*blabla*

Using it is simple:

import de.unkrig.commons.text.pattern.Glob;
import de.unkrig.commons.text.pattern.Pattern2;

Glob glob = Glob.compile("*.c=$0.C,*.h=$0.H", Pattern2.WILDCARD | Glob.INCLUDES_EXCLUDES | Glob.REPLACEMENT);
glob.match("foo.c"); // returns true
glob.replace("foo.h"); // returns "foo.H"
glob.replace("foo.cpp"); // returns null

Remember: The <tt>Pattern2.WILDCARD</tt> modifies the regex compilation to understand wildcard characters. <tt>Glob.INCLUDES_EXCLUDES</tt> activates the recognition of "<tt>,</tt>" and "<tt>~</tt>". Finally, <tt>Glob.REPLACEMENT</tt> activates the recognition of "<tt>=</tt>".

Using Globs - Revision history