ExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files
# read/create filemy $typemap = ExtUtils::Typemaps->new(file => 'typemap');# alternatively create an in-memory typemap# $typemap = ExtUtils::Typemaps->new();# alternatively create an in-memory typemap by parsing a string# $typemap = ExtUtils::Typemaps->new(string => $sometypemap);# add a mapping$typemap->add_typemap(ctype => 'NV', xstype => 'T_NV');$typemap->add_inputmap( xstype => 'T_NV', code => '$var = ($type)SvNV($arg);');$typemap->add_outputmap( xstype => 'T_NV', code => 'sv_setnv($arg, (NV)$var);');$typemap->add_string(string => $typemapstring); # will be parsed and merged# remove a mapping (same for remove_typemap and remove_outputmap...)$typemap->remove_inputmap(xstype => 'SomeType');# save a typemap to a file$typemap->write(file => 'anotherfile.map');# merge the other typemap into this one$typemap->merge(typemap => $another_typemap);This module can read, modify, create and write Perl XS typemap files. If you don't know what a typemap is, please confer theperlxstut andperlxs manuals.
The module is not entirely round-trip safe: For example it currently simply strips all comments. The order of entries in the maps is, however, preserved.
We check for duplicate entries in the typemap, but do not check for missingTYPEMAP entries forINPUTMAP orOUTPUTMAP entries since these might be hidden in a different typemap.
Returns a new typemap object. Takes an optionalfile parameter. If set, the given file will be read. If the file doesn't exist, an empty typemap is returned.
Alternatively, if thestring parameter is given, the supplied string will be parsed instead of a file.
Get/set the file that the typemap is written to when thewrite method is called.
Add aTYPEMAP entry to the typemap.
Required named arguments: Thectype (e.g.ctype => 'double') and thexstype (e.g.xstype => 'T_NV').
Optional named arguments:replace => 1 forces removal/replacement of existingTYPEMAP entries of the samectype.skip => 1 triggers a"first come first serve" logic by which new entries that conflict with existing entries are silently ignored.
As an alternative to the named parameters usage, you may pass in anExtUtils::Typemaps::Type object as first argument, a copy of which will be added to the typemap. In that case, only thereplace orskip named parameters may be used after the object. Example:
$map->add_typemap($type_obj, replace => 1);Add anINPUT entry to the typemap.
Required named arguments: Thexstype (e.g.xstype => 'T_NV') and thecode to associate with it for input.
Optional named arguments:replace => 1 forces removal/replacement of existingINPUT entries of the samexstype.skip => 1 triggers a"first come first serve" logic by which new entries that conflict with existing entries are silently ignored.
As an alternative to the named parameters usage, you may pass in anExtUtils::Typemaps::InputMap object as first argument, a copy of which will be added to the typemap. In that case, only thereplace orskip named parameters may be used after the object. Example:
$map->add_inputmap($type_obj, replace => 1);Add anOUTPUT entry to the typemap. Works exactly the same asadd_inputmap.
Parses a string as a typemap and merge it into the typemap object.
Required named argument:string to specify the string to parse.
Removes aTYPEMAP entry from the typemap.
Required named argument:ctype to specify the entry to remove from the typemap.
Alternatively, you may pass a singleExtUtils::Typemaps::Type object.
Removes anINPUT entry from the typemap.
Required named argument:xstype to specify the entry to remove from the typemap.
Alternatively, you may pass a singleExtUtils::Typemaps::InputMap object.
Removes anOUTPUT entry from the typemap.
Required named argument:xstype to specify the entry to remove from the typemap.
Alternatively, you may pass a singleExtUtils::Typemaps::OutputMap object.
Fetches an entry of the TYPEMAP section of the typemap.
Mandatory named arguments: Thectype of the entry.
Returns theExtUtils::Typemaps::Type object for the entry if found.
Fetches an entry of the INPUT section of the typemap.
Mandatory named arguments: Thexstype of the entry or thectype of the typemap that can be used to find thexstype. To wit, the following pieces of code are equivalent:
my $type = $typemap->get_typemap(ctype => $ctype)my $input_map = $typemap->get_inputmap(xstype => $type->xstype);my $input_map = $typemap->get_inputmap(ctype => $ctype);Returns theExtUtils::Typemaps::InputMap object for the entry if found.
Fetches an entry of the OUTPUT section of the typemap.
Mandatory named arguments: Thexstype of the entry or thectype of the typemap that can be used to resolve thexstype. (See above for an example.)
Returns theExtUtils::Typemaps::InputMap object for the entry if found.
Write the typemap to a file. Optionally takes afile argument. If given, the typemap will be written to the specified file. If not, the typemap is written to the currently stored file name (see"file" above, this defaults to the file it was read from if any).
Generates and returns the string form of the typemap.
Generates and returns the string form of the typemap with the appropriate prefix around it for verbatim inclusion into an XS file as an embedded typemap. This will return a string like
TYPEMAP: <<END_OF_TYPEMAP... typemap here (see as_string) ...END_OF_TYPEMAPThe method takes care not to use a HERE-doc end marker that appears in the typemap string itself.
Merges a given typemap into the object. Note that a failed merge operation leaves the object in an inconsistent state so clone it if necessary.
Mandatory named arguments: Eithertypemap => $another_typemap_obj orfile => $path_to_typemap_file but not both.
Optional arguments:replace => 1 to force replacement of existing typemap entries without warning orskip => 1 to skip entries that exist already in the typemap.
Returns a bool indicating whether this typemap is entirely empty.
Returns a list of the C types that are mappable by this typemap object.
Returns a hash mapping the C types to the XS types:
{ 'char **' => 'T_PACKEDARRAY', 'bool_t' => 'T_IV', 'AV *' => 'T_AVREF', 'InputStream' => 'T_IN', 'double' => 'T_DOUBLE', # ...}This is documented because it is used byExtUtils::ParseXS, but it's not intended for general consumption. May be removed at any time.
Returns a hash mapping the XS types (identifiers) to the corresponding INPUT code:
{ 'T_CALLBACK' => ' $var = make_perl_cb_$type($arg)', 'T_OUT' => ' $var = IoOFP(sv_2io($arg))', 'T_REF_IV_PTR' => ' if (sv_isa($arg, \\"${ntype}\\")) { # ...}This is documented because it is used byExtUtils::ParseXS, but it's not intended for general consumption. May be removed at any time.
Returns a hash mapping the XS types (identifiers) to the corresponding OUTPUT code:
{ 'T_CALLBACK' => ' sv_setpvn($arg, $var.context.value().chp(), $var.context.value().size());', 'T_OUT' => ' { GV *gv = (GV *)sv_newmortal(); gv_init_pvn(gv, gv_stashpvs("$Package",1), "__ANONIO__",10,0); if ( do_open(gv, "+>&", 3, FALSE, 0, 0, $var) ) sv_setsv( $arg, sv_bless(newRV((SV*)gv), gv_stashpv("$Package",1)) ); else $arg = &PL_sv_undef; }', # ...}This is documented because it is used byExtUtils::ParseXS, but it's not intended for general consumption. May be removed at any time.
Returns a hash mapping the C types of the typemap to their corresponding prototypes.
{ 'char **' => '$', 'bool_t' => '$', 'AV *' => '$', 'InputStream' => '$', 'double' => '$', # ...}This is documented because it is used byExtUtils::ParseXS, but it's not intended for general consumption. May be removed at any time.
Creates and returns a clone of a full typemaps object.
Takes named parameters: Ifshallow is true, the clone will share the actual individual type/input/outputmap objects, but not share their storage. Use with caution. Withoutshallow, the clone will be fully independent.
Function to (heuristically) canonicalize a C type in terms of white space. Works to some degree with C++ types. For example,
$halfway_canonical_type = tidy_type(' int * * const * ');returns'int ** const *'.
Moved fromExtUtils::ParseXS.
Inherits some evil code fromExtUtils::ParseXS.
The parser is heavily inspired from the one inExtUtils::ParseXS.
For details on typemaps:perlxstut,perlxs.
Steffen Mueller<smueller@cpan.org>
Copyright 2009, 2010, 2011, 2012, 2013 Steffen Mueller
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via theGitHub issue tracker oremail regarding any issues with the site itself, search, or rendering of documentation.
The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via thePerl issue tracker, themailing list, orIRC to report any issues with the contents or format of the documentation.