=pod

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

=encoding utf8

=head1 NAME

perl5 - Use a Perl 5 group of modules/features

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

=head1 SYNOPSIS

Use a version of Perl and its feature set:

    use perl5;      # Same as 'use perl5 v5.10.0;'
    use perl5 v14.1;
    use perl5 14.1;
    use perl5-14.1;

Use a bundled feature set from a C<perl5> plugin:

    use perl5-i;
    use perl5-2i;
    use perl5-modern;
    use perl5-yourShinyPlugin;

Or both:

    use perl5 v14.1 -shiny;

=head1 DESCRIPTION

The C<perl5> module lets you C<use> a well known set of modules in one
command.

It allows people to create plugins like C<perl5::foo> and C<perl5::bar> that
are sets of useful modules that have been tested together and are known to
create joy.

This module, C<perl5>, is generally the base class to such a plugin.

=head1 USAGE

This:

    use perl5-foo;

Is equivalent in Perl to:

    use perl5 '-foo';

The C<perl5> module takes the first argument in the C<use> command, and uses
it to find a plugin, like C<perl5::foo> in this case.

C<perl5::foo> is typically just a subclass of L<perl5>. It invokes a set of
modules for its caller.

If you use it with a version, like this:

    use perl5 v14;

It is the same as saying:

    use v5.14;
    use strict;
    use warnings;
    use feature ':5.14';

If you use C<perl5> with no arguments, like this:

    use perl5;

It is the same as saying:

    use perl5 v10;

=head1 PLUGIN API

This module uses lexically-wrapped-goto-chaining-magic to correctly load a set
of modules (including optional version requirements and import options) into
the user's code. The API for specifying a perl5 plugin is very simple.

To create a plugin called C<perl5::foo> that gets called like this:

    use perl5-foo;

Write some code like this:

    package perl5::foo;
    use base 'perl5';
    our $VERSION = 0.12;

    # These is the list of modules (with optional version and arguments)
    sub imports {
        return (
            strict =>
            warnings =>
            features => [':5.10'],
            SomeModule => 0.22,
            OtherModule => 0.33, [option1 => 2],
            Module => [],   # Don't invoke Module's import() method
        );
    }

    1;

=head1 INSPIRATION

This module was inspired by Michael Schwern's L<perl5i>, and the talk he gave
about it at the 2010 OSDC in Melbourne. By "inspired" I mean that I was
perturbed by Schwern's non-TMTOWTDI attitude towards choosing a standard set
of Perl modules for all of us.

B<THIS IS PERL! THERE ARE NO STANDARDS!>

...and I told him so. I also promised that I would show him my feelings in
code. Schwern, I<this> is how I feel! (See also: L<perl5::i>)

=head1 THANKS

Special thanks to schwern, mstrout, audreyt, rodrigo and jesse for ideas
and support.

=head1 AUTHOR

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

=head1 COPYRIGHT

Copyright 2011-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