Dist::Zilla::Plugin::IfBuilt - Use code only in built (or unbuilt/raw) version
This document describes version 0.02 of Dist::Zilla::Plugin::IfBuilt (from Perl distribution Dist-Zilla-Plugin-IfBuilt), released on 2015-06-17.
In dist.ini:
[IfBuilt] [InsertBlock::FromModule]
In lib/Foo.pm:
... # IFUNBUILT use warnings; # END IFUNBUILT # IFBUILT ##INSERT_BLOCK Function::Embeddable uniq # END IFBUILT # IFUNBUILT use List::MoreUtils 'uniq'; # END IFUNBUILT ...
After build, the above section will become:
... # IFUNBUILT # use warnings; # END IFUNBUILT # IFBUILT sub uniq (@) { my %seen = (); my $k; my $seen_undef; grep { defined $_ ? not $seen{ $k = $_ }++ : not $seen_undef++ } @_; } # END IFBUILT # IFUNBUILT # use List::MoreUtils 'uniq'; # END IFBUILT ...
This plugin finds blocks like this:
# IFBUILT # ... # END IFBUILT
or this:
# IFUNBUILT ... # END IFBUILT
in your modules and scripts. All the lines inside # IFBUILT ... # END IFBUILT must all be commented-out, and they will be uncommented (one character # removed from each line) in the built version. On the other hand, all the lines inside # IFUNBUILT ... # END IFUNBUILT will be commented (one character # added to each line) in the built version.
# IFBUILT
# END IFBUILT
#
# IFUNBUILT
# END IFUNBUILT
This plugin is useful when you want to have code that is only present in the built/unbuilt version. One use-case is when you want to replace a routine with an inlined version in the built edition, like the example in Synopsis. In the unbuilt/raw version, the routine is retrieved from a module. This allows testing to work either with the unbuilt version (e.g. using prove -l) or the built version (e.g. using dzil test).
prove -l
dzil test
Dist::Zilla::Plugin::InsertBlock, Dist::Zilla::Plugin::InsertBlock::FromModule
Please visit the project's homepage at https://metacpan.org/release/Dist-Zilla-Plugin-IfBuilt.
Source repository is at https://github.com/perlancar/perl-Dist-Zilla-Plugin-IfBuilt.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-IfBuilt
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2015 by perlancar@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.
To install Dist::Zilla::Plugin::IfBuilt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Plugin::IfBuilt
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Plugin::IfBuilt
For more information on module installation, please visit the detailed CPAN module installation guide.