ExtUtils::Constant (Perl in a Nutshell, 2nd Edition)

8.69. ExtUtils::Constant

For example:

use ExtUtils::Constant qw (WriteConstants);
WriteConstants(
    NAME => `Nate',
    NAMES => [qw(Nate Nathan Nathaniel)], # not Nat
);
# Generates wrapper code to make the values of the constants
# Nate Nathan Nathaniel available to perl

Currently, this module understands the following types, although h2xs may only know a subset. The sizes of the numeric types are chosen by the Configure script at compile time.

IV: Signed integer. At least 32 bits.
UV: Unsigned integer. The same size as IV.
NV: Floating-point type. Probably double. Possibly long double.
PV NUL[L]: Terminated string. Length will be determined with strlen.
PVN: A fixed-length thing, given as a pointer, length pair. If you know the length of a string at compile time, you can use this instead of PV.
SV: A mortal SV.
YES: Truth (PL_sv_yes). The value is not needed (and is ignored).
NO: Defined falsehood (PL_sv_no). The value is not needed (and is ignored).
UNDEF: The value of the macro is not needed.

ExtUtils::Constant implements the following functions.

assign

assign indent, type, pre, post, value ...

Returns a suitable assignment clause. If type is aggregate (e.g., PVN expects both pointer and length), then there should be multiple values for the components. pre and post, if defined, give snippets of C code to proceed and follow the assignment. preis at the start of a block, so variables may be defined in it.

autoload

autoload package, version, autoloader

Generates the AUTOLOAD subroutine for the module package. version is the Perl version with which the code should be backwards-compatible. It defaults to the version of Perl running the subroutine. If autoloaderis true, the AUTOLOAD subroutine falls back on AutoLoader::AUTOLOAD for all names that the constant() routine doesn't recognize.

C_constant

C_constant package, subname, default_type, types, indent,  breakout, item ...

Returns a list of C subroutine definitions that return the value and type of constants when passed the name by the XS wrapper. item... gives a list of constant names. These can be strings, which are taken as a C macro name, or references to a hash with the following keys:

name

The name of the constant, as seen by the Perl code.

type

The type of the constant (IV, NV, etc.).

value

A C expression for the value of the constant, or a list of C expressions if the type is aggregate. Defaults to name if not given.

macro

The C preprocessor macro to use in the #ifdef. Defaults to name and is primarily used if value is an enum. If a reference or an array is passed, then the first element is used in place of the #ifdef line, and the second element is used in place of the #endif. This allows preprocessor constructions such as:

#if defined (foo)
#if !defined (bar)
...
#endif
#endif

which are used to determine if a constant will be defined.

A macro of 1 signals that the constant is always defined, so the #if/#endif test is omitted.

default

Default value to use (instead of croak ing with "your vendor has not defined . . . ) if the macro isn't defined. Specifies a reference to an array with type followed by value(s).

pre

C code to use before the assignment of the value of the constant. This allows you to use temporary variables to extract a value from part of a struct and return this as value. This C code is placed at the start of a block, so you can declare variables in it.

post

C code to place between the assignment of value (temporary) and the return from the function. This allows you to clear up anything in pre. Rarely needed.

def_pre

def_post

Equivalents of pre and post for the default value.

utf8

Generated internally. Is 0 or undefined if name is 7-bit ASCII, no if the name is 8-bit (and so should match only if SvUTF8() is false), and yes if the name is utf8-encoded.

constant_types

constant_types

Returns a single scalar with #define definitions for the constants used internally between the generated C and XS functions.

C_stringify

C_stringify name

Returns a 7-bit ASCII correctly \-escaped version of the string passed. Suitable for C "" or ''. It will die if passed Unicode characters.

dump_names

dump_names default_type, types, indent, options, item ...

An internal function to generate the embedded Perl code to regenerate the constant subroutines. default_type, types, and items are the same as for C_constant. indent is the number of spaces to indent. options is a hashref of options; currently, only declare_types is recognized. If the value is true, a types is always declared in the generated Perl code; if defined and false, one is never declared; and if undefined, types is declared only if the values in types as passed in cannot be inferred from default_types and the items.

memEQ_clause

memEQ_clause name, checked_at, indent

Returns a suitable C if statement to check whether name is equal to the C variable name. If checked_at is defined, then it is used to avoid memEQ for short names.

params

params what

An internal function. what should be a hashref of types the constant function will return. params returns a hashref keyed IV NV PV SV to show which combination of pointers will be needed in the C argument list.

perl_stringify

perl_stringify name

Returns a 7-bit ASCII correctly \-escaped version of the string passed. Suitable for a Perl "" string.

return_clause

return_clause item, indent

Returns a suitable #ifdef clause. item is a hashref passed to C_constant and match_clause. indent is the number of spaces to indent; defaulting is 6.

switch_clause

switch_clause indent, namelen, itemhash, item ...

An internal function to generate a suitable switch clause, called by C_constant. items are in the hashref format as given in the description of C_constant and must all have names of the same length, given by namelen. itemhash is a reference to a hash, keyed by name, with values as the hashrefs in the item list.

XS_constant

XS_constant package, types, subname, c_subname

Generates the XS code to implement the Perl subroutine package::constant used by package::AUTOLOAD to load constants. This XS code is a wrapper around a C subroutine usually generated by C_constant and usually named constant

types should be given either as a comma-separated list of types that the C subroutine constant will generate or as a reference to a hash. It should be the same list of types that C_constant was given. Otherwise, XS_constant and C_constant may have different ideas about the number of parameters passed to the C function constant.

You can call the Perl visible subroutine something other than "constant" if you give the parameter subname. The C subroutine it calls defaults to the name of the Perl visible subroutine, unless you give the parameter c_subname.