Kent Fredric │‫3﹪🔋


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


version 1.000001


  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.

  • $content will contain the content, decoded if possible

  • $encoding will be either text or bytes, the latter if decoding is not possible.

  • InMemory will apply the code immediately

  • FromCode will 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 an InMemory instance via the callback.

  • munge_FromCode - trusts you when you say you have a FromCode, and munges with CodeRef chaining.

  • 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 a FromCode represented as a new InMemory object.

  • to_FromCode - returns an InMemory represented as a new FromCode object.

  • inplace_to_InMemory - like to_InMemory, but replaces the object in-place.

  • inplace_to_FromCode - like to_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.


  source = ADDR=0x015 = data = { x => y }
                      = class = Foo

  target = ADDR=0x017 = data = { z => a }
                      = class = Bar

  array  = ADDR=0x016 = data = [ 0x015 ]


  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 )

      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"

See Also


Kent Fredric <>


This software is copyright (c) 2014 by Kent Fredric <>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.