view release on metacpan or  search on metacpan

lib/App/distfind.pm  view on Meta::CPAN

=for stopwords dirs

=for test_synopsis 1;
__END__

=head1 NAME

App::distfind - Find Perl module distributions within a directory hierarchy

=head1 VERSION

version 1.101400

=head1 SYNOPSIS

    $ distfind
    path/to/My-Dist path/to/My-Other-Dist

    $ distfind --dir foo --dir bar --prune deprecated --line
    foo/some/path/My-Dist
    foo/some/other/path/My-Other-Dist
    bar/yet/another/path/My-Shiny

    $ distfind --dir baz --print-roots
    baz

    $ distfind --print-path Foo-Bar --prefix "ls -al "
    ls -al path/to/Foo-Bar

To be able to run programs from within your development directories without
having to install the distributions, add this to your C<.bashrc>:

    for i in $(distfind)
    do
        if [ -d $i/bin ]; then
            PATH=$i/bin:$PATH
        fi
    done

=head1 DESCRIPTION

C<distfind> can find Perl module distributions in a directory hierarchy. A
Perl distribution in this sense is defined as a directory that contains a
C<Makefile.PL>, C<Build.PL> or C<dist.ini> file.

=head1 FUNCTIONS

=head2 run

The main function, which is called by the C<distfind> program.

=head2 normalize_dirs

This function takes a reference to an array of directory specifications. It
then normalizes them by splitting them along colon or semicolon characters and
filters out duplicates. Tilde characters will be expanded to C<$ENV{HOME}>.
The returning list is returned as an array reference.

=head2 find_dists

Traverses the given directories, looks for Perl module distributions, and
returns a list of paths to those distribution directories. See C<--prune> for
directories that will be pruned. Also if a Perl module distribution directory
is found, it is then pruned because we assume that it won't recursively
contain another Perl module distribution.

=head1 OPTIONS

Options can be shortened according to L<Getopt::Long/"Case and
abbreviations">.

=over

=item C<--dir>

This option takes a string argument and can be given several times. Specifies
a directory that should be searched for Perl module distributions. If no
directories are specified, the value of C<$ENV{PROJROOT}> is added by default.

=item C<--prune>

This option takes a string argument and can be given several times. If a
directory with this name is encountered, it will be pruned.

By default, the following directories are pruned: C<.svn>, C<.git>, C<blib>
and C<skel>.

=item C<--print-roots>

This option causes the directories that would be searched to be printed,
without actually searching them. The C<--join> option is used, if given.
See C<--dir> on how this could be different from the options you gave at
the command-line.

=item C<--print-path>

This option takes a string argument and can be given several times. It has the
effect of restricting what will be printed to the given distribution names.
For example:

    $ distfind --print-path Foo-Bar --print-path Baz

will only print paths to those distributions:

    path/to/Foo-Bar path/to/Baz

=item C<--prefix>

This option takes a string argument. If given, every distribution path will be
prefixed with this string as it is printed.

=item C<--suffix>

This option takes a string argument. If given, every distribution path will be
suffixed with this string as it is printed.

=item C<--join>

This option takes a string argument. When printing distribution paths, they
will be separated by this string. It defaults to a single space character.