NAME

Path::Tiny::Glob - File globbing utility

VERSION

version 0.2.0

SYNOPSIS

    use Path::Tiny::Glob;

    my $dzil_files = pathglob( '~/work/perl-modules/**/dist.ini' );

    while( my $file = $dzil_files->next ) {
        say "found a Dist::Zilla project at ", $file->parent;
    }

DESCRIPTION

This module exports a single function by default, pathglob.

EXPORTED FUNCTIONS

pathglob

    $list = pathglob( $glob );
    $list = pathglob( \@path_segments );

This function takes in a shell-like file glob, and returns a Lazy::List of Path::Tiny objects matching it.

If you prefer to get all the globbed files in one go instead of Lazy::Listed, you can import pathglob with the flag all:

    use Path::Tiny::Glob pathglob => { all => 1 };

    # now behaves like pathglob( '/foo/**' )->all;
    my @files = pathglob( '/foo/**' );

The function can also take an arrayref of path segments. The segments can be strings, in which case they are obeying the same globbing patterns as the stringy $glob.

    $list = pathglob( [ 'foo', 'bar', '*', 'README.md' ] );

    # equivalent to

    $list = pathglob( 'foo/bar/*/README.md' );

The segments, however, can also be coderefs, which will be passed Path::Tiny objects both as their argument and as $_, and are expected to return true if the path is matching.

    $big_files = pathglob( [ 'foo/bar/**/', sub { -f $_ and -s $_ > 1E6 } );

The segments can also be regexes, in which case they will be compared to the paths' current basename.

    @readmes = pathglob( [ 'foo/bar/**/', /^readme\.(md|mkd|txt)$/i );

Known limitation: backtracking paths using .. doesn't work.

Supported globbing patterns

*

Matches zero or more characters.

?

Matches zero or one character.

**

Matches zero or more directories.

If ** is the last segment of the path, it'll return all descendent files.

is_globby

    my $globby = is_globby( './foo/*/bar' );

Returns true if the argument contains any glob character (so ? or *). Can be useful to determine if the input was an explicit path or a glob.

Not exported by default.

SEE ALSO

File::Wildcard

AUTHOR

Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2018 by Yanick Champoux.

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