/ 
Dist-Zilla-Plugin-MetaResources-Template-v0.4.7
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 v0.4.7, released on 2015-11-05 20:49 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.example.org/Public/Dist/Display.html?Name={{$dist->name}}
    bugtracker.mailto   = mailto:bug-{{$dist->name}}@rt.example.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.example.org
    # Option value will be "mailto:bug-Foo@rt.example.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://example.org/bugs.html?dist=NAME
    bugtracker.mailto = bug-NAME@rt.example.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://example.org/bugs.html?dist={{$dist->name}}
    bugtracker.mailto = bug-{{$dist->name}}@rt.example.org
    repository.url    = git://example.org/AUTHOR/{{$dist->name}}.git
    repository.web    = http://example.org/AUTHOR/{{$dist->name}}
    repository.type   = git

EXAMPLES

;   file: dist.ini
name    = Assa
version = 0.007
author  = John Doe <john.doe@example.org>
license = GPL_3::or_later
[GenerateFile/Assa]
    filename = lib/Assa.pm
    content  = package Assa;
    content  = # ABSTRACT: MetaResources::Template example
    content  = 1;
[MetaResources::Template]
    homepage            = http://example.org/{{$dist->name}}
    license             = {{$dist->license->url}}
    bugtracker.web      = https://rt.example.org/{{$dist->name}}
    bugtracker.mailto   = mailto:bug-{{$dist->name}}@rt.example.org
    x_plugin            = Generated with {{$plugin->plugin_name}}
[MetaYAML]
[MetaJSON]
; end of file ;

SEE ALSO

Dist::Zilla — Distribution builder
Dist::Zilla::Plugin::MetaResources — Standard plugin
Text::Template — Template engine
CPAN::Meta::Spec — Distribution metainfo specification
"resources" in CPAN::Meta::Spec — Specification of "resources"

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015 Van de Bugger

License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.