view release on metacpan or  search on metacpan

lib/Dist/Zilla/Plugin/MungeFile/WithConfigFile.pm  view on Meta::CPAN

Is transformed to:

    my $some_string = 'something derived from data in config file';
    my $maison = 'my castle';

=head1 DESCRIPTION

=for stopwords FileMunger

This is a L<FileMunger|Dist::Zilla::Role::FileMunger> plugin for
L<Dist::Zilla> that passes a file(s)
through a L<Text::Template>, with a variable provided that contains data
read from the provided config file.

L<Text::Template> is used to transform the file by making the C<< $config_data >>
variable available to all code blocks within C<< {{ }} >> sections.

This data is extracted from the provided C<configfile> using L<Config::Any>,
so a variety of file formats are supported, including C<JSON>, C<YAML> and
C<INI>.

The L<Dist::Zilla> object (as C<$dist>) and this plugin (as C<$plugin>) are
also made available to the template, for extracting other information about
the build.

Additionally, any extra keys and values you pass to the plugin are passed
along in variables named for each key.

=for Pod::Coverage munge_files munge_file mvp_aliases

=head1 OPTIONS

=head2 C<finder>

=for stopwords FileFinder

This is the name of a L<FileFinder|Dist::Zilla::Role::FileFinder> for finding
files to modify.

Other pre-defined finders are listed in
L<Dist::Zilla::Role::FileFinderUser/default_finders>.
You can define your own with the
L<[FileFinder::ByName]|Dist::Zilla::Plugin::FileFinder::ByName> plugin.

There is no default.

=head2 C<file>

Indicates the filename in the distribution to be operated upon; this file can exist on
disk, or have been generated by some other plugin.  Can be included more than once.

B<At least one of the C<finder> or C<file> options is required.>

=head2 C<arbitrary option>

All other keys/values provided will be passed to the template as is.

=head1 CAVEATS

Presently, the config file is not read with any sort of file decoding (e.g.
UTF-8), so any extracted strings should be appropriately decoded first. This
is an issue that needs to be resolved in L<Config::Any> (perhaps by having the
caller, in our case L<MooseX::SimpleConfig>, to pass the desired decoding).

=head1 SEE ALSO

=over 4

=item *

L<Dist::Zilla::Plugin::Substitute>

=item *

L<Dist::Zilla::Plugin::GatherDir::Template>

=item *

L<Dist::Zilla::Plugin::MungeFile>

=item *

L<Dist::Zilla::Plugin::MungeFile::WithDataSection>

=back

=head1 SUPPORT

Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-MungeFile-WithConfigFile>
(or L<bug-Dist-Zilla-Plugin-MungeFile-WithConfigFile@rt.cpan.org|mailto:bug-Dist-Zilla-Plugin-MungeFile-WithConfigFile@rt.cpan.org>).

There is also a mailing list available for users of this distribution, at
L<http://dzil.org/#mailing-list>.

There is also an irc channel available for users of this distribution, at
L<C<#distzilla> on C<irc.perl.org>|irc://irc.perl.org/#distzilla>.

I am also usually active on irc, as 'ether' at C<irc.perl.org>.

=head1 AUTHOR

Karen Etheridge <ether@cpan.org>

=head1 COPYRIGHT AND LICENCE

This software is copyright (c) 2014 by Karen Etheridge.

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

=cut