NAME

Package::Transporter::Rule::Standard - standard rule class

SYNOPSIS

        use Package::Transporter::Rule;

        my $rule = Package::Transporter::Rule->new
                ($generator, $pkg_match, $sub_match, $argc_match);

DESCRIPTION

A rule is a check whether a generator should run to generate a missing subroutine. Example: a call for the missing subroutine Ex::Ample::no_such_thing(7, [8, 9]) will cause these style of checks to occur internally:

        $rule->check('Ex::Ample', 'no_such_thing', 1, 7, [8, 9]);

To create a rule object for the above example, use this class as follows:

        use Package::Transporter::Rule;
        my $rule = Package::Transporter::Rule->new
                ($generator, 'Ex::Ample', 'no_such_thing', 1, '', 'ARRAY');

However, it is not required to specify all details; normally the last item in rule creation is the subroutine name. Note that the standard rule class does not check the values of arguments, but rather the result of ref().

In order to minimize the number of rules to evaluate, they are organized in a tree by package name and subroutine name. Internally the above rule will be stored in the pre-selection tree under

        'Ex::Ample' => {'no_' => [$rule]}

This detail only needs to be considered when you write your own rules class. See the pre_select attribute in the standard class.

A Generator

Please see the documentation of the generator base class Package::Transporter::Generator.

Matching a Package

To widen the scope of a hierarchy search rule, shorten the names. Ex:: applies to all package names starting with Ex:: (no wildcard required), Ex::(A|B|C) is recognized as a regular expression and an empty package name applies to all packages. Alternatively you can specify a list of complete names (meaning these won't undergo wildcard interpretation) as an array reference.

        $pkg_match = 'The::Requesting::Package'; # exact
        $pkg_match = 'The::Requesting::'; # wildcard
        $pkg_match = 'The::Requesting(1|2)::'; # RE
        $pkg_match = ''; # wildcard, dangerous
        $pkg_match = sub { if ... return(1) ... return(0) }; # dynamic
        $pkg_match = ['Requesting1', 'Requesting2', ...]; # an array ref

Matching a Subroutine

Similarly for subroutine names (any kind of search). Specify no_ to match a name starting with no_ (partial subroutine name ending in underscore but no wildcard required), no_(parking|money) is recognized as a regular expression and an empty subroutine name applies to all subroutines. Alternatively you can specify a list of complete names (meaning these won't undergo wildcard interpretation) as an array reference.

        $sub_match = 'missing_subroutine'; # exact
        $sub_match = 'missing_'; # wildcard
        $sub_match = 'missing_(subroutine|function)'; # RE
        $sub_match = ''; # wildcard, dangerous
        $sub_match = sub { if ... return(1) ... return(0) }; # dynamic
        $sub_match = ['missing1', 'missing2', ...]; # an array ref

Matching The Argument Count

Normally not specified. Either the exact number of arguments passed or undef for any number of arguments. No syntax for 'less than' or 'more than'. Read on for dangers behind using this criteria.

Matching Types of Arguments

Normally not specified. The types of the actual call as returned by ref(). Keep in mind that subsequent calls to the subroutine might be done with different number and types of arguments, which the subroutine must also handle correctly. The subroutine is not re-defined depending on the calling context.

wantarray - not available

It is a design decision not to forward the return value of wantarray to the rule matchers. That would only cause surprising behaviour, because different variants of a subroutine could be generated depending on the context in which it is first called. wantarray was made for dynamic return values of subroutines, not for arbitrary static behaviour.

PUBLIC METHODS

The following methods belong to the public interface of Package::Transporter::Package.

check

The constructor as shown in the synopsis.

check

Called when the rule was pre-selected, should decide whether the generator applies to the missing subroutine and return the generator.

pre-select

Return string representations of the matchers for package name and subroutine name. This is for optimization purposes, so that not all rules have to be considered each time a subroutine is missing.

ANYTHING ELSE

Please see the documentation of the upstream package Package::Transporter.

cpanm Package::Transporter

perl -MCPAN -e shell
install Package::Transporter