Dist::Zilla::Util::SimpleMunge - Make munging File::FromCode and File::InMemory easier.
version 1.000003
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.
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.
$contentwill contain the content, decoded if possible$encodingwill be eithertextorbytes, the latter if decoding is not possible.InMemorywill apply the code immediatelyFromCodewill take your code and create a chained system so your code will be evaluated when the file itself is written out.
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 anInMemoryinstance via the callback.munge_FromCode- trusts you when you say you have aFromCode, and munges withCodeRefchaining.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.to_InMemory- returns aFromCoderepresented as a newInMemoryobject.to_FromCode- returns anInMemoryrepresented as a newFromCodeobject.inplace_to_InMemory- liketo_InMemory, but replaces the object in-place.inplace_to_FromCode- liketo_FromCode, but replaces the object in-place.munge_file- combines all of the above behaviors based on configuration values.munge_files- applies a single configuration and callback to a collection of files.
# 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.
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
Shorthand for
inplace_replace( $file, to_FromCode($file) );
Shorthand for
inplace_replace( $file, to_InMemory($file) );
# munge_file ( $FILE , \%CONFIGURATION )
munge_file(
$zilla_file,
{
via => sub { ... },
lazy => $laziness
}
);
A ::Role::File object to munge.
{
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
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.
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.
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 )
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"
Kent Fredric [email protected]
This software is copyright (c) 2017 by Kent Fredric [email protected].
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.