bsd_glob#

Expand a shell-style pattern and return the list of matching paths.

Synopsis#

my @list    = bsd_glob('*.[ch]');
my @homes   = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
my @latest  = bsd_glob('src/*.pl', GLOB_NOSORT);

What you get back#

A list of filenames, possibly empty. In scalar context you get the count of matches. Filenames are returned as plain strings in the order determined by the flags (alphabetical under the default GLOB_CSH, unsorted under GLOB_NOSORT).

When the pattern matches nothing and neither GLOB_NOCHECK nor GLOB_NOMAGIC is in effect, the list is empty. With GLOB_NOCHECK the original pattern is returned as the sole element; with GLOB_NOMAGIC the pattern is returned only when it contains no metacharacters.

Examples#

use File::Glob ':bsd_glob';
my @perl = bsd_glob('*.pl');          # ('a.pl', 'b.pl', ...)

# Brace expansion - default flags include GLOB_BRACE
my @src = bsd_glob('{lib,t}/*.pm');   # files under lib/ and t/

# Tilde expansion to another user's home
my ($home) = bsd_glob('~gnat', GLOB_TILDE);

# Case-insensitive match
my @readmes = bsd_glob('readme*', GLOB_NOCASE);

Edge cases#

  • No second argument: flags come from $File::Glob::DEFAULT_FLAGS (initialised to GLOB_CSH).

  • GLOB_APPEND, GLOB_DOOFFS, GLOB_ALTDIRFUNC and GLOB_MAGCHAR are cleared from the caller’s flags, as upstream clears them: they only make sense to a C caller.

  • A pattern containing an embedded NUL byte returns the empty list, sets $! to ENOENT and warns “Invalid \0 character in pattern for bsd_glob” (a syscalls warning).

  • Called with no pattern at all, croaks “Usage: File::Glob::bsd_glob(pattern_sv, …)”.

  • Under taint mode (-T) every returned name is tainted, as with every other glob form: filenames come from outside the program.

  • Brace alternatives are globbed one after the other, each sorted on its own: bsd_glob('{b,a}.*') lists the b names before the a names. A lone {} is kept as it is.

  • In a set, ! negates ([!a]*); ^ is an ordinary member.

See also#

  • csh_glob - the form Perl’s built-in glob uses internally.

  • GLOB_ERROR - non-zero after a traversal error.

  • GLOB_CSH - the default flag bundle.

  • GLOB_NOCHECK - return the pattern itself when nothing matches.