=head1 NAME

STEVEB::Dist::Mgr - My distribution development cycle toolkit

=head1 DESCRIPTION

This distribution is for my personal development cycle. At this time, is relies
on using <c>module-starter</c> for initial distribution creation, Github for
repository and bugtracker, and the L<ExtUtils::MakeMaker> build system, which
utilizes C<Makefile.PL> files.

=head1 SYNOPSIS

    use STEVEB::Dist::Mgr qw(:all)

    my $results = bump_version('2.02');

    my $file_versions = get_version_info();

=head1 EXPORT_OK

We do not automatically import anything into your namespace, you must request
functionality explicitly. Available functions are:

    # Makefile.PL functions

    add_bugtracker
    add_repository

    # Module file functions

    bump_version
    get_version_info

    # CI functions

    ci_github
    ci_badges

NOTE: You can auto import everything at once by specifying the C<:all> tag.

=head1 FUNCTIONS

=head2 add_bugtracker

Adds bugtracker information to the C<Makefile.PL> file. If the required
C<META_MERGE> section doesn't exist, we'll create it.

Currently, only Github is supported.

I<Parameters>:

    $author

I<Mandatory, String>: The Github username of the software author. For example,
mine is C<stevieb9>.

    $repository

I<Mandatory, String>: The name of the repository. For example, the repository
name for this distribution is C<steveb-dist-mgr>.

    $makefile

I<Optional, String>: The path and name of the C<Makefile.PL> file to use. We
default to C<./Makefile.PL>.

I<Returns>: C<0> upon success.

=head2 add_repository

Adds repository information to the C<Makefile.PL> file. If the required
C<META_MERGE> section doesn't exist, we'll create it.

Currently, only Github is supported.

I<Parameters>:

    $author

I<Mandatory, String>: The Github username of the software author. For example,
mine is C<stevieb9>.

    $repository

I<Mandatory, String>: The name of the repository. For example, the repository
name for this distribution is C<steveb-dist-mgr>.

    $makefile

I<Optional, String>: The path and name of the C<Makefile.PL> file to use. We
default to C<./Makefile.PL>.

I<Returns>: C<0> upon success.

=head2 bump_version

Finds and updates the version number of a Perl module file, or all Perl
module files in a directory structure.

I<Parameters>:

    $version

I<Mandatory, String>: The new version to update to.

=head3 Dry run mode

The C<$version> parameter can be prepended with an optional dash (C<->), and if
so, we'll operate in "dry-run" mode, where we'll return the results, but won't
have written to any files. Eg: C<bump_version('-1.01')>.

    $fs_entry

I<Optional, String>: The directory or file to operate on. If a directory is
sent in, we'll iterate over all files in all directories recursively.

I<Default>: C<lib/>

I<Returns>: An HoH:

    $VAR1 = {
        't/data/work/Two.pm' => {
            'dry_run'   => 0,
            'from'      => '2.66',
            'to'        => '2.67',
            'content'   => '' # Module file code (snipped for brevity)
        },
        't/data/work/One.pm' => {
            'dry_run'   => 0,
            'from'      => '2.66',
            'to'        => '2.67',
            'content'   => '' # Module file code (snipped for brevity)
        },
    };

=head2 get_version_info

Fetches the file version information of Perl module files. Can operate on a
single file, or iterate over a directory structure.

I<Parameters>:

    $fs_entry

I<Optional, String>: The directory or file to operate on. If a directory is
sent in, we'll iterate over all files in all directories recursively.

I<Default>: C<lib/>

I<Returns>: Hash reference:

    $VAR1 = {
        't/data/orig/One.pm'    => '2.66'
        't/data/orig/Two.pm'    => '2.66',
        't/data/orig/Three.pm'  => '2.66',
        't/data/orig/Bad.pm'    => undef,   # $VERSION can't be parsed
        't/data/orig/No.pm'     => undef,   # No $VERSION defined
    };

=head2 ci_github

Installs a Github Actions configuration file into C<.github/workflows>. We'll
create the directory if it doesn't exist.

I<Parameters>:

    $os

I<Optional, Array Reference>: A list of the Operating Systems you want to run
your tests on.

I<Valid values>: C<l>, C<w>, C<m>, where:

    l == Linux (Ubuntu to be specific)
    w == Windows
    m == MacOS

I<Returns>: An array of the contents of the generated file.

=head2 ci_badges

Inserts various CI and coverage badges into module files.

I<Parameters>:

    $author

I<Mandatory, String>: The repository owner (eg. mine is 'stevieb9').

    $repository

I<Mandatory, String>: The name of the repository (eg. this one is
'steveb-dist-mgr').

    $fs_entry

I<Optional, String>: The path and name of a Perl module file, or a directory
that contains Perl module files. If a directory is sent in, we'll operate
recursively.

I<Returns>: C<0> upon success.

=head2 manifest_skip

Generates a C<MANIFEST.SKIP> file.

I<Parameters>:

    $directory

I<Optional, String>: The directory where we'll create the file. If not
specified, we'll create it in the current directory, C<.>.

=head1 AUTHOR

Steve Bertrand, C<< <steveb at cpan.org> >>

=head1 LICENSE AND COPYRIGHT

Copyright 2020 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). You may obtain a
copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>

=head1 AUTHOR

Steve Bertrand, C<< <steveb at cpan.org> >>

=head1 LICENSE AND COPYRIGHT

Copyright 2020 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). You may obtain a
copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>