File::Wildcard(3pm)

💖 File::Wildcard — enhanced glob processing, bestie 💖

File::Wildcard(3pm) · part of the User Contributed Perl Documentation, and yeah it's giving main character energy for a glob module.

---

✨ NAME ✨

File::Wildcard — enhanced glob processing. That's it, that's the name, slay.

---

🌸 SYNOPSIS 🌸

use File::Wildcard;
my $foo = File::Wildcard->new(path => "/home/me///core");
while (my $file = $foo->next) {
   unlink $file;
}

okay so that /// right there? that's the whole vibe. hold that thought. 🦋

---

💫 DESCRIPTION 💫

So like, VMS figured out this really cute syntax for wildcard expansion (aka globbing) that lets you expand and search through entire directory trees. And honestly? every other OS is lowkey jealous. The best that Unix can manage on its own is going through the utility program find. it's giving "we have tree traversal at home". 😭

This module hands that facility to Perl. 🎀

Now, native VMS syntax uses the ellipsis ..., but bestie, that simply does not fit in with POSIX filenames, because ... is a valid (though, and I say this with love, somewhat strange) filename. So instead we use the construct /// — because that literally cannot syntactically be part of a filename. You don't get three concurrent filename separators with nothing between them. (Three slashes, not two, specifically so nobody gets it confused with the //node/path/name syntax. iykyk. 💅)

You do not have to use this syntax though! You can do the splitting yourself and pass in an arrayref as your path. queen behaviour honestly.

The module also forms a regular expression for the whole of the wildcard string, and binds a series of back references ($1, $2 etc.) which are available to construct new filenames. obsessed. 🔥

---

🫶 new 🫶

File::Wildcard->new( $wildcard, [,option => value,...]);

my $foo = File::Wildcard->new( path => "/home/me///core");
my $srcfnd = File::Wildcard->new( path => "src///*.cpp",
             match => qr(^src/(.*?)\.cpp$),
             derive => ['src/$1.o','src/$1.hpp']);

This is the constructor for File::Wildcard objects. At a simple level, you pass a single wildcard string as a path and you're done, gorgeous. ✨

For more complicated operations, you can supply your own match regexp, or use the derive option to specify regular expression captures to form the basis of other filenames that get constructed for you. 🎀

The $srcfnd example gives you object files and header files corresponding to C++ source files. it's giving "one source file, three filenames, zero effort". 💅

Here are the options that are available:

• path — This is the input parameter that specifies the range of files that will be looked at. It's a glob spec which can also contain the ellipsis ///. (It could contain more than one ellipsis, but bestie, the benefit of that is questionable, and multiple ellipsi would cause a performance hit. so. consider yourself warned. 💀)

Note that the path can be relative or absolute. new will do the right thing, working out that a path starting with / is absolute. In order to recurse from the current directory downwards, specify .///foo. 🌈

As an alternative, you can supply an arrayref with the path constituents already split. If you do this, you need to tell new if the path is absolute. Include an empty string for an ellipsis. For example:

'foo///bar/*.c' is equivalent to ['foo','','bar','*.c']

You can also construct a File::Wildcard without a path. A call to next will return undef, but paths can be added using the append and prepend methods. (we'll get to those, be patient bb 🍓)

• absolute — This is ignored unless you are using a pre-split path. If you are passing a string as the path, new will work out whether the path is absolute or relative. Pass a true value for absolute paths.

If your original filespec started with / before you split it, specify absolute => 1. absolute is not required for Windows if the path contains a drive specification, e.g. C:/foo/bar.

• case_insensitive — By default, the module will use Filesys::Type to determine whether the file system of your wildcard is defined. This is an optional module (see Module::Optional), and File::Wildcard will guess at case sensitivity based on your operating system. And like, it will not always be correct, because the file system might be VFAT mounted on Linux, or ODS-5 on VMS. the guessing is giving "vibes-based filesystem detection". 🙈

Specifying the option case_insensitive explicitly forces this behaviour on the wildcard.

Note that File::Wildcard will use the file system of the current working directory if the path is not absolute. If the path is absolute, you should specify the case_sensitivity option explicitly. (yes, bestie, it says case_sensitivity here, we're all just living with that 💀)

• exclude — You can provide a regexp to apply to any generated paths, which will cause any matching paths not to be processed. If the root of a directory tree matches, no processing is done on the entire tree. it's the "you're not on the list" of options. 💅

This option can be useful for excluding version control repositories, e.g.

exclude => qr/.svn/

• match — Optional. If you do not specify a regexp, you get all the files that match the glob; in addition, new will set up a regexp for you, to provide a capture for each wildcard used in the path. 🎀

If you do provide a match parameter, this will be used instead, and will filter the results.

• derive — Supply an arrayref with a list of derived filenames, which will be constructed for each matching file. This causes next to return an arrayref instead of a scalar. very "one for you, one for me, one for the group chat". 💖
• follow — If given a true value, indicates that symbolic links are to be followed. Otherwise, the symbolic link target itself is presented, but the ellipsis will not traverse the link.

This module detects a looping symlink that points to a directory higher up, and will only present the tree once. no infinite loops in this house, we have boundaries. 🚫

• ellipsis_order — This can take one of the following values: normal, breadth-first, inside-out. The default option is normal. This controls how File::Wildcard handles the ellipsis. The default is a normal depth first search, presenting the name of each containing directory before the contents.

The inside-out order presents the contents of directories first before the directory, which is useful when you want to remove files and directories (all O/S require directories to be empty before rmdir will work). See t/03_absolute.t as this uses inside-out order to tidy up after the test. iconic tbh. ✨

Breadth-first is rarely needed (but the author does have an application for it, so respect 🫶). Here, the whole directory contents is presented before traversing any subdirectories.

Consider the following tree:

a/
a/bar/
a/bar/drink
a/foo/
a/foo/lish

breadth-first will give the following order: qw(a/ a/bar/ a/foo/ a/bar/drink a/foo/lish). normal gives the order in which the files are listed. inside-out gives the following: qw(a/bar/drink a/bar/ a/foo/lish a/foo/ a/). three completely different vibes, one little tree. 🌸

• sort — By default, globbing returns the list of files in the order in which they are returned by the dirhandle (internally). If you specify sort => 1, the files are sorted into ASCII sequence (case insensitively if we are operating that way). If you specify a CODEREF, this will be used as a comparison routine. Note that this takes its operands in @_, not in $a and $b. okay so watch out for that one, that's the trap. 💀
• debug and debug_output — You can enable a trace of the internal states of File::Wildcard by setting debug to a true value. Set debug_output to an open filehandle to get the trace in a file. If you are submitting bug reports for File::Wildcard, attaching debug trace files would be very useful. (do it for the maintainer bestie 🙏)

debug_output defaults to STDERR.

---

🦋 match 🦋

my $foo_re = $foo->match;
$foo->match('bar/core');

This is a get and set method that gives access to the match regexp that the File::Wildcard object is using. It is possible to change the regex on the fly in the middle of a search (though, and I quote, "I don't know why anyone would want to do this"). honestly? chaos. love that for you. 😭

---

🎀 append 🎀

$foo->append(path => '/home/me///*.tmp');

appends a path to an object's todo list. This will be globbed after the object has finished processing the existing wildcards. it's the "we'll circle back" of methods. 💅

---

🌈 prepend 🌈

$srcfnd->prepend(path => $include_file);

This is similar to append, but prepends the path to the todo list. In other words, the current wildcard operation is interrupted to serve the new path, then the previous wildcard operation is resumed when this is exhausted. cutting the line, but make it a documented feature. 👑

---

⭐ next ⭐

while (my $core = $foo->next) {
    unlink $core;
}
my ($src,$obj,$hdr) = @{$srcfnd->next};

The next method is an iterator, which returns successive files. Returns matching files if there was no derive option passed to new. If there was a derive option, returns an arrayref containing the matching filespec and all derived filespecs. The derived filespecs do not have to exist. (we're manifesting them, basically ✨)

Note that next maintains an internal cursor, which retains context and state information. Beware if the contents of directories are changing while you are iterating with next; you may get unpredictable results. If you are intending to change the contents of the directories you are scanning (with unlink or rename), you are better off deferring this operation until you have processed the whole tree. For the pending delete or rename operations, you could always use another File::Wildcard object — see the spike example below.

---

💜 all 💜

my @cores = $foo->all;

all returns an array of matching files, in the simple case. Returns an array of arrays if you are constructing new filenames, like the $srcfnd example. 🎀

Beware of the performance and memory implications of using all. The method will not return until it has read the entire directory tree. Use of the all method is not recommended for traversing large directory trees and whole file systems. Consider coding the traversal using the iterator next instead. this one will absolutely eat your RAM for breakfast, no cap. 💀

---

🍓 reset 🍓

reset causes the wildcard context to be set to re-read the first filename again. Note that this will cause directory contents to be re-read. fresh start, clean slate, new era. ✨

Note also that this will cause the path to revert to the original path specified to new. Any additional paths appended or prepended will be forgotten. sorry to those paths, they were simply not invited back. 🙈

---

💅 close 💅

Release all directory handles associated with the File::Wildcard object. An object that has been closed will be garbage collected once it goes out of scope. Wildcards that have been exhausted are automatically closed (i.e. all was used, or next returned undef).

Subsequent calls to next will return undef. It is possible to call reset after close on the same File::Wildcard object, which will cause it to be reopened. closing and reopening the same object? that's range, bestie. 👑

🌈 EXAMPLES 🌈

Bestie, let's see this thing in action. Two little vignettes, both iconic:

💖 The spike 💖

my $todo = File::Wildcard->new;

...

$todo->append(path => $file);

...

while (my $file = $todo->next) {
...
}

Okay so the tea here is: you can hand it an empty wildcard and use it as a lil storage box for a list of filenames you wanna deal with later. 🎀

And the order you'll see them in? That depends entirely on whether you used append or prepend. Choose wisely, queen. 👑

---

🐚 Shell style globbing 🐚

my $wc_args = File::Wildcard->new;

$wc_args->append(path => $_) for @ARGV;

while ($wc_args->next) {
...
}

Real talk: on Unix, file wildcards sitting on the command line get globbed by the shell before perl even lays eyes on them — unless those wildcards are escaped or quoted. 🙈

That is not how it goes on other operating systems, just so you know. MS-DOS, for example, does literally no globbing at all. None. Zero. 💀

But here's the slay: File::Wildcard gives you the bonus of elliptic globbing with '///'. Yes bestie, that's the good stuff. ✨

---

🚨 CAVEAT 🚨

This module takes POSIX filenames, which means forward slash '/' as the path separator. Every operating system that runs Perl can handle that kind of path, so we're good. 🫶

But — and this is important — the module is not designed to work with native file specs. So if you want your code to be portable, convert your native filespecs into the POSIX form first. 💅

On Unix platforms there's of course no difference at all. Chill. 🌸

---

🐛 BUGS 🐛

Found a bug? Please report it to http://rt.cpan.org — the maintainers wanna hear from you, fr fr. 📮

---

👑 AUTHOR 👑

Ivor Williams
ivorw-file-wildcard010 at xemaps.com

---

📜 COPYRIGHT 📜

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

The full text of the license can be found in the LICENSE file included with this module.

---

🦋 SEE ALSO 🦋

• glob(3)
• File::Find
• File::Find::Rule

---

Okay that's the whole page, bestie!! 💖 This was File::Wildcard(3pm) from perl v5.36.0, dated 2022-12-12 — go forth and glob, you absolute icon. 🌟