/ 
File-Globstar-0.1
River stage one • 1 direct dependent • 1 total dependent
/ File::Globstar

NAME

File::Globstar - Globbing With Double Asterisk Expansion

SYNOPSIS

use File::Globstar qw(globstar fnmatchstar);

@files = globstar '**/*.css';
@files = globstar 'css/**/*.css';
@files = globstar 'scss/**';

print "Match!\n" if fnmatchstar '*.pl', 'hello.pl';
print "Case-insensitive match!\n" 
    if fnmatchstar '*.pl', 'Makefile.PL', ignoreCase => 1;

$re = File::Globstar::translatestar('**/*.css');

$safe_pattern = quotestar $config_srcdir;

DESCRIPTION

Shortcut: If you want to implement file inclusion or exclusion in the style of .gitignore, have a look at File::Globstar::ListMatch.

Many globbing implementations have been recently extended to accept the pattern ** in place of a path element. The double asterisk matches all files and directories in the current directory and all of its descendants including the current directory itself (in other words: the directory . is included in the match, the parent directory .. is not).

The convention is especially popular in the Node.js ecosystem and is also used by git when evaluating ignore patterns (see https://git-scm.com/docs/gitignore).

FUNCTIONS

globstar PATTERN[, DIRECTORY]

Return all files and directories matching PATTERN in DIRECTORY. DIRECTORY defaults to the current directory if empty or undefined.

An invalid PATTERN matches nothing and globstar() returns an empty list for it.

The function only expand the sequence "**" (at the appropriate) positions. All other heavy lifting is done by File::Glob::bsd_glob() (which is also the backend for the standard Perl glob operator <HANDLE>.

Currently, only the (forward!) slash is accepted as a path separator!

fnmatchstar PATTERN, STRING[, OPTIONS]

Returns 1 if STRING matches PATTERN, false otherwise. If a Perl truthy value is passed as the optional third argument, case is ignored for the match.

OPTIONS is an optional hash of named arguments. The only supported option is "ignoreCase" at the moment.

Invalid PATTERNs never match.

Unlike globstar(), the function does not rely on File::Glob and is implemented entirely in Perl. The semantics of PATTERN are as follows:

*

A single asterisk stands for zero or more arbitrary characters except for the slash /.

?

The question mark stands for exactly one character except for the slash /.

**

A double asterisk stands for an arbitrary sequence of 0 or more characters. It is only allowed when preceded by either the beginning of the string or a slash. Likewise it must be followed by a slash or the end of the pattern.

[RANGE], [!RANGE]

A character range or a negated character range that is preceded by an exclamation mark. A range cannot be empty.

The following features are supported:

CHARACTER

By default, all CHARACTERs stand for themselves.

CHARACTER1-CHARACTER2

All characters from CHARACTER1 to CHARACTER2 according to the collation valid for the currently selected locale.

[:CLASS:]

A character class like "[:print:]", "[:upper:]", "[:lower:]". Example:

[0-9[:lower:]]

This pattern stands for exactly one character, either one of the ASCII digits 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9 or any lowercase character (according to the current locale).

\CHARACTER

Any character with a special meaning can be escaped with a backslash.

You can include a hyphen in a range by using it as the last character. You can include a closing square bracket by using it as the first character. This is implied by the above rules.

Example:

[]-]

This pattern matches either a closing square bracket "]" or a hyphen "-".

Note that POSIX collation classes (for example "[.ch.]") and POSIX equivalence classes (for example "[=a=]") are not supported. Rationale: bsd_glob() does not support them and in Perl regular expression character classes they are currently not supported and their usage throws an exception.

translatestar PATTERN[, OPTIONS]

Compiles PATTERN into a Perl regular expression or throws an exception in case of failure. This function is used internally by fnmatchstar().

OPTIONS is an optional hash of named arguments. The only supported option is "ignoreCase" at the moment.

quotestar STRING[, NEGATABLE]

Escapes all characters special to globstar patterns. This are:

\\ the backslash
* the asterisk/star
[ the opening square bracket
] the closing square bracket (actually unneeded but ...)

If the optional argument NEGATABLE is truthy, a leading exclamation mark will also be backslash-escaped.

EXAMPLES

First, let's look at some examples for the double asterisk pattern.

**/*.css

All files matching the name *.css in the current directory and all its descendants, for example main.css, styles/body.css, styles/body/footer.css, styles/footer/whatever.css and so on.

src/**

The directory src and all files and directories underneath src, for example src/a, src/b, src/a/x/y, and so on.

src/**/*.c

All *.c files in the directory src or one if its descendants, for example src/file.c, src/a/file.c, src/b/file.c, src/a/x/file.c, and so on.

GORY DETAILS

The function globstar() is a wrapper around bsd_glob (see File::Glob) that extends the functionality with the double asterisk semantics. A double asterisk is only allowed in the following cases:

**/...

At the beginning of a pattern, when followed by a slash.

.../**/...

Anywhere inside a pattern, when preceded and followed by a slash.

.../**

At the end of a pattern, when preceded by a slash.

**

The pattern ** expands to all files and directories in the current directory with arbitrary nesting level.

All other usages of two consecutive asterisks are considered illegal. An illegal pattern does not match any file. The file foo***bar for example does not match the pattern foo***bar. It matches, however, foo\*\*\*bar.

Of course, all other features of File::Glob::bsd_glob() are supported as well. The module also suffers from the same bugs and incompatibilities.

BUGS AND CAVEATS

Other than the ones currently unknown, be prepared for the following:

COMPATIBILITY

The module assumes that the (forward!) slash "/" is the only valid path separator. Especially the backslash "\\" is only used for escaping and never as a path separator. On the other hand, the underlying function bsd_glob() from File::Glob does support other path separators than a slash.

This behavior may change in the future. The main reason why the backslash is not supported as a path separator is that I have no idea how bsd_glob() behaves exactly, for example under Windows. Patches are welcome!

UNIFORM BEHAVIOR OF GLOBSTAR() AND FNMATCHSTAR()

The functions should theoretically behave accordingly. If globstar() returns a filename for a certain pattern, then fnmatchstar() should return true for the same pattern and the filename passed as a string.

Unfortunately, the two implementations are completely independent, and this cannot be guaranteed. Please file a bug if you find a discrepancy.

CASE-INSENSITIVE FILE SYSTEMS

The behavior of globstar() completely depends on the behavior of the underlying File::Glob. For fnmatchstar() you can pass a third argument specifying whether the match should be done case-insensitively or not.

For real-world scenarios you should be aware that on non-Windows systems, every directory level could behave differently: While "/media/disk1/backup" can be case-sensitive, "/media/disk1/backup/data" could be case-preserving and "/media/disk2/mp3" could be case-insensitive.

COPYRIGHT

Copyright (C) 2016-2017 Guido Flohr <guido.flohr@cantanea.com>, all rights reserved.

SEE ALSO

File::Glob(3pm), File::Globstar::Listmatch(3pm), glob(3), glob(7), fnmatch(3), glob(1), perl(1)