NAME

glob - 100% Perl implementation of (t)csh ``globbing''


SYNOPSIS

On the command-line:

    glob 'eenie{meenie,mynie,moe}*.[ch]'

As a Perl function:

    use FastGlob qw(glob);
    @list = &glob('eenie{meenie,mynie,moe}*.[ch]');


DESCRIPTION

The glob command/function implements globbing in perl, rather than forking a csh like Perl's built-in glob() call. This is faster than the built-in glob() call, and more robust (on many platforms, csh chokes on echo * if too many files are in the directory.)


Pattern Matching Syntax for Filename Expansion

The expressions that are passed as arguments to glob must adhere to csh/tcsh pattern-matching syntax for wildcard filename expansion (also known as globbing). Unquoted words containing an asterisk (*), question-mark (?), square-brackets ([...]), or curly-braces ({...}), or beginning with a tilde (~), are expanded into an alphabetically sorted list of filenames, as follows:

Only the patterns *, ? and [...] imply pattern matching; an error results if no filename matches a pattern that contains them. When a period or ``dot'' (.) is the first character in a filename or pathname component, it must be matched explicitly. The filename component separator character (e.g., / or slash) must also be matched explicitly.


OPTIONS

When invoking glob as a script from the command-line, if the very first argument is -0 (a minus sign followed by the number zero), then a NUL character (``\0'') is used to separate the expanded words and/or filenames when printing them to standard output. Otherwise a newline is used as the word/filename output separator.

When invoking glob as a function from the FastGlob module, There are several module-local variables that can be set for alternate environments, they are listed below with their (UNIX-ish) defaults.

        $FastGlob::dirsep = '/';        # directory path separator
        $FastGlob::rootpat = '\A\Z';    # root directory prefix pattern
        $FastGlob::curdir = '.';        # name of current directory in dir
        $FastGlob::parentdir = '..';    # name of parent directory in dir
        $FastGlob::hidedotfiles = 1;    # hide filenames starting with .

So for MS-DOS for example, you could set these to:

        $FastGlob::dirsep = '\\';       # directory path separator
        $FastGlob::rootpat = '[A-Z]:';  # <Drive letter><colon> pattern
        $FastGlob::curdir = '.';        # name of current directory in dir
        $FastGlob::parentdir = '..';    # name of parent directory in dir

        $FastGlob::hidedotfiles = 0;    # hide filenames starting with .

And for MacOS to:

        $FastGlob::dirsep = ':';        # directory path separator
        $FastGlob::rootpat = '\A\Z';    # root directory prefix pattern
        $FastGlob::curdir = '.';        # name of current directory in dir
        $FastGlob::parentdir = '..';    # name of parent directory in dir
        $FastGlob::hidedotfiles = 0;    # hide filenames starting with .

Furthermore, after a call to glob, the variable $FastGlob::matched will indicate the number of valid filenames that were matched, and the array @FastGlob::errors well contain a (possibly empty) list of error messages.


RETURNS

When glob is invoked as a script from the command-line, the exit-status returned will be 0 if any files were matched or word-sets were expanded; 1 if no files/word-sets were matched/expanded; and 2 if some other kind of error occurred.

When glob is invoked as a function from the FastGlob module, the return value will be an array of matching filenames and expanded word-sets.


DIAGNOSTICS

If no filenames are matched and pattern-matching characters were used (*, ?, or [...]), then an error message of ``No Match'' is issued. If a user's home directory is specified using tilde-expansion (e.g., ~username) but the corresponding username or their home directory cannot be found, then the error message ``Unknown user: username'' is issued.

NOTE that when glob is invoked as a script from the command-line then error messages are issued by printing them to standard diagnostic output (STDERR); When glob is invoked as a function from the FastGlob module, then error messages are issued by storing in the @FastGlob::errors array.


COPYRIGHT

Copyright (c) 1997-1999 Marc Mengel. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


AUTHOR

Marc Mengel <mengel@fnal.gov>


REVISIONS

Brad Appleton ltbradapp@enteract.comgt -- v1.2 March 1999

Modified to use qr// (and some other minor speedups), to explode subexpressions in curly braces (a la csh -- rather than using just plain alternation), and made callable as a standalone script.