File Coverage

blib/lib/Sub/Inject.pm

Criterion	Covered	Total	%
statement	4	5	80.0
branch	1	2	50.0
condition	1	3	33.3
subroutine	2	2	100.0
pod	1	1	100.0
total	9	13	69.2

package Sub::Inject;
$Sub::Inject::VERSION = '0.3.0';
# ABSTRACT: Inject subroutines into a lexical scope

use 5.018;

require XSLoader;
XSLoader::load(__PACKAGE__);

sub sub_inject {
    @_ = %{ $_[0] } if @_ == 1 && ref $_[0] eq 'HASH';
    goto &_sub_inject;
}

1;

#pod =encoding utf8
#pod
#pod =head1 SYNOPSIS
#pod
#pod     use Sub::Inject;   # requires perl 5.18+
#pod
#pod     {
#pod         BEGIN { Sub::Inject::sub_inject( 'one', sub { say "One!" } ); }
#pod         one();
#pod     }
#pod
#pod     one();    # throws "Undefined subroutine &main::one called"
#pod
#pod =head1 DESCRIPTION
#pod
#pod This module allows to dynamically inject lexical subs
#pod during compilation. It is implemented using
#pod lexical subroutines introduced in perl 5.18.
#pod
#pod This is a low level library. It is meant for cases where
#pod subroutine names and bodies are to be treated as data
#pod or not known in advance. Otherwise, lexical subs syntax
#pod is recommended. For instance,
#pod
#pod     use experimental qw(lexical_subs);
#pod     state sub foo { say "One!" }
#pod
#pod is the static equivalent of
#pod
#pod     BEGIN {
#pod         Sub::Inject::sub_inject( 'one', sub { say "One!" } );
#pod     }
#pod
#pod =head1 HOW IT WORKS
#pod
#pod Used like
#pod
#pod     BEGIN { Sub::Inject::sub_inject('foo', sub { ... }) }
#pod
#pod it works as
#pod
#pod     \state &foo = sub { ... };
#pod
#pod That means:
#pod
#pod =over 4
#pod
#pod =item *
#pod
#pod The scope behavior is the same as the lexical sub statement
#pod
#pod =item *
#pod
#pod Being a "state" lexical guarantees the persistence
#pod of the association between the name and the subroutine
#pod
#pod =item *
#pod
#pod The reference aliasing operation means no copy is done
#pod
#pod =back
#pod
#pod =head1 FUNCTIONS
#pod
#pod =head2 sub_inject
#pod
#pod     sub_inject($name, $code);
#pod     sub_inject($name1, $code1, $name2, $code2);
#pod     sub_inject(\%subs);
#pod
#pod Injects C<$code> as a lexical subroutine named C<$name>
#pod into the currently compiling scope. The same applies
#pod to multiple name / code pairs given as input.
#pod
#pod Throws an error if called at runtime.
#pod
#pod =head1 ACKNOWLEDGEMENTS
#pod
#pod This code is a fork of "Lexical.xs" file from
#pod L
#pod by L.
#pod
#pod =head1 SEE ALSO
#pod
#pod L
#pod
#pod L
#pod
#pod L and L
#pod
#pod =cut

__END__