App-podweaver

 view release on metacpan or  search on metacpan

lib/App/podweaver.pm  view on Meta::CPAN

our $VERSION = '1.00';

sub FAIL()              { 0; }
sub SUCCESS_UNCHANGED() { 1; }
sub SUCCESS_CHANGED()   { 2; }

sub weave_file
{
    my ( $self, %input ) = @_;
    my ( $file, $no_backup, $write_to_dot_new, $weaver );
    my ( $perl, $ppi_document, $pod_after_end, @pod_tokens, $pod_str,
         $pod_document, %weave_args, $new_pod, $end, $new_perl,
         $output_file, $backup_file, $fh, $module_info );

    unless( $file = delete $input{ filename } )
    {
        $log->errorf( 'Missing file parameter in args %s', \%input )
            if $log->is_error();
        return( FAIL );
    }
    unless( $weaver = delete $input{ weaver } )
    {
        $log->errorf( 'Missing weaver parameter in args %s', \%input )
            if $log->is_error();
        return( FAIL );
    }
    $no_backup        = delete $input{ no_backup };
    $write_to_dot_new = delete $input{ new };

    #  From here and below is mostly hacked out from
    #    Dist::Zilla::Plugin::PodWeaver

    $perl = File::Slurp::read_file( $file );

    unless( $ppi_document = PPI::Document->new( \$perl ) )
    {
        $log->errorf( "PPI error in '%s': %s", $file, PPI::Document->errstr() )

lib/App/podweaver.pm  view on Meta::CPAN

    }

    if( $perl eq $new_perl )
    {
        $log->infof( "Contents of '%s' unchanged", $file )
            if $log->is_info();
        return( SUCCESS_UNCHANGED );
    }

    $output_file = $write_to_dot_new ? ( $file . '.new' ) : $file;
    $backup_file = $file . '.bak';

    unless( $write_to_dot_new or $no_backup )
    {
        unlink( $backup_file );
        copy( $file, $backup_file );
    }

    $log->debugf( "Writing new '%s' for '%s'", $output_file, $file )
        if $log->is_debug();
    #  We want to preserve permissions and other stuff, so we open
    #  it for read/write.
    $fh = IO::File->new( $output_file, $write_to_dot_new ? '>' : '+<' );
    unless( $fh )
    {
        $log->errorf( "Unable to write to '%s' for '%s': %s",

lib/App/podweaver.pm  view on Meta::CPAN

=over

=item B<< filename => >> I<$filename> (required)

The filename of the file to weave.

=item B<< weaver => >> I<$weaver> (required)

The L<Pod::Weaver> instance to use for the weaving.

=item B<< no_backup => >> I<0> | I<1> (default: 0)

If set to a true value, no backup will be made of the original file.

=item B<< new => >> I<0> | I<1> (default: 0)

If set to a true value, the modified file will be written to the
original filename with C<.new> appended, rather than overwriting
the original.

=item B<< dist_version => >> I<$version>

If no C<$VERSION> can be parsed from the file by

script/podweaver  view on Meta::CPAN

our $VERSION = '1.00';

# ---------------------------------------------------------------------------

my $help    = 0;
my $man     = 0;
my $version = 0;

my %options = (
    new       => 0,
    no_backup => 0,
    antispam  => '',
    verbose   => 0,
    );

if( my $config = App::podweaver->config() )
{
    foreach my $option ( keys( %{$config->{ _ }} ) )
    {
        if( exists( $options{ $option } ) )
        {

script/podweaver  view on Meta::CPAN

    }
}

Getopt::Long::Configure( 'gnu_getopt' );
Getopt::Long::GetOptions(
    'help|?|h'                => \$help,
    'man'                     => \$man,
    'version'                 => \$version,
    'verbose|v+'              => \$options{ verbose },
    'new'                     => \$options{ new },
    'no_backup|nobackup'      => \$options{ no_backup },
    'antispam=s'              => \$options{ antispam },
    ) or pod2usage( 2 );

pod2usage( 1 ) if $help;
pod2usage( -exitstatus => 0, -verbose => 2 ) if $man;

if( $version )
{
    print "podweaver, version $VERSION\n\n",
        "Config file: ", App::podweaver->_config_file(), "\n";

script/podweaver  view on Meta::CPAN

version 1.00

=head1 SYNOPSIS

podweaver [options]

 Options:
   -v, --verbose     increase verbosity
   --new             write to *.new files rather than overwriting existing
   --no_backup       skip generating *.bak files when editing files
   --antispam=str    replace @ in author emails with 'str'.
   --help            brief help message
   --man             full documentation
   --version         display version information and exit

=head1 OPTIONS

=over 8

=item B<--new>

Write the modified version of a file to a new file based on the original
filename with a C<.new> extension, rather than the default behaviour of
overwriting the original.

When B<--new> is supplied, no *.bak backup of the original is created (since
the original is left untouched.)

=item B<--no_backup>

Skips the production of *.bak backups for any changed files.
Be warned, this could result in loss of the file contents if anything goes
wrong, use with caution. (Or better still, use with your changes safely
commited to the VCS of your choice.)

=item B<--antispam=>I<string>

Replaces the @ in author email addresses with the supplied string as an
anti-spam measure.
Given that the original email is still within the META.yml, this will not
prevent all spam harvesting, but it may at least help.

script/podweaver  view on Meta::CPAN

=item B<--version>

Prints version information and the location of the config file and
exits.

=back

=head1 DESCRIPTION

L<podweaver> will run L<Pod::Weaver> across all files in a distribution,
editing them in place and leaving a backup of the original in
I<original>.bak.

This was designed to run with the
L<Pod::Weaver::PluginBundle::ReplaceBoilerplate> plugin, so you can
run L<podweaver> as part of your release process to update the boilerplate
and other automatically generated POD in your source files, rather than
the default L<Pod::Weaver> behaviour of appending.

To use L<podweaver> it is suggested you place a C<weaver.ini> file in
the root of your distribution with contents similar to:

script/podweaver  view on Meta::CPAN

UNIX-based operating systems, and
C<~/Local Settings/Application Data/App-podweaver/podweaver.ini> under Windows.

You can find the exact location of your configuration file using
the B<--version> option.

The configuration file follows L<Config::Tiny> style .ini format and
consists of command-line option names for keys, for example:

  antispam  = BLAHBLAH
  no_backup = 1
  verbose   = 2

This would be as if you provided C<< --antispam=BLAHBLAH --no_baackup -vv >>
on the command-line.

Any options supplied on the command-line will override those supplied
within the configuration file.

=head1 SEE ALSO

t/30-weave-file.t  view on Meta::CPAN

                do { local $/; open my $fh, '<', $woven_file;    <$fh> };
            eq_or_diff( $woven, $expected,
                "$test_name produces correct output" );

        }
    }
}

#  TODO: test new => 1
#  TODO: test new default
#  TODO: test no_backup => 1
#  TODO: test no_backup default