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.

cpanm Dist::Zilla::Plugin::MetaResources::Template

perl -MCPAN -e shell
install Dist::Zilla::Plugin::MetaResources::Template