ExtUtils::Constant - generate XS code to import C header constants |
ExtUtils::Constant - generate XS code to import C header constants
use ExtUtils::Constant qw (WriteConstants); WriteConstants( NAME => 'Foo', NAMES => [qw(FOO BAR BAZ)], ); # Generates wrapper code to make the values of the constants FOO BAR BAZ # available to perl
ExtUtils::Constant facilitates generating C and XS wrapper code to allow
perl modules to AUTOLOAD constants defined in C library header files.
It is principally used by the h2xs
utility, on which this code is based.
It doesn't contain the routines to scan header files to extract these
constants.
Generally one only needs to call the WriteConstants
function, and then
#include "const-c.inc"
in the C section of Foo.xs
INCLUDE const-xs.inc
in the XS section of Foo.xs
.
For greater flexibility use constant_types()
, C_constant
and
XS_constant
, with which WriteConstants
is implemented.
Currently this module understands the following types. h2xs may only know
a subset. The sizes of the numeric types are chosen by the Configure
script at compile time.
double
, possibly long double
strlen
PL_sv_yes
) The value is not needed (and ignored).
PL_sv_no
) The value is not needed (and ignored).
undef
. The value of the macro is not needed.
#define
definitions for the
constants used internally between the generated C and XS functions.
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, or to generate a comment to
highlight the position of the character in the switch
statement.
A function to return a suitable #ifdef
clause. ITEM is a hashref
(as passed to C_constant
and match_clause
. INDENT is the number
of spaces to indent, defaulting to 6.
XXX document me
switch
clause, called by
C_constant
ITEMs are in the hash ref format as given in the description
of C_constant
, and must all have the names of the same length, given by
NAMELEN (This is not checked). ITEMHASH is a reference to a hash,
keyed by name, values being the hashrefs in the ITEM list.
(No parameters are modified, and there can be keys in the ITEMHASH that
are not in the list of ITEMs without causing problems).
An internal function to generate the embedded perl code that will regenerate
the constant subroutines. DEFAULT_TYPE, TYPES and ITEMs are the
same as for C_constant. INDENT is treated as number of spaces to indent
by. OPTIONS is a hashref of options. Currently only declare_types
is
recognised. If the value is true a $types
is always declared in the perl
code generated, if defined and false never declared, and if undefined $types
is only declared if the values in TYPES as passed in cannot be inferred from
DEFAULT_TYPES and the ITEMs.
An internal function to generate the embedded perl code that will regenerate the constant subroutines. Parameters are the same as for C_constant.
A function that 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. Each can either be a string, which is taken as a C macro name, or a reference to a hash with the following keys
#ifdef
. This defaults to the
name, and is mainly used if value is an enum
. If a reference an
array is passed then the first element is used in place of the #ifdef
line, and the second element in place of the #endif
. This allows
pre-processor constructions such as
#if defined (foo) #if !defined (bar) ... #endif #endif
to be used to determine if a constant is to be defined.
A ``macro'' 1 signals that the constant is always defined, so the #if
/#endif
test is omitted.
croak
ing with ``your vendor has not
defined...'') to return if the macro isn't defined. Specify a reference to
an array with type followed by value(s).
struct
and return this as value. This C code is places at the start of a block,
so you can declare variables in it.
SvUTF8()
is false),
``yes'' if the name is utf8 encoded.
The internals automatically clone any name with characters 128-255 but none 256+ (ie one that could be either in bytes or utf8) into a second entry which is utf8 encoded.
PACKAGE is the name of the package, and is only used in comments inside the generated C code.
The next 5 arguments can safely be given as undef
, and are mainly used
for recursion. SUBNAME defaults to constant
if undefined.
DEFAULT_TYPE is the type returned by ITEM
s that don't specify their
type. In turn it defaults to IV. 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. DEFAULT_TYPE will be added to the list if not
present, as will any types given in the list of ITEMs. The resultant list
should be the same list of types that XS_constant
is given. [Otherwise
XS_constant
and C_constant
may differ in the number of parameters to the
constant function. INDENT is currently unused and ignored. In future it may
be used to pass in information used to change the C indentation style used.]
The best way to maintain consistency is to pass in a hash reference and let
this function update it.
BREAKOUT governs when child functions of SUBNAME are generated. If there
are BREAKOUT or more ITEMs with the same length of name, then the code
to switch between them is placed into a function named SUBNAME_LEN, for
example constant_5
for names 5 characters long. The default BREAKOUT is
3. A single ITEM
is always inlined.
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 as 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.
constant()
routine doesn't recognise.
A function to generate perl code for Makefile.PL that will regenerate
the constant subroutines. Parameters are named as passed to WriteConstants
,
with the addition of INDENT
to specify the number of leading spaces
(default 2).
Currently only INDENT
, NAME
, DEFAULT_TYPE
, NAMES
, C_FILE
and
XS_FILE
are recognised.
#include
and INCLUDE
in the C and XS sections respectively of your module's XS
code. You probaby want to do this in your Makefile.PL
, so that you can
easily edit the list of constants without touching the rest of your module.
The attributes supported are
IV
is assumed.
const-c.inc
. The -
in the name ensures that the file can't be
mistaken for anything related to a legitimate perl package name, and
not naming the file .c
avoids having to override Makefile.PL's
.xs
to .c
rules.
const-xs.inc
.
constant
.
_
and the name
length appended, so constants with 10 character names would be in
constant_10
with the default XS_SUBNAME.
Nicholas Clark <nick@ccl4.org> based on the code in h2xs
by Larry Wall and
others
ExtUtils::Constant - generate XS code to import C header constants |