view release on metacpan or  search on metacpan

lib/Module/Starter.pm  view on Meta::CPAN

package Module::Starter;

use warnings;
use strict;
use Carp qw( croak );
use Module::Runtime qw( require_module );

=head1 NAME

Module::Starter - a simple starter kit for any module

=head1 VERSION

version 1.82

=cut

our $VERSION = '1.82';

=head1 SYNOPSIS

Nothing in here is meant for public consumption.  Use L<module-starter>
from the command line.

    module-starter --module=Foo::Bar,Foo::Bat \
        --author="Andy Lester <andy@petdance.com>"

=head1 DESCRIPTION

This is the core module for Module::Starter.  If you're not looking to extend
or alter the behavior of this module, you probably want to look at
L<module-starter> instead.

Module::Starter is used to create a skeletal CPAN distribution, including basic
builder scripts, tests, documentation, and module code.  This is done through
just one method, C<create_distro>.

=head1 METHODS

=head2 Module::Starter->create_distro(%args)

C<create_distro> is the only method you should need to use from outside this
module; all the other methods are called internally by this one.

This method creates orchestrates all the work; it creates distribution and
populates it with the all the requires files.

It takes a hash of params, as follows:

    distro       => $distroname,      # distribution name (defaults to first module)
    modules      => [ module names ], # modules to create in distro
    dir          => $dirname,         # directory in which to build distro
    builder      => 'Module::Build',  # defaults to ExtUtils::MakeMaker
                                      # or specify more than one builder in an
                                      # arrayref

    license      => $license,    # type of license; defaults to 'artistic2'
    author       => [ authors ], # author(s) name and email address
                                 # (if not provided, name and email are taken from getpwuid and
                                 # EMAIL respectively)
                                 # format: Author Name <author-email@domain.tld>
    github       => $username,   # author's GitHub user name (for creating links to issue tracker)
    ignores_type => $type,       # ignores file type ('generic', 'cvs', 'git', 'hg', 'manifest')
    fatalize     => $fatalize,   # generate code that makes warnings fatal

    verbose      => $verbose,    # bool: print progress messages; defaults to 0
    force        => $force       # bool: overwrite existing files; defaults to 0

The ignores_type is a new feature that allows one to create SCM-specific ignore files.
These are the mappings:

    ignores_type => 'generic'  # default, creates 'ignore.txt'
    ignores_type => 'cvs'      # creates .cvsignore
    ignores_type => 'git'      # creates .gitignore
    ignores_type => 'hg'       # creates .hgignore
    ignores_type => 'manifest' # creates MANIFEST.SKIP

It is also possible to provide an array ref with multiple types wanted:

    ignores_type => [ 'git', 'manifest' ]

=head1 PLUGINS

Module::Starter itself doesn't actually do anything.  It must load plugins that
implement C<create_distro> and other methods.  This is done by the class's C<import>
routine, which accepts a list of plugins to be loaded, in order.

For more information, refer to L<Module::Starter::Plugin>.

=cut

sub import {
    my $class = shift;
    my @plugins = ((@_ ? @_ : 'Module::Starter::Simple'), $class);
    my $parent;

    while (my $child = shift @plugins) {
        require_module $child;

        ## no critic
        no strict 'refs'; #Violates ProhibitNoStrict
        push @{"${child}::ISA"}, $parent if $parent;
        use strict 'refs';
        ## use critic

        if ( @plugins && $child->can('load_plugins') ) {
            $parent->load_plugins(@plugins);
            last;
        }
        $parent = $child;
    }

    return;
}

=head1 AUTHORS

Dan Book, C<< <dbook at cpan.org> >>