NAME

Module::Husbandry - build and manage perl modules in a Perl module distribution

SYNOPSIS

DESCRIPTION

FUNCTION

parse_module_specs

    my @specs = parse_module_specs @ARGV, \%options;

Parses a module specification, one of:

    Foo
    Foo::Bar
    lib/Foo.pm
    lib/Foo/Bar.pm
    lib/Foo/Bar.pod

and returns the package name (Foo::Bar) and the path to the file (lib/Foo/Bar.pm) for each parameter in a hash. The result HASHes look like:

    {
         Filename       => "lib/Foo/Bar.pm",
         Package        => "Foo::Bar",
         Spec           => $spec,   ## What was passed in
    };

Any name containing characters other that A-Z, 0-9, :, or ' are assumed to be filenames. Filenames should begin with lib/ (or LIB/ on Win32) or will be warned about.

The only option provided is:

    as_dir    Set this to 1 to suppress the add "/" instead of ".pm"
              the Filename when a module name is converted to a filename.
              Does not affect anything when a filename is parsed.  This
              is used by mvpm's recurse option.

parse_bin_specs

    my @specs = parse_bin_specs @ARGV, \%options;

Parses specifications for a "bin" program, like:

    foo
    bin/foo

and returns the program name (foo) and the path to the file (bin/foo) for each parameter in a hash. The result HASHes look like:

    {
         Filename       => "bin/foo",
         Program        => "foo",
         Spec           => $spec,   ## What was passed in
    };

If a spec has no directory separators, "bin/" is prepended. If a spec has directory separator, no "bin/" is prepended.

parse_dist_specs

Takes a list of distributions specs (Foo::Bar, Foo-Bar) and returns a hash like

    {
        Package => "Foo::Bar",
        Spec    => $spec,
    }

reconfigure_dist

Runs perl Makefile.PL using the current Perl.

TODO: Support Module::Build methodology.

add_to_MANIFEST

    add_to_MANIFEST "foo", "bar";

Adds one or more files to the MANIFEST.

rm_from_MANIFEST

    rm_from_MANIFEST "foo", "bar";

Remove one or more files to the MANIFEST.

install_file

    install_file $from_file_hash, $to_file_hash, \%macros;

Locates the approptiate file in the .newpm directory and copies it, instantiating any <%macros%> needed.

Reads <%meta foo bar %> and <%meta foo=bar %> tags.

    Meta tags
    =========
    <%meta chmod 0755 %>    chmod the resulting file (numeric only)

Any unrecognized meta or macro tags are ignored with a warning.

Adds file to MANIFEST.

TODO: adapt to Module::Build's manifesting procedures.

templates_for

    my @from_files = templates_for @to_files;

Given a list of files to write to, find the appropriate source files.

test_scripts_for

    my @test_scripts = test_scripts_for @modules;

Returns test scripts for any .pm and .pl file in @modules:

    {
        Filename => "t/Foo.t",
    }

where @modules is an array of HASHes returned by parse_module_specs.

skeleton_files

    my %skel_map = skeleton_files $target_dir;

Returns a list of from/to files to install from the skeleton directory.

cppm

    cppm $from, $to, \%options

Copies a file in a distribution and a related test suite (if found).

TODO: Don't rewrite changelogs. Not sure how best to recognize them; this could be an option for the mythical .newpmrc.

TODO: Make the filename substitutions patterns case insensitive on Win32?

newpm

Create new modules in ./lib/... and, if it's a .pm module, a test suite in ./t/...

Does not build the make file.

newpmbin

Create new script files in bin/. Does not add a test script (since there's no safe way to test an arbitrary program).

newpmdist

Create a new distribution in . and populate it from the skeleton files. newpm() a new module.

mvpm

    mvpm $from, $to, \%options

Changes the name of a file in a distribution and all occurences of the file's name (and, if applicable, package name) in it and in all other files.

A backup of any files changed is placed in .newpm/bak_0000 (where 0000 increments each time).

TODO: some kind of locking so simultaneous mvpms don't happen to choose the same backup directory name.

TODO: Don't rewrite changelogs. Not sure how best to recognize them; this could be an option for the mythical .newpmrc.

TODO: Make the filename substitutions patterns case insensitive on Win32?

rmpm

Removes any modules and tests named after a package (or module) name.

Warns about any other files that refer to the doomed package.

A backup is made in the backup directory (.mvpm/... for now, will change)..

TODO: Allow a site-specific rm command to be used, like 'trash', so this command may be better integrated with a user's working environment. This will wait until we restructure the directories.

usage

parse_cli

    my ( $options, @params ) = parse_options @ARGV, \%spec;

Reads the command line and parses out the options and other parameters. Options may be intermixed with parameters.

Options -h|-?|--help and -- do the normal things always.

-n|--describe print out what *would* happen, but do nothing.

LIMITATIONS

ASSumes a dir tree and file naming conventions like:

    Foo-Bar/
        Makefile.PL
        ...
        lib/Foo/Bar.pm
        t/Foo-Bar.pm

This probably won't work out all that well for XS distributions, not sure how they work. Let me know and we'll see if we can add it :)

Not tested on Win32.

Does not know about Module::Build.

Does not use anything like a .newpmrc file.

COPYRIGHT

    Copyright 2002, R. Barrie Slaymaker, Jr., All Rights Reserved

LICENSE

You may use this module under the terms of the BSD, Artistic, oir GPL licenses, any version.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>