view release on metacpan or  search on metacpan

lib/Dist/Zilla/Util/SimpleMunge.pm  view on Meta::CPAN

Dist::Zilla::Util::SimpleMunge - Make munging File::FromCode and File::InMemory easier.

=head1 VERSION

version 1.000002

=head1 SYNOPSIS

  use Dist::Zilla::Util::SimpleMunge qw( auto_munge_file );
  ...;

  sub somesub {
    ...;

    next if $file->is_bytes;

    if ( $file->can('code') ) {

    auto_munge_file $file_from_zilla, sub {
        my ( $file, $content , $encoding ) = @_;
        return $mangled if $encoding ne 'text'; # bytes or text
        ... mangle $content here ...;
        return $mangled;
    };
  }

=head1 DESCRIPTION

=head2 NOTE: STOPGAP

This module is mostly a stopgap and a implementation experiment in lieu of something better in Dist::Zilla eventually transpiring.

=head2 BASIC USAGE

Munging files in Dist::Zilla can be a pain.

Its mostly the same:

  $file->content( substr( $file->content, 0, 10 ) ); # etc.

Except when you come to C<CodeRef>s, that all changes.

  my $orig_code = $file->code();
  $file->code( sub {
      $file->$orig_code() =~ s/foo/bar/
  });

Which quickly gets messy.

So this module is as simple as I think I can get it without hacking Dist::Zilla directly.

  auto_munge_file $file, sub {
     my ( $thefile, $content, $encoding ) = @_;
  };

The callback will be called as appropriate.

=over 4

=item * C<$content> will contain the content, I<decoded if possible>

=item * C<$encoding> will be either C<text> or C<bytes>, the latter if decoding is not possible.

=item * C<InMemory> will apply the code immediately

=item * C<FromCode> will take your code and create a chained system so your code will be evaluated when the file itself is written out.

=back

And this is the most useful and straight forward interface that doesn't invoke any weird re-blessing magic.

=head2 ADVANCED USAGE

There are a few less simple utilities that may also prove useful.

=over 4

=item * L<< C<munge_InMemory>|/munge_InMemory >> - trusts you know what you're dealing with and munges an C<InMemory> instance via the callback.

=item * L<< C<munge_FromCode>|/munge_FromCode >> - trusts you when you say you have a C<FromCode>, and munges with C<CodeRef> chaining.

=item * L<< C<inplace_replace>|/inplace_replace >> - A bit of magic to replace an object in-place without modifying any containers that point to it and without changing the reference address.

=item * L<< C<to_InMemory>|/to_InMemory >> - returns a C<FromCode> represented as a new C<InMemory> object.

=item * L<< C<to_FromCode>|/to_FromCode >> - returns an C<InMemory> represented as a new C<FromCode> object.

=item * L<< C<inplace_to_InMemory>|/inplace_to_InMemory >> - like C<to_InMemory>, but replaces the object in-place.

=item * L<< C<inplace_to_FromCode>|/inplace_to_FromCode >> - like C<to_FromCode>, but replaces the object in-place.

=item * L<< C<munge_file>|/munge_file >> - combines all of the above behaviors based on configuration values.

=item * L<< C<munge_files>|/munge_files >> - applies a single configuration and callback to a collection of files.

=back

=head1 FUNCTIONS

=head2 C<auto_munge_file>

  # auto_munge_file ( $FILE, $CODEREF )

  auto_munge_file( $zilla_file, sub {
      my ( $file, $content, $encoding ) = @_;
      return $new_content # must still be in form $encoding
  });

=head2 C<to_InMemory>

Given a C<FromCode>, return an equivalent C<InMemory> file, flattening the callback
in the process into simply a string.

  my $in_memory = to_InMemory( $from_code );

=head2 C<to_FromCode>

Given a C<InMemory> or C<OnDisk>, return an equivalent C<FromCode> file, converting the content into a callback that yields that content.

  my $from_code = to_FromCode( $in_memory_or_from_disk );