Require::HookChain - Chainable require hook
This document describes version 0.004 of Require::HookChain (from Perl distribution Require-HookChain), released on 2022-11-15.
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:
@INC
use Require::HookChain -end => 1, append => 'some code';
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:
INC
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.
require()
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.
Require::HookChain
use
Require::HookChain::*
Require::HookChain::r
$r
$r->src
$r->src($new_content)
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.
Usage:
my $filename = $r->filename;
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.
Please visit the project's homepage at https://metacpan.org/release/Require-HookChain.
Source repository is at https://github.com/perlancar/perl-Require-HookChain.
RHC for convenience of using on the command-line or one-liners.
perlancar <perlancar@cpan.org>
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.
This software is copyright (c) 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.
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.
To install Require::HookChain, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Require::HookChain
CPAN shell
perl -MCPAN -e shell install Require::HookChain
For more information on module installation, please visit the detailed CPAN module installation guide.