view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

=encoding utf-8

=head1 NAME

ful - a useI<ful> "B<f>ind B<u>pper B<l>ib" pragma that ascends dirs to include
module directories in C<@INC>.

=head1 SYNOPSIS

=begin HTML

<span>
    <a href="https://badge.fury.io/pl/Acme-ful">
        <img src="https://badge.fury.io/pl/Acme-ful.svg" alt="CPAN Current Version" height="18">
    </a>
    <a href="https://cpants.cpanauthors.org/release/RWILLIS/Acme-ful-0.11">
        <img src="https://cpants.cpanauthors.org/release/RWILLIS/Acme-ful-0.11.svg" alt="CPAN Module Quality" />
    </a>
    <a href="https://travis-ci.org/github/ryan-willis/ful.pm">
        <img src="https://travis-ci.org/ryan-willis/ful.pm.svg?branch=master" alt="Build Status" />
    </a>
    <a href="https://coveralls.io/github/ryan-willis/ful.pm?branch=master">
        <img src="https://coveralls.io/repos/github/ryan-willis/ful.pm/badge.svg?branch=master" alt="Coverage Status" />
    </a>
</span>

=end HTML

One line to rule them all.

    use ful;

Brings the first C<lib/> directory found by directory ascencion and adds it to
C<@INC>.

Instead of:

    use lib::relative '../../lib';
    # or
    use FindBin;
    use lib "$FindBin::Bin/../lib";
    # or even
    BEGIN {
        use Path::Tiny;
        my $base = path(__FILE__)->parent;
        $base = $base->parent until -d "$base/lib" or $base->is_rootdir;
        unshift @INC, "$base/lib";
    }

=head1 USAGE

When you're working within C<a-script.pl> when your project looks like this:

    project-root/
    ├── bin/
    │   └── utils/
    │       └── a-script.pl
    ├── lib/
    │   └── Some/
    │       └── Module.pm
    ├── vendor/
    │   └── SomeOrg/
    │       └── Some/
    │           └── Module.pm

Just drop the line before your other C<use> statements:

    use ful;
    use Some::Module;

And that's all.

If you need more than just the C<project-root/lib> dir, you can do this:

    use ful qw/vendor lib/;
    use Some::Module;
    use SomeOrg::Some::Module;

=head1 METHODS

=over 4

=item * crum()

Returns the parent directory for the latest addition to C<@INC>.

=back

=head1 ADVANCED

    use ful \%options;

=head2 OPTIONS

=over 4

=item * C<libdirs =E<gt> \@dirs>

Equivalent to C<use ful qw/lib vendor/;> but can be combined with all other
options.