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.