Dist::Zilla::Util::SimpleMunge - Make munging File::FromCode and File::InMemory easier.
version 1.000002
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; }; }
This module is mostly a stopgap and a implementation experiment in lieu of something better in Dist::Zilla eventually transpiring.
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 CodeRefs, that all changes.
CodeRef
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.
$content will contain the content, decoded if possible
$content
$encoding will be either text or bytes, the latter if decoding is not possible.
$encoding
text
bytes
InMemory will apply the code immediately
InMemory
FromCode will take your code and create a chained system so your code will be evaluated when the file itself is written out.
FromCode
And this is the most useful and straight forward interface that doesn't invoke any weird re-blessing magic.
There are a few less simple utilities that may also prove useful.
munge_InMemory - trusts you know what you're dealing with and munges an InMemory instance via the callback.
munge_InMemory
munge_FromCode - trusts you when you say you have a FromCode, and munges with CodeRef chaining.
munge_FromCode
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.
inplace_replace
to_InMemory - returns a FromCode represented as a new InMemory object.
to_InMemory
to_FromCode - returns an InMemory represented as a new FromCode object.
to_FromCode
inplace_to_InMemory - like to_InMemory, but replaces the object in-place.
inplace_to_InMemory
inplace_to_FromCode - like to_FromCode, but replaces the object in-place.
inplace_to_FromCode
munge_file - combines all of the above behaviors based on configuration values.
munge_file
munge_files - applies a single configuration and callback to a collection of files.
munge_files
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 });
Given a FromCode, return an equivalent InMemory file, flattening the callback in the process into simply a string.
my $in_memory = to_InMemory( $from_code );
Given a InMemory or OnDisk, return an equivalent FromCode file, converting the content into a callback that yields that content.
OnDisk
my $from_code = to_FromCode( $in_memory_or_from_disk );
Munge an InMemory ( or similar ) item using a callback.
munge_InMemory( $xfile, sub { my ( $file, $content, $encoding ) = @_; ... return $content; });
This munging is applied immediately.
Munge a FromCode object by replacing the CodeRef with a new one that yields the former.
munge_FromCode( $xfile, sub { my ( $file, $content, $encoding ) = @_; $content =~ s/foo/bar/; return $content; });
Note: this code is equivalent to:
my $orig_code = $xfile->code; my $encoding = $xfile->core_return_type; $xfile->code( sub { my $content = $xfile->$orig_code(); $content =~ s/a/b/; return $content; });
This is a rather nasty way to replace an Object in place without breaking references held on it.
Consider:
source = ADDR=0x015 = data = { x => y } = class = Foo target = ADDR=0x017 = data = { z => a } = class = Bar array = ADDR=0x016 = data = [ 0x015 ]
Then:
delete source->{x} source->{z} = target->{z} bless source, 'Bar'
This should result in:
source = ADDR=0x015 = data = { z => a } = class = Bar target = ADDR=0x017 = data = { z => a } = class = Bar array = ADDR=0x016 = data = [ 0x015 ]
Yes, this is rather nasty to do this, but no good alternatives at the moment :).
inplace_replace( $original_object, $replacement_object );
This will mirror all the keys from $replacement_object to $original_object, and subsequently ensure $original_object is reblessed into the class of $replacement_object
$replacement_object
$original_object
reblessed
Shorthand for
inplace_replace( $file, to_FromCode($file) );
inplace_replace( $file, to_InMemory($file) );
# munge_file ( $FILE , \%CONFIGURATION ) munge_file( $zilla_file, { via => sub { ... }, lazy => $laziness } );
A ::Role::File object to munge.
::Role::File
{ via => $CODEREF, lazy => $LAZINESS, }
Called to munge the file itself.
Passed a reference to the ::Role::File instance, and a scalar containing the contents of that file.
Return new content for the file via return
return
sub { my ( $file, $content ) = @_ ; ...; return $newcontent; }
Specify how lazy you want the munge to be performed. Normally, what this is set to is dependent on the type of file being munged.
$LAZINESS = undef ; # use default for the file type $LAZINESS = 0 ; # Munge immediately $LAZINESS = 1 ; # Defer munging till as late as possible.
For things that are normally backed by scalar values, such as ::File::OnDisk and ::File::InMemory , the laziness is equivalent to $LAZINESS = 0 , which is not lazy at all, and munges the file content immediately.
::File::OnDisk
::File::InMemory
$LAZINESS = 0
For things backed by code, such as ::File::FromCode , munging defaults to $LAZINESS = 1 , where the actual munging sub you specify is executed as late as possible.
::File::FromCode
$LAZINESS = 1
You can specify the $LAZINESS value explicitly if you want to customize the behavior, i.e.: Make something that is presently a scalar type get munged as late as possible ( converting the file into a FromCode file ), or make something currently backed by code get munged "now", ( converting the file into a InMemory file )
$LAZINESS
This is mostly a convenience utility for munging a lot of files without having to hand-code the looping logic.
It basically just proxies for "munge_file".
# munge_files ( \@FILEARRAY , \%CONFIGURATION ) munge_files( [ $zilla_file_one, $zilla_file_two, ], { via => sub { ... }, lazy => $laziness, });
An ArrayRef of "$FILE"
ArrayRef
"%CONFIGURATION"
"$CODEREF"
"$FILE"
"$LAZINESS"
Kent Fredric <kentnl@cpan.org>
This software is copyright (c) 2017 by Kent Fredric <kentnl@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Dist::Zilla::Util::SimpleMunge, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Util::SimpleMunge
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Util::SimpleMunge
For more information on module installation, please visit the detailed CPAN module installation guide.