/ 
Require-HookChain-0.012
River stage one • 1 direct dependent • 1 total dependent
/ Require::HookChain

NAME

Require::HookChain - Chainable require hook

VERSION

This document describes version 0.012 of Require::HookChain (from Perl distribution Require-HookChain), released on 2023-04-22.

SYNOPSIS

Say you want to create a require hook to prepend some code to the module source code that is loaded. In your hook source, in Require/HookChain/munge/prepend.pm:

package Require::HookChain::munge::prepend;

sub new {
    my ($class, $preamble) = @_;
    bless { preamble => $preamble }, $class;
}

sub Require::HookChain::munge::prepend::INC {
    my ($self, $r) = @_;

    # safety, in case we are not called by Require::HookChain
    return () unless ref $r;

    my $src = $r->src;
    return unless defined $src;
    $src = "$self->{preamble};\n$src";
    $r->src($src);
}

1;

In a code to use this hook:

use Require::HookChain 'munge::prepend' => 'use strict';
use Foo::Bar; # Foo/Bar.pm will be loaded with added 'use strict;' at the start

Install another hook, but put it at the end of @INC instead of at the beginning:

use Require::HookChain -end => 1, append => 'some code';

DESCRIPTION

This module lets you create chainable require hooks. As one already understands, Perl lets you put a coderef or object in @INC. In the case of object, its INC method will be called by Perl:

package My::INCHandler;
sub new { ... }
sub My::INCHandler::INC {
    my ($self, $filename) = @_;
    ...
}

The method is passed itself then filename (which is what is passed to require()) and is expected to return nothing or a list of up to four values: a scalar reference containing source code, filehandle, reference to subroutine, optional state for subroutine (more information can be read from the perlfunc manpage). As soon as the first hook in @INC returns non-empty value then the search for source code is stopped.

With Require::HookChain, you can put multiple hooks in @INC that all get executed. When use'd, Require::HookChain will install its own hook at the beginning of @INC which will search for source code in @INC as well as execute INC method of all the other hooks which are instances of Require::HookChain::* class. Instead of filename, the method is passed a Require::HookChain::r object ($r). The method can do things on $r, for example retrieve source code via $r->src or modify source code via $r->src($new_content). After the method returns, the next Require::HookChain::* hook is executed, and so on. The final source code will be retrieved from $r->src and returned for Perl.

This lets one chainable hook munge the result of the previous chainable hook.

To create your own chainable require hook, see example in "SYNOPSIS". First you create a module under the Require::HookChain::* namespace, then create a constructor as well as INC handler.

Import options

Options must be specified at the beginning, before specifying

  • -end

    Bool. If set to true, then hooks will be put at the end of @INC instead of at the beginning (after Require::HookChain's own hook). Regardless, Require::HookChain's own hook will be put at the beginning to allow executing all the other hooks.

  • -debug

    Bool. If set to true, then debug messages will be printed to stderr.

Subnamespace organization

  • Require::HookChain::debug::

    Hooks that do debugging-related stuffs. See also: log:: subnamespace, timestamp:: subnamespace.

  • Require::HookChain::filter::

    Hooks that filter module loading due to some criteria. These hooks can fail a module being loaded even though the source is available, if the additional criteria are not met.

  • Require::HookChain::log::

    Hooks that add logging to module loading process. See also: debug:: subnamespace.

  • Require::HookChain::munge::

    Hooks that modify source code.

  • Require::HookChain::source::

    Hooks that allow loading module source from alternative sources.

  • Require::HookChain::test::

    Testing-related, particularly testing the Require::HookCHain hook module itself.

  • Require::HookChain::timestamp::

    Hooks that add timestamps during module loading process.

Require::HookChain::r OBJECT

Methods

filename

Usage:

my $filename = $r->filename;

src

Usage:

my $src = $r->src;
$r->src($new_src);

Get or set source code content. Will return undef if source code has not been found or set.

FAQ

Loading a hook does nothing!

Make sure you use a hook this way:

use Require::HookChain 'hookname'; # correct

instead of:

use Require::HookChain::hookname; # INCORRECT

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Require-HookChain.

SOURCE

Source repository is at https://github.com/perlancar/perl-Require-HookChain.

SEE ALSO

RHC for convenience of using on the command-line or one-liners.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2023, 2022, 2020, 2017 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Require-HookChain

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.