View on
MetaCPAN
Reini Urban > ExtUtils-Constant-0.23_08 > ExtUtils::Constant::ProxySubs

Download:
ExtUtils-Constant-0.23_08.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.23_08   Source  

NAME ^

ExtUtils::Constant::ProxySubs - generate XS ProxySubs code

SYNOPSIS ^

    use ExtUtils::Constant qw (WriteConstants);
    WriteConstants(
        NAME         => 'Package',
        NAMES        => [qw(FOO BAR BAZ)],
        PROXYSUBS    => { autoload => 1 },
        DEFAULT_TYPE => 'IV',
    );
    # Generates easier wrapper code, unusable with 5.6

DESCRIPTION ^

With the PROXYSUBS option to WriteConstants, this module generates better XS code, with 4 optional variants.

Each symbol is added as CONSTSUB at BOOT time, as via sub NAME () {value}. Undefined names (#undef NAME) will be stored in a special ExtUtils::Constant::ProxySubs::Missing namespace, because accessing an undefined name should throw a different error "Your vendor has not defined MyPackage macro NAME", and not "Undefined subroutine &MyPackage::NAME".

There's no run-time lookup for matching names in the constant function, but there's still AUTOLOAD needed to catch unknown names and a short dispatch for matching types.

NOTICE:

ExtUtils::Constant::ProxySubs versions older than 0.23_04 creates code usable only >= 5.14. There is no official CPAN version which creates usable code yet. The CPAN maintainers think p5p should sort it out, which they didn't for the last 7 years.

OPTIONS ^

PROXYSUBS can be used with an optional hashref of 4 exclusive options.

'autoload', 'croak_on_error' and 'croak_on_read' can not be used together. 'push' and 'croak_on_read' cannot be used together.

autoload

This option generates an XS AUTOLOAD function which dispatches to the XS constant function. Only auto-generated C and XS code is needed, no manual addition of sub AUTOLOAD as generated by ExtUtils::Constant::autoload.

Limitation: With 5.6 the error message for undefined macros is not "Your vendor has not defined MyPackage macro NAME", but "Undefined subroutine &MyPackage::NAME"

push

This option keeps a list of all added constants.

E.g. NAME => 'MyPackage', PROXYSUBS => { push => 'CONSTNAMES' }, will create @MyPackage::CONSTNAMES.

croak_on_error

Errors in run-time name lookup via XS constant is normally handled by AUTOLOAD. With croak_on_error the AUTOLOAD function can be simplified, errors with missing undefined names are thrown directly in the XS constant() function.

The XS caller context might be different to the pure-perl AUTOLOAD context though, identifying the source location of the error.

croak_on_read

Similar to croak_on_error, but much more restrictive. For each variable which should report the "Your vendor has not defined MyPackage macro NAME" error, a magic getter and setter hook is added to throw this error.

This option creates code usable only since Perl 5.24, so don't use it with any CPAN module!

AUTHOR ^

Reini Urban <rurban@cpan.org> fixed up ProxySubs and took over maintainance. Nicholas Clark <nick@ccl4.org> wrote it from scratch.

syntax highlighting: