Dist::Zilla::Role::Regenerator(3)

NAME
Dist::Zilla::Role::Regenerator - A package which can regenerate source files

VERSION
version 0.001003

SYNOPSIS
  package Dist::Zilla::Plugin::Regenerate::SomeThing;
  use Moose;
  use Path::Tiny qw( path );
  with "Dist::Zilla::Role::Plugin","Dist::Zilla::Role::Regenerator";

  ...
  sub regenerate {
    my ( $self, $config ) = @_;
    path($config->{root}, 'CONTRIBUTING.pod')->spew_raw($content);
    path($config->{build_root}, 'META.json')->copy(path($config->{root}, 'META.json'));
  }

DESCRIPTION
This role is for "Dist::Zilla" "Plugin"'s that wish to fire under "dzil regenerate"

It is strongly recommended that this role not be lumped on randomly into packages that will operate at other phases.

IMPLEMENTATION
Consumers of this role MUST compose in "Dist::Zilla::Role::Plugin" at some stage, or at least, "Dist::Zilla::Role::ConfigDumper".

Consumers of this rule MUST implement a method "regenerate".

  "regenerate" implementation
"regenerate" will be called as a method and passed a configuration hash.

  {
      build_root => "path/to/where/dzil/build/writes/to"
      root       => "path/to/dzil/source/tree"
  }

You may do with these as you wish, but recommended usage is to employ "Path::Tiny" to do one of the following:

•   Write files directly from the plugin

      path($config->{root}, "CONTRIBUTING.pod")->spew_raw( ... );

    Keep in mind how file encoding works if you get your data from other parts of "Dist::Zilla"

•   Copy files from the build tree

      path($config->{build_root}, "META.json")->copy($path->{root}, "META.json");

    ( Note: This case is implemented by "[Regenerate]" )

•   (DON'T) Write files from "zilla" to disk

    How you'd do this is left to your imagination, but the details are ugly.

    Take note of the calls to "_write_out_file" in "Dist::Zilla::Dist::Builder" and the implementation details of "_write_out_file" in "Dist::Zilla"

    I suspect something like

      $self->zilla->_write_out_file( $self->zilla->files[0] , $config->{root} )

    Might kinda work, but keep in mind, that will spew if the file already exists.

    Good Luck Have Fun.

    Also, this approach is NOT recommended, because the final release image is NOT drafted from "$self->zilla->files" but from direct read of the "$config->{build_root}".

    See "Dist::Zilla/build_archive" which has the call sequence:

    •   ensure_built_in ...

    •   write_out ...

    •   "-AfterBuild"

    •   "-BeforeArchive"

    •   "_build_archive" ( from $write_out_dir )

AUTHOR
Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
This software is copyright (c) 2016-2017 by Kent Fredric <kentfredric@gmail.com>.

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