[p5sagit/p5-mst-13.2.git] / ext / File / Glob / Glob.pm

package File::Glob;

use strict;
use Carp;
our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS,
    $AUTOLOAD, $DEFAULT_FLAGS);

require Exporter;
use XSLoader ();
require AutoLoader;

@ISA = qw(Exporter AutoLoader);

# NOTE: The glob() export is only here for compatibility with 5.6.0.
# csh_glob() should not be used directly, unless you know what you're doing.

@EXPORT_OK   = qw(
    csh_glob
    bsd_glob
    glob
    GLOB_ABEND
    GLOB_ALPHASORT
    GLOB_ALTDIRFUNC
    GLOB_BRACE
    GLOB_CSH
    GLOB_ERR
    GLOB_ERROR
    GLOB_MARK
    GLOB_NOCASE
    GLOB_NOCHECK
    GLOB_NOMAGIC
    GLOB_NOSORT
    GLOB_NOSPACE
    GLOB_QUOTE
    GLOB_TILDE
);

%EXPORT_TAGS = (
    'glob' => [ qw(
        GLOB_ABEND
	GLOB_ALPHASORT
        GLOB_ALTDIRFUNC
        GLOB_BRACE
        GLOB_CSH
        GLOB_ERR
        GLOB_ERROR
        GLOB_MARK
        GLOB_NOCASE
        GLOB_NOCHECK
        GLOB_NOMAGIC
        GLOB_NOSORT
        GLOB_NOSPACE
        GLOB_QUOTE
        GLOB_TILDE
        glob
        bsd_glob
    ) ],
);

$VERSION = '0.991';

sub import {
    my $i = 1;
    while ($i < @_) {
	if ($_[$i] =~ /^:(case|nocase|globally)$/) {
	    splice(@_, $i, 1);
	    $DEFAULT_FLAGS &= ~GLOB_NOCASE() if $1 eq 'case';
	    $DEFAULT_FLAGS |= GLOB_NOCASE() if $1 eq 'nocase';
	    if ($1 eq 'globally') {
		no warnings;
		*CORE::GLOBAL::glob = \&File::Glob::csh_glob;
	    }
	    next;
	}
	++$i;
    }
    goto &Exporter::import;
}

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.  If a constant is not found then control is passed
    # to the AUTOLOAD in AutoLoader.

    my $constname;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    my $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
	if ($! =~ /Invalid/) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
		croak "Your vendor has not defined File::Glob macro $constname";
	}
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

XSLoader::load 'File::Glob', $VERSION;

# Preloaded methods go here.

sub GLOB_ERROR {
    return constant('GLOB_ERROR', 0);
}

sub GLOB_CSH () {
    GLOB_BRACE()
	| GLOB_NOMAGIC()
	| GLOB_QUOTE()
	| GLOB_TILDE()
	| GLOB_ALPHASORT()
}

$DEFAULT_FLAGS = GLOB_CSH();
if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos|MacOS)$/) {
    $DEFAULT_FLAGS |= GLOB_NOCASE();
}

# Autoload methods go after =cut, and are processed by the autosplit program.

sub bsd_glob {
    my ($pat,$flags) = @_;
    $flags = $DEFAULT_FLAGS if @_ < 2;
    return doglob($pat,$flags);
}

# File::Glob::glob() is deprecated because its prototype is different from
# CORE::glob() (use bsd_glob() instead)
sub glob {
    goto &bsd_glob;
}

## borrowed heavily from gsar's File::DosGlob
my %iter;
my %entries;

sub csh_glob {
    my $pat = shift;
    my $cxix = shift;
    my @pat;

    # glob without args defaults to $_
    $pat = $_ unless defined $pat;

    # extract patterns
    $pat =~ s/^\s+//;	# Protect against empty elements in
    $pat =~ s/\s+$//;	# things like < *.c> and <*.c >.
			# These alone shouldn't trigger ParseWords.
    if ($pat =~ /\s/) {
        # XXX this is needed for compatibility with the csh
	# implementation in Perl.  Need to support a flag
	# to disable this behavior.
	require Text::ParseWords;
	@pat = Text::ParseWords::parse_line('\s+',0,$pat);
    }

    # assume global context if not provided one
    $cxix = '_G_' unless defined $cxix;
    $iter{$cxix} = 0 unless exists $iter{$cxix};

    # if we're just beginning, do it all first
    if ($iter{$cxix} == 0) {
	if (@pat) {
	    $entries{$cxix} = [ map { doglob($_, $DEFAULT_FLAGS) } @pat ];
	}
	else {
	    $entries{$cxix} = [ doglob($pat, $DEFAULT_FLAGS) ];
	}
    }

    # chuck it all out, quick or slow
    if (wantarray) {
        delete $iter{$cxix};
        return @{delete $entries{$cxix}};
    }
    else {
        if ($iter{$cxix} = scalar @{$entries{$cxix}}) {
            return shift @{$entries{$cxix}};
        }
        else {
            # return undef for EOL
            delete $iter{$cxix};
            delete $entries{$cxix};
            return undef;
        }
    }
}

1;
__END__

=head1 NAME

File::Glob - Perl extension for BSD glob routine

=head1 SYNOPSIS

  use File::Glob ':glob';
  @list = bsd_glob('*.[ch]');
  $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
  if (GLOB_ERROR) {
    # an error occurred reading $homedir
  }

  ## override the core glob (CORE::glob() does this automatically
  ## by default anyway, since v5.6.0)
  use File::Glob ':globally';
  my @sources = <*.{c,h,y}>

  ## override the core glob, forcing case sensitivity
  use File::Glob qw(:globally :case);
  my @sources = <*.{c,h,y}>

  ## override the core glob forcing case insensitivity
  use File::Glob qw(:globally :nocase);
  my @sources = <*.{c,h,y}>

=head1 DESCRIPTION

File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is
a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2").
bsd_glob() takes a mandatory C<pattern> argument, and an optional
C<flags> argument, and returns a list of filenames matching the
pattern, with interpretation of the pattern modified by the C<flags>
variable.

Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob().
Note that they don't share the same prototype--CORE::glob() only accepts
a single argument.  Due to historical reasons, CORE::glob() will also
split its argument on whitespace, treating it as multiple patterns,
whereas bsd_glob() considers them as one pattern.

The POSIX defined flags for bsd_glob() are:

=over 4

=item C<GLOB_ERR>

Force bsd_glob() to return an error when it encounters a directory it
cannot open or read.  Ordinarily bsd_glob() continues to find matches.

=item C<GLOB_MARK>

Each pathname that is a directory that matches the pattern has a slash
appended.

=item C<GLOB_NOCASE>

By default, file names are assumed to be case sensitive; this flag
makes bsd_glob() treat case differences as not significant.

=item C<GLOB_NOCHECK>

If the pattern does not match any pathname, then bsd_glob() returns a list
consisting of only the pattern.  If C<GLOB_QUOTE> is set, its effect
is present in the pattern returned.

=item C<GLOB_NOSORT>

By default, the pathnames are sorted in ascending ASCII order; this
flag prevents that sorting (speeding up bsd_glob()).

=back

The FreeBSD extensions to the POSIX standard are the following flags:

=over 4

=item C<GLOB_BRACE>

Pre-process the string to expand C<{pat,pat,...}> strings like csh(1).
The pattern '{}' is left unexpanded for historical reasons (and csh(1)
does the same thing to ease typing of find(1) patterns).

=item C<GLOB_NOMAGIC>

Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not
contain any of the special characters "*", "?" or "[".  C<NOMAGIC> is
provided to simplify implementing the historic csh(1) globbing
behaviour and should probably not be used anywhere else.

=item C<GLOB_QUOTE>

Use the backslash ('\') character for quoting: every occurrence of a
backslash followed by a character in the pattern is replaced by that
character, avoiding any special interpretation of the character.
(But see below for exceptions on DOSISH systems).

=item C<GLOB_TILDE>

Expand patterns that start with '~' to user name home directories.

=item C<GLOB_CSH>

For convenience, C<GLOB_CSH> is a synonym for
C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>.

=back

The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD
extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been
implemented in the Perl version because they involve more complex
interaction with the underlying C structures.

The following flag has been added in the Perl implementation for
csh compatibility:

=over 4

=item C<GLOB_ALPHASORT>

If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical
order (case does not matter) rather than in ASCII order.

=back

=head1 DIAGNOSTICS

bsd_glob() returns a list of matching paths, possibly zero length.  If an
error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be
set.  &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
or one of the following values otherwise:

=over 4

=item C<GLOB_NOSPACE>

An attempt to allocate memory failed.

=item C<GLOB_ABEND>

The glob was stopped because an error was encountered.

=back

In the case where bsd_glob() has found some matching paths, but is
interrupted by an error, it will return a list of filenames B<and>
set &File::Glob::ERROR.

Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will
continue processing despite those errors, unless the C<GLOB_ERR> flag is
set.

Be aware that all filenames returned from File::Glob are tainted.

=head1 NOTES

=over 4

=item *

If you want to use multiple patterns, e.g. C<bsd_glob "a* b*">, you should
probably throw them in a set as in C<bsd_glob "{a*,b*}">.  This is because
the argument to bsd_glob() isn't subjected to parsing by the C shell.
Remember that you can use a backslash to escape things.

=item *

On DOSISH systems, backslash is a valid directory separator character.
In this case, use of backslash as a quoting character (via GLOB_QUOTE)
interferes with the use of backslash as a directory separator. The
best (simplest, most portable) solution is to use forward slashes for
directory separators, and backslashes for quoting. However, this does
not match "normal practice" on these systems. As a concession to user
expectation, therefore, backslashes (under GLOB_QUOTE) only quote the
glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself.
All other backslashes are passed through unchanged.

=item *

Win32 users should use the real slash.  If you really want to use
backslashes, consider using Sarathy's File::DosGlob, which comes with
the standard Perl distribution.

=item *

Mac OS (Classic) users should note a few differences. Since
Mac OS is not Unix, when the glob code encounters a tilde glob (e.g.
~user/foo) and the C<GLOB_TILDE> flag is used, it simply returns that
pattern without doing any expansion.

Glob on Mac OS is case-insensitive by default (if you don't use any
flags). If you specify any flags at all and still want glob
to be case-insensitive, you must include C<GLOB_NOCASE> in the flags.

The path separator is ':' (aka colon), not '/' (aka slash). Mac OS users
should be careful about specifying relative pathnames. While a full path
always begins with a volume name, a relative pathname should always
begin with a ':'.  If specifying a volume name only, a trailing ':' is
required.

=back

=head1 AUTHOR

The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>,
and is released under the artistic license.  Further modifications were
made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy
E<lt>gsar@activestate.comE<gt>, and Thomas Wegner
E<lt>wegner_thomas@yahoo.comE<gt>.  The C glob code has the
following copyright:

    Copyright (c) 1989, 1993 The Regents of the University of California.
    All rights reserved.

    This code is derived from software contributed to Berkeley by
    Guido van Rossum.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    3. Neither the name of the University nor the names of its contributors
       may be used to endorse or promote products derived from this software
       without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.

=cut
Commit	Line	Data
72b16652	1	package File::Glob;
	2
	3	use strict;
	4	use Carp;
17f410f9	5	our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS,
17f410f9	6	$AUTOLOAD, $DEFAULT_FLAGS);
72b16652	7
72b16652	8	require Exporter;
9426adcd	9	use XSLoader ();
72b16652	10	require AutoLoader;
72b16652	11
9426adcd	12	@ISA = qw(Exporter AutoLoader);
72b16652	13
00c80938	14	# NOTE: The glob() export is only here for compatibility with 5.6.0.
	15	# csh_glob() should not be used directly, unless you know what you're doing.
	16
72b16652	17	@EXPORT_OK = qw(
72b16652	18	csh_glob
00c80938	19	bsd_glob
72b16652	20	glob
72b16652	21	GLOB_ABEND
2d5e9e5d	22	GLOB_ALPHASORT
72b16652	23	GLOB_ALTDIRFUNC
72b16652	24	GLOB_BRACE
220398a0	25	GLOB_CSH
72b16652	26	GLOB_ERR
	27	GLOB_ERROR
	28	GLOB_MARK
220398a0	29	GLOB_NOCASE
72b16652	30	GLOB_NOCHECK
	31	GLOB_NOMAGIC
	32	GLOB_NOSORT
	33	GLOB_NOSPACE
	34	GLOB_QUOTE
	35	GLOB_TILDE
	36	);
	37
72b16652	38	%EXPORT_TAGS = (
	39	'glob' => [ qw(
	40	GLOB_ABEND
2d5e9e5d	41	GLOB_ALPHASORT
72b16652	42	GLOB_ALTDIRFUNC
72b16652	43	GLOB_BRACE
220398a0	44	GLOB_CSH
72b16652	45	GLOB_ERR
	46	GLOB_ERROR
	47	GLOB_MARK
220398a0	48	GLOB_NOCASE
72b16652	49	GLOB_NOCHECK
	50	GLOB_NOMAGIC
	51	GLOB_NOSORT
	52	GLOB_NOSPACE
	53	GLOB_QUOTE
	54	GLOB_TILDE
	55	glob
00c80938	56	bsd_glob
72b16652	57	) ],
	58	);
	59
220398a0	60	$VERSION = '0.991';
	61
	62	sub import {
	63	my $i = 1;
	64	while ($i < @_) {
	65	if ($_[$i] =~ /^:(case\|nocase\|globally)$/) {
	66	splice(@_, $i, 1);
	67	$DEFAULT_FLAGS &= ~GLOB_NOCASE() if $1 eq 'case';
	68	$DEFAULT_FLAGS \|= GLOB_NOCASE() if $1 eq 'nocase';
	69	if ($1 eq 'globally') {
9f1b1f2d	70	no warnings;
220398a0	71	*CORE::GLOBAL::glob = \&File::Glob::csh_glob;
	72	}
	73	next;
	74	}
	75	++$i;
72b16652	76	}
220398a0	77	goto &Exporter::import;
72b16652	78	}
	79
	80	sub AUTOLOAD {
	81	# This AUTOLOAD is used to 'autoload' constants from the constant()
	82	# XS function. If a constant is not found then control is passed
	83	# to the AUTOLOAD in AutoLoader.
	84
	85	my $constname;
	86	($constname = $AUTOLOAD) =~ s/.*:://;
	87	my $val = constant($constname, @_ ? $_[0] : 0);
	88	if ($! != 0) {
	89	if ($! =~ /Invalid/) {
	90	$AutoLoader::AUTOLOAD = $AUTOLOAD;
	91	goto &AutoLoader::AUTOLOAD;
	92	}
	93	else {
	94	croak "Your vendor has not defined File::Glob macro $constname";
	95	}
	96	}
	97	eval "sub $AUTOLOAD { $val }";
	98	goto &$AUTOLOAD;
	99	}
	100
9426adcd	101	XSLoader::load 'File::Glob', $VERSION;
72b16652	102
	103	# Preloaded methods go here.
	104
	105	sub GLOB_ERROR {
	106	return constant('GLOB_ERROR', 0);
	107	}
	108
2d5e9e5d	109	sub GLOB_CSH () {
	110	GLOB_BRACE()
	111	\| GLOB_NOMAGIC()
	112	\| GLOB_QUOTE()
	113	\| GLOB_TILDE()
	114	\| GLOB_ALPHASORT()
	115	}
72b16652	116
220398a0	117	$DEFAULT_FLAGS = GLOB_CSH();
	118	if ($^O =~ /^(?:MSWin32\|VMS\|os2\|dos\|riscos\|MacOS)$/) {
	119	$DEFAULT_FLAGS \|= GLOB_NOCASE();
	120	}
	121
72b16652	122	# Autoload methods go after =cut, and are processed by the autosplit program.
72b16652	123
00c80938	124	sub bsd_glob {
f0963acb	125	my ($pat,$flags) = @_;
	126	$flags = $DEFAULT_FLAGS if @_ < 2;
	127	return doglob($pat,$flags);
72b16652	128	}
72b16652	129
00c80938	130	# File::Glob::glob() is deprecated because its prototype is different from
	131	# CORE::glob() (use bsd_glob() instead)
	132	sub glob {
	133	goto &bsd_glob;
	134	}
	135
72b16652	136	## borrowed heavily from gsar's File::DosGlob
	137	my %iter;
	138	my %entries;
	139
	140	sub csh_glob {
	141	my $pat = shift;
	142	my $cxix = shift;
	143	my @pat;
	144
	145	# glob without args defaults to $_
	146	$pat = $_ unless defined $pat;
	147
	148	# extract patterns
be3174d2	149	$pat =~ s/^\s+//; # Protect against empty elements in
	150	$pat =~ s/\s+$//; # things like < .c> and <.c >.
	151	# These alone shouldn't trigger ParseWords.
72b16652	152	if ($pat =~ /\s/) {
	153	# XXX this is needed for compatibility with the csh
	154	# implementation in Perl. Need to support a flag
	155	# to disable this behavior.
	156	require Text::ParseWords;
	157	@pat = Text::ParseWords::parse_line('\s+',0,$pat);
	158	}
	159
	160	# assume global context if not provided one
	161	$cxix = '_G_' unless defined $cxix;
	162	$iter{$cxix} = 0 unless exists $iter{$cxix};
	163
	164	# if we're just beginning, do it all first
	165	if ($iter{$cxix} == 0) {
	166	if (@pat) {
220398a0	167	$entries{$cxix} = [ map { doglob($_, $DEFAULT_FLAGS) } @pat ];
72b16652	168	}
72b16652	169	else {
220398a0	170	$entries{$cxix} = [ doglob($pat, $DEFAULT_FLAGS) ];
72b16652	171	}
	172	}
	173
	174	# chuck it all out, quick or slow
	175	if (wantarray) {
	176	delete $iter{$cxix};
	177	return @{delete $entries{$cxix}};
	178	}
	179	else {
	180	if ($iter{$cxix} = scalar @{$entries{$cxix}}) {
	181	return shift @{$entries{$cxix}};
	182	}
	183	else {
	184	# return undef for EOL
	185	delete $iter{$cxix};
	186	delete $entries{$cxix};
	187	return undef;
	188	}
	189	}
	190	}
	191
	192	1;
	193	__END__
	194
	195	=head1 NAME
	196
	197	File::Glob - Perl extension for BSD glob routine
	198
	199	=head1 SYNOPSIS
	200
	201	use File::Glob ':glob';
00c80938	202	@list = bsd_glob('*.[ch]');
00c80938	203	$homedir = bsd_glob('~gnat', GLOB_TILDE \| GLOB_ERR);
72b16652	204	if (GLOB_ERROR) {
	205	# an error occurred reading $homedir
	206	}
	207
00c80938	208	## override the core glob (CORE::glob() does this automatically
11fe14b1	209	## by default anyway, since v5.6.0)
220398a0	210	use File::Glob ':globally';
	211	my @sources = <*.{c,h,y}>
	212
	213	## override the core glob, forcing case sensitivity
	214	use File::Glob qw(:globally :case);
	215	my @sources = <*.{c,h,y}>
	216
	217	## override the core glob forcing case insensitivity
	218	use File::Glob qw(:globally :nocase);
72b16652	219	my @sources = <*.{c,h,y}>
	220
	221	=head1 DESCRIPTION
	222
00c80938	223	File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is
	224	a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2").
	225	bsd_glob() takes a mandatory C<pattern> argument, and an optional
72b16652	226	C<flags> argument, and returns a list of filenames matching the
72b16652	227	pattern, with interpretation of the pattern modified by the C<flags>
00c80938	228	variable.
	229
	230	Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob().
	231	Note that they don't share the same prototype--CORE::glob() only accepts
	232	a single argument. Due to historical reasons, CORE::glob() will also
	233	split its argument on whitespace, treating it as multiple patterns,
	234	whereas bsd_glob() considers them as one pattern.
	235
	236	The POSIX defined flags for bsd_glob() are:
72b16652	237
	238	=over 4
	239
	240	=item C<GLOB_ERR>
	241
00c80938	242	Force bsd_glob() to return an error when it encounters a directory it
00c80938	243	cannot open or read. Ordinarily bsd_glob() continues to find matches.
72b16652	244
	245	=item C<GLOB_MARK>
	246
	247	Each pathname that is a directory that matches the pattern has a slash
	248	appended.
	249
220398a0	250	=item C<GLOB_NOCASE>
	251
	252	By default, file names are assumed to be case sensitive; this flag
00c80938	253	makes bsd_glob() treat case differences as not significant.
220398a0	254
72b16652	255	=item C<GLOB_NOCHECK>
72b16652	256
00c80938	257	If the pattern does not match any pathname, then bsd_glob() returns a list
72b16652	258	consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect
	259	is present in the pattern returned.
	260
	261	=item C<GLOB_NOSORT>
	262
	263	By default, the pathnames are sorted in ascending ASCII order; this
00c80938	264	flag prevents that sorting (speeding up bsd_glob()).
72b16652	265
	266	=back
	267
	268	The FreeBSD extensions to the POSIX standard are the following flags:
	269
	270	=over 4
	271
	272	=item C<GLOB_BRACE>
	273
a45bd81d	274	Pre-process the string to expand C<{pat,pat,...}> strings like csh(1).
72b16652	275	The pattern '{}' is left unexpanded for historical reasons (and csh(1)
	276	does the same thing to ease typing of find(1) patterns).
	277
	278	=item C<GLOB_NOMAGIC>
	279
	280	Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not
	281	contain any of the special characters "*", "?" or "[". C<NOMAGIC> is
	282	provided to simplify implementing the historic csh(1) globbing
	283	behaviour and should probably not be used anywhere else.
	284
	285	=item C<GLOB_QUOTE>
	286
	287	Use the backslash ('\') character for quoting: every occurrence of a
	288	backslash followed by a character in the pattern is replaced by that
	289	character, avoiding any special interpretation of the character.
220398a0	290	(But see below for exceptions on DOSISH systems).
72b16652	291
	292	=item C<GLOB_TILDE>
	293
	294	Expand patterns that start with '~' to user name home directories.
	295
	296	=item C<GLOB_CSH>
	297
	298	For convenience, C<GLOB_CSH> is a synonym for
2d5e9e5d	299	C<GLOB_BRACE \| GLOB_NOMAGIC \| GLOB_QUOTE \| GLOB_TILDE \| GLOB_ALPHASORT>.
72b16652	300
	301	=back
	302
	303	The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD
	304	extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been
	305	implemented in the Perl version because they involve more complex
	306	interaction with the underlying C structures.
	307
2d5e9e5d	308	The following flag has been added in the Perl implementation for
	309	csh compatibility:
	310
	311	=over 4
	312
	313	=item C<GLOB_ALPHASORT>
	314
	315	If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical
	316	order (case does not matter) rather than in ASCII order.
	317
	318	=back
	319
72b16652	320	=head1 DIAGNOSTICS
72b16652	321
00c80938	322	bsd_glob() returns a list of matching paths, possibly zero length. If an
72b16652	323	error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be
	324	set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
	325	or one of the following values otherwise:
	326
	327	=over 4
	328
	329	=item C<GLOB_NOSPACE>
	330
	331	An attempt to allocate memory failed.
	332
	333	=item C<GLOB_ABEND>
	334
	335	The glob was stopped because an error was encountered.
	336
	337	=back
	338
00c80938	339	In the case where bsd_glob() has found some matching paths, but is
00c80938	340	interrupted by an error, it will return a list of filenames B<and>
72b16652	341	set &File::Glob::ERROR.
72b16652	342
00c80938	343	Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
00c80938	344	by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will
72b16652	345	continue processing despite those errors, unless the C<GLOB_ERR> flag is
	346	set.
	347
	348	Be aware that all filenames returned from File::Glob are tainted.
	349
	350	=head1 NOTES
	351
	352	=over 4
	353
	354	=item *
	355
00c80938	356	If you want to use multiple patterns, e.g. C<bsd_glob "a* b*">, you should
150b260b	357	probably throw them in a set as in C<bsd_glob "{a,b}">. This is because
	358	the argument to bsd_glob() isn't subjected to parsing by the C shell.
	359	Remember that you can use a backslash to escape things.
72b16652	360
	361	=item *
	362
220398a0	363	On DOSISH systems, backslash is a valid directory separator character.
	364	In this case, use of backslash as a quoting character (via GLOB_QUOTE)
	365	interferes with the use of backslash as a directory separator. The
	366	best (simplest, most portable) solution is to use forward slashes for
	367	directory separators, and backslashes for quoting. However, this does
	368	not match "normal practice" on these systems. As a concession to user
	369	expectation, therefore, backslashes (under GLOB_QUOTE) only quote the
	370	glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself.
	371	All other backslashes are passed through unchanged.
	372
	373	=item *
	374
72b16652	375	Win32 users should use the real slash. If you really want to use
	376	backslashes, consider using Sarathy's File::DosGlob, which comes with
	377	the standard Perl distribution.
	378
7369a524	379	=item *
	380
	381	Mac OS (Classic) users should note a few differences. Since
	382	Mac OS is not Unix, when the glob code encounters a tilde glob (e.g.
	383	~user/foo) and the C<GLOB_TILDE> flag is used, it simply returns that
	384	pattern without doing any expansion.
	385
	386	Glob on Mac OS is case-insensitive by default (if you don't use any
	387	flags). If you specify any flags at all and still want glob
	388	to be case-insensitive, you must include C<GLOB_NOCASE> in the flags.
	389
	390	The path separator is ':' (aka colon), not '/' (aka slash). Mac OS users
	391	should be careful about specifying relative pathnames. While a full path
	392	always begins with a volume name, a relative pathname should always
	393	begin with a ':'. If specifying a volume name only, a trailing ':' is
	394	required.
	395
a45bd81d	396	=back
a45bd81d	397
72b16652	398	=head1 AUTHOR
72b16652	399
0e950d83	400	The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>,
72b16652	401	and is released under the artistic license. Further modifications were
7369a524	402	made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy
	403	E<lt>gsar@activestate.comE<gt>, and Thomas Wegner
	404	E<lt>wegner_thomas@yahoo.comE<gt>. The C glob code has the
72b16652	405	following copyright:
72b16652	406
0e950d83	407	Copyright (c) 1989, 1993 The Regents of the University of California.
0e950d83	408	All rights reserved.
3cb6de81	409
0e950d83	410	This code is derived from software contributed to Berkeley by
	411	Guido van Rossum.
	412
	413	Redistribution and use in source and binary forms, with or without
	414	modification, are permitted provided that the following conditions
	415	are met:
	416
	417	1. Redistributions of source code must retain the above copyright
	418	notice, this list of conditions and the following disclaimer.
	419	2. Redistributions in binary form must reproduce the above copyright
	420	notice, this list of conditions and the following disclaimer in the
	421	documentation and/or other materials provided with the distribution.
	422	3. Neither the name of the University nor the names of its contributors
	423	may be used to endorse or promote products derived from this software
	424	without specific prior written permission.
	425
	426	THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	427	ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	428	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	429	ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	430	FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	431	DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	432	OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	433	HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	434	LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	435	OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	436	SUCH DAMAGE.
72b16652	437
72b16652	438	=cut