=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.31.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

inc - Smart C<@INC> Processing

=for html
<a href="https://travis-ci.org/ingydotnet/inc-pm"><img src="https://travis-ci.org/ingydotnet/inc-pm.png" alt="inc-pm"></a>
<a href="https://coveralls.io/r/ingydotnet/inc-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/inc-pm/badge.png" alt="inc-pm"></a>

=head1 SYNOPSIS

    use inc <smart-object-spec-list>;

or:

    perl -Minc=<smart-object-spec-list> …

or:

    PERL5OPT='-Minc=<smart-object-spec-list>' prove -v t/

=head1 DESCRIPTION

The C<inc> module redefines @INC to a list of predefined I<smart objects>.
These objects are really just code refs for handy lookup techniques. For
example, only finding modules that were core in Perl 5.8.1, or only finding
non-core modules that are declared prerequisites of some module.

A real example is testing a module that you are releasing to CPAN. You can use
this to make sure that only predeclared prerequisite modules get loaded:

    PERL5OPT='-Minc=dist.ini:core=5.8.1:lib' prove -v t/

Each smart object object can have an argument list:

    use inc 'core=5.8.1';

In this example C<core> is the name of the smart object (code ref) and '5.8.1'
is an argument. Multiple arguments are separated by commas.

The list of objects can be a real list or a single string separated by colons.
This is to allow easy usage loading C<inc> using C<-M>:

    perl -Minc=lib:core …

=head1 SMART OBJECTS

This is a list of the smart objects that are predefined by the C<inc> module
(in alpha order):

=over

=item C<blib>

Use the path values that C<blib.pm> would add.

=item C<cache>

Some of the smart objects can take long time to get their information. They
might need to fetch information from the internet, for example. This object
will save all the state into a file called C<./.perl-inc-cache>. You can
override this filename by passing a value of your own as an argument.

If the cache file exists it will be used. If not, values will be stored to it.
To refresh the cache, simply delete the file.

=item C<core>

Only finds the modules that are in core for the version of Perl that is
running. You can give this a Perl version argument, and modules will be
limited to the ones that were core for that version.

=item C<cwd>

Adds the absolute path of the current directory.

=item C<deps>

Only finds modules that are known prereqs of a module. Defaults to the
module from which it was called. You can pass in the names of one or more
modules to use.

=item C<dot>

Adds C<< File::Spec->curdir >>. (Usually C<.>).

=item C<dzil>

Use Dist::Zilla's C<dzil listdeps> to find prereqs. Only find these modules.

=item C<inc>

Expands to the value on C<@INC> prior to the execution of C<use inc …>.

=item C<INC>

Expands to the perl's default @INC.

=item C<LC>

Lancaster Core. Alias for C<core=5.8.1>

=item C<lib>

Expands to an absolute path of C<./lib>.

=item C<meta>

Only find modules listed as prereqs in C<META.json> or C<META.yaml>. Also
finds modules that are prereqs of those modules.

=item C<none>

Use this to set C<@INC> to the empty list. The C<use inc …> statement requires
at least one object, so this is needed to make it empty.

=item C<< not=<regex> >>

Removes paths that match the regex.

=item C<< ok=<regex> >>

If the name of the module being loaded matches the regex, it will be loaded
from the original C<@INC>.

=item C<perl5lib>

Expands to the paths in the PERL5LIB environment variable.

=item C<priv>

Adds C<privlib> and C<archlib> paths from the L<Config> module.

=item C<-priv>

Removes C<privlib> and C<archlib> paths from the L<Config> module.

=item C<show>

This is for debugging. Prints the @INC values that have been assembled so far.

=item C<site>

Adds C<sitelib> and C<sitearch> paths from the L<Config> module.

=item C<-site>

Removes C<sitelib> and C<sitearch> paths from the L<Config> module.

=item C<zild>

Use Zilla::Dist's C<zild listdeps> to find prereqs. Only find these modules.

=item Directory Paths

Any list value containing a '/' in the name, is a real filesystem path. That
means you can do something like:

    use inc 'foo', @INC, 'bar';

=item C<::Foo> (Plugins)

Use the C<inc::Plugin::Foo> module to look for smart objects. Objects will be
searched in plugins first, then C<inc.pm>.

=back

=head1 USE WITHOUT C<USE>

If you just want to get the list of real values the C<inc> would create from a
usage list, do this:

    require inc;
    my @inc = inc->list(<smart-object-spec-list>);

This can be used to have more control and set C<@INC> yourself.

=head1 C<INC> PLUGINS

You can define your own C<inc> plugin by making a module called
C<inc::Plugin::Mine>:

    package inc::Plugin::Mine;
    sub inc_this {
      …
    }

People can use it like this:

    use inc qw'::Mine this=arg1,arg2';

Plugins are searched in the reverse order they are loaded in. For example:

    use inc qw'this ::His that ::Hers other';

The C<this> object will only be looked for in C<inc>. The C<that> object will
be looked for in C<inc::Plugin::His> then C<inc>. The C<that> object will be
looked for in C<inc::Plugin::Hers>, then C<inc::Plugin::His> then C<inc>.

=head1 EXAMPLE USAGES

… coming soon …

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT

Copyright 2014. Ingy döt Net.

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

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
