NAME

Dist::Zilla::Role::Hooker - Run Perl code written in your plugin's dist.ini section

VERSION

Version v0.8.4, released on 2018-03-15 21:44 UTC.

WHAT?

Dist-Zilla-Plugin-Hook (or just Hook) is a set of Dist-Zilla plugins. Every plugin executes Perl code inlined into dist.ini at particular stage of build process.

This is Hooker role documentation. Read this if you are going to hack or extend Dist-Zilla-Plugin-Hook, or use the role in your plugin.

If you want to write Dist::Zilla plugin directly in dist.ini, read the manual. General topics like getting source, building, installing, bug reporting and some others are covered in the README.

DESCRIPTION

Dist-Zilla-Plugin-Hook is a set of plugins: Hook::Init, Hook::BeforeBuild, Hook::GatherFiles, etc. All these plugins are just stubs, they contains almost no code. They just use services provided by the Hooker role. The role is an engine for all Hook plugins.

OBJECT ATTRIBUTES

code

Perl code to execute, list of lines (without newline characters).

ArrayRef[Str], read-only. Default value is empty array (i. e. no code).

Note: init_arg attribute property set to ".". In dist.ini file the Perl code should be specified using this notation:

    [Hook::Role]
        . = …Perl code…

OBJECT METHODS

hook

    $ret = $self->hook( @args );
    @ret = $self->hook( @args );
    $self->hook( @args );

This is the primary method of the role. The method executes Perl code specified in code attribute (prepended with _prologue) with string form of eval. The method passes arguments specified by the caller to the code, and passes the code return value back to the caller. Calling context (list, scalar, or void) is preserved. The method also hides all the lexical variables (except the variables documented below) from code. The method intercepts warnings generated in code and logs them; warnings do not stop executing.

Following lexical variables are exposed to the code intentionally:

@_

hook arguments, self-reference is already shifted!

$arg

The same as $_[ 0 ].

$self

$plugin

Reference to the plugin object executing the code (such as Hook::Init or Hook::BeforeBuild).

$dist

$zilla

Reference to Dist::Zilla object, the same as $self->zilla.

If code dies, the method logs error message and aborts Dist::Zilla.

_line_directive

    $dir = $self->_line_directive( $filename, $linenumber );
    $dir = $self->_line_directive( $filename );

The method returns Perl line directive, like

    #line 1 "filename.ext"

The method takes care about quotes. Perl line directive does not allow any quotes (escaped or not) in filename, so directive

    #line 1 "\"Assa\" project.txt"

will be ignored. To avoid this, line_directive replaces quotes in filename with apostrophes, e. g.:

    #line 1 "'Assa' project.txt"

If line number is not specified, 1 will be used.

_prologue

    @code = $self->_prologue;

The method returns prologue code.

Prologue code is extracted from Dist::Zilla plugin named prologue.

mvp_multivalue_args

The method tells Dist::Zilla that dot (.) is a multi-value option.

SEE ALSO

Dist::Zilla

Dist::Zilla::Role

Dist::Zilla::Role::Plugin

Dist::Zilla::Plugin::Hook::Manual

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015, 2016, 2018 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::Hook

perl -MCPAN -e shell
install Dist::Zilla::Plugin::Hook