add readme.mkdn

README.mkdn

@@ -0,0 +1,118 @@
+# NAME
+
+Dist::Zilla::Util::SimpleMunge - Make munging File::FromCode and File::InMemory easier.
+
+# VERSION
+
+version 0.2.2
+
+# SYNOPSIS
+
+    use Dist::Zilla::Util::SimpleMunge qw( munge_file munge_files );
+    ...;
+
+    sub somesub {
+      ...;
+      munge_file $file_from_zilla, {
+        via => sub {
+          my ( $file, $content ) = @_;
+          ... mangle $content here ...;
+          return $mangled;
+        },
+      };
+    }
+
+# FUNCTIONS
+
+## munge\_file
+
+    # munge_file ( $FILE , \%CONFIGURATION )
+
+    munge_file(
+      $zilla_file,
+      {
+        via => sub { ... },
+          lazy => $laziness
+      }
+    );
+
+#### $FILE
+
+A [`::Role::File` ](http://search.cpan.org/perldoc?Dist::Zilla::Role::File) object to munge.
+
+#### %CONFIGURATION
+
+    {
+      via => $CODEREF,
+      lazy => $LAZINESS,
+    }
+
+#### $CODEREF
+
+Called to munge the file itself.
+
+Passed a reference to the [`::Role::File` ](http://search.cpan.org/perldoc?Dist::Zilla::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;
+    }
+
+#### $LAZINESS
+
+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` ](http://search.cpan.org/perldoc?Dist::Zilla::File::OnDisk) and
+[`::File::InMemory` ](http://search.cpan.org/perldoc?Dist::Zilla::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` ](http://search.cpan.org/perldoc?Dist::Zilla::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 behaviour, 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 )
+
+## munge\_files
+
+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\_file).
+
+    # munge_files ( \@FILEARRAY , \%CONFIGURATION )
+
+    munge_files( [ $zilla_file_one, $zilla_file_two, ], {
+      via => sub { ... },
+      lazy => $laziness,
+    });
+
+#### @FILEARRAY
+
+An `ArrayRef` of ["$FILE"](#$FILE)
+
+#### See Also
+
+- ["%CONFIGURATION"](#%CONFIGURATION)
+- ["$CODEREF"](#$CODEREF)
+- ["$FILE"](#$FILE)
+- ["$LAZINESS"](#$LAZINESS)
+
+# AUTHOR
+
+Kent Fredric <kentnl@cpan.org>
+
+# COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2013 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.