Perl Cd Bookshelf [Electronic resources] نسخه متنی

8.69. ExtUtils::Constant

Generates XS code to import C header
constants, allowing Perl modules to AUTOLOAD constants defined in C
library header files. Generally, you should not touch
ExtUtils::Constant functions, since they are already implemented by
h2xs.

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 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 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 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

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

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 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 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 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 name

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

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 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 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.