/ 
Dist-Zilla-Plugin-MetaResources-Template-0.001
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::MetaResources::Template::Manual

NAME

Dist::Zilla::Plugin::MetaResources::Template::Manual - MetaResources::Template plugin user manual

VERSION

Version 0.001, released on 2015-07-09 18:08 UTC.

WHAT?

Dist-Zilla-Plugin-MetaResources-Template is a Dist::Zilla plugin, a replacement for standard plugin MetaResources. Both provide resources for distribution metadata, but this one treats values as text templates.

This is Manifest::Write plugin user manual. Read this if you want to use Perl code in distribution "resource" metadata.

If you are going to hack or extend Dist-Zilla-Plugin-MetaResources-Template, read the module documentation. General topics like getting source, building, installing, bug reporting and some others are covered in the readme.

SYNOPSIS

In your dist.ini:

[MetaResources::Template]
    license             = {{ $dist->license->url }}
    bugtracker.web      = https://rt.cpan.org/Public/Dist/Display.html?Name={{ $dist->name }}
    bugtracker.mailto   = mailto:bug-{{ $dist->name }}@rt.cpan.org
    …

DESCRIPTION

Dist-Zilla-Plugin-MetaResources-Template is a replacement for MetaResources standard plugin. To use Dist-Zilla-Plugin-MetaResources-Template you should replace line

[MetaResources]

with

[MetaResources::Template]

in your dist.ini. Voilà! Now all the plugin options are treated as templates. It means text surrounded by double braces (e. g. {{ $dist->name }}) is evaluated as Perl code, and result of evaluation replaces the original text (and surrounding double braces). For example:

name = Foo
…
[MetaResources::Template]
    bugtracker.mailto = mailto:bug-{{ $dist->name }}@rt.cpan.org
    # Option value will be "mailto:bug-Foo@rt.cpan.org".

Within Perl code, two variables are set: $dist and $plugin. $dist variable gives you access to Dist-Zilla instance and various distribution attributes:

$dit->name          # string
$dist->version      # string
$dist->abstract     # string
$dist->authors      # arrayref
…

See "ATTRIBUTES" in Dist::Zilla for full list of attributes.

$plugin variable is mostly useless and provided for conformance with other plugins (GenerateFile, GatherDir::Template, TemplateFiles, etc). In case of complex code (which is unlikely to happen) you can use it for logging, though:

{{ …; $plugin->log( "message" ); …; }}
{{ …; $plugin->log_fatal( "aborting…" ); …; }}

You need to study Dist::Zilla guts in order to understand what could be done through the plugin reference.

Actual evaluating and replacement (i. e. template processing) is performed by Text::Template module, so look for the gory details there.

WHY?

By using standard MetaResources plugin you can specify resources for your distribution metadata, e. g.:

[MetaResources]
    homepage          = http://example.org/~AUTHOR/NAME
    bugtracker.web    = http://rt.cpan.org/NoAuth/Bugs.html?Dist=NAME
    bugtracker.mailto = bug-NAME@rt.cpan.org
    repository.url    = git://example.org/AUTHOR/NAME.git
    repository.web    = http://example.org/AUTHOR/NAME
    repository.type   = git

Quite simple, but project name (NAME) appears 5 times in 7 lines — it is far too many to my taste. Repeating the same name multiple times is boring and error-prone, it complicates project creation and maintenance.

I know there are plugins like GitHib or Bitbucket which fulfill the resources. However, they are not applicable if your project lives at another, less popular hosting, like SourceForge, Savannah, or TuxFamily. There are no dedicated plugins for these hostings, and probably for many others.

MetaResources::Template helps to reduce duplication without introducing any hosting-specific details. MetaResources::Template treats resources as text templates:

[MetaResources::Template]
    homepage          = http://example.org/~AUTHOR/{{ $dist->name }}
    bugtracker.web    = http://rt.cpan.org/NoAuth/Bugs.html?Dist={{ $dist->name }}
    bugtracker.mailto = bug-{{ $dist->name }}@rt.cpan.org
    repository.url    = git://example.org/AUTHOR/{{ $dist->name }}.git
    repository.web    = http://example.org/AUTHOR/{{ $dist->name }}
    repository.type   = git

SEE ALSO

Dist::Zilla — Distribution builder
Dist::Zilla::Plugin::MetaResources — Standard plugin
Text::Template — Template engine

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Plugin-MetaResources-Template.

perl-Dist-Zilla-Plugin-MetaResources-Template is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Plugin-MetaResources-Template is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Plugin-MetaResources-Template. If not, see <http://www.gnu.org/licenses/>.