Dist::Zilla::Role::Hooker(3pm)

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]
        . = XPerl codeX

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.