内容

名称

ExtUtils::Typemaps - 读取/写入/修改 Perl/XS 类型映射文件

概要

# read/create file
my $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);

描述

此模块可以读取、修改、创建和写入 Perl XS 类型映射文件。如果您不知道什么是类型映射，请参阅 perlxstut 和 perlxs 手册。

该模块并非完全双向兼容：例如，它目前只是简单地删除所有注释。但是，映射中条目的顺序将被保留。

我们检查类型映射中是否存在重复条目，但不会检查 INPUTMAP 或 OUTPUTMAP 条目是否缺少 TYPEMAP 条目，因为这些条目可能隐藏在其他类型映射中。

方法

new

返回一个新的类型映射对象。接受一个可选的 file 参数。如果设置了该参数，则将读取给定的文件。如果文件不存在，则返回一个空的类型映射。

或者，如果提供了string参数，则会解析提供的字符串而不是文件。

file

获取/设置当调用write方法时类型映射写入的文件。

add_typemap

向类型映射添加TYPEMAP条目。

必需的命名参数：ctype（例如ctype => 'double'）和xstype（例如xstype => 'T_NV'）。

可选命名参数：replace => 1 强制删除/替换具有相同ctype的现有TYPEMAP条目。skip => 1 触发“先到先得”逻辑，通过该逻辑，与现有条目冲突的新条目将被静默忽略。

作为命名参数使用方式的替代方案，您可以将ExtUtils::Typemaps::Type对象作为第一个参数传递，该对象的副本将被添加到类型映射中。在这种情况下，只有replace或skip命名参数可以在对象之后使用。示例

$map->add_typemap($type_obj, replace => 1);

add_inputmap

向类型映射添加INPUT条目。

必需的命名参数：xstype（例如xstype => 'T_NV'）和与其关联的输入code。

可选命名参数：replace => 1 强制删除/替换具有相同xstype的现有INPUT条目。skip => 1 触发“先到先得”逻辑，通过该逻辑，与现有条目冲突的新条目将被静默忽略。

作为命名参数使用方式的替代方案，您可以将ExtUtils::Typemaps::InputMap对象作为第一个参数传递，该对象的副本将被添加到类型映射中。在这种情况下，只有replace或skip命名参数可以在对象之后使用。示例

$map->add_inputmap($type_obj, replace => 1);

add_outputmap

向类型映射添加OUTPUT条目。与add_inputmap的工作方式完全相同。

add_string

将字符串解析为类型映射并将其合并到类型映射对象中。

必需的命名参数：string，用于指定要解析的字符串。

remove_typemap

从类型映射中删除TYPEMAP条目。

必需的命名参数：ctype，用于指定要从类型映射中删除的条目。

或者，您可以传递一个ExtUtils::Typemaps::Type对象。

remove_inputmap

从类型映射中移除一个 INPUT 条目。

必需的命名参数：xstype，用于指定要从类型映射中移除的条目。

或者，您可以传递一个 ExtUtils::Typemaps::InputMap 对象。

remove_outputmap

从类型映射中移除一个 OUTPUT 条目。

必需的命名参数：xstype，用于指定要从类型映射中移除的条目。

或者，您可以传递一个 ExtUtils::Typemaps::OutputMap 对象。

get_typemap

获取类型映射 TYPEMAP 部分的条目。

必需的命名参数：条目的 ctype。

如果找到，则返回条目的 ExtUtils::Typemaps::Type 对象。

get_inputmap

获取类型映射 INPUT 部分的条目。

必需的命名参数：条目的 xstype 或可用于查找 xstype 的类型映射的 ctype。也就是说，以下代码片段是等效的

my $type = $typemap->get_typemap(ctype => $ctype)
my $input_map = $typemap->get_inputmap(xstype => $type->xstype);

my $input_map = $typemap->get_inputmap(ctype => $ctype);

如果找到，则返回条目的 ExtUtils::Typemaps::InputMap 对象。

get_outputmap

获取类型映射 OUTPUT 部分的条目。

必需的命名参数：条目的 xstype 或可用于解析 xstype 的类型映射的 ctype。（有关示例，请参见上文。）

如果找到，则返回条目的 ExtUtils::Typemaps::InputMap 对象。

write

将类型映射写入文件。可以选择接受 file 参数。如果给出，类型映射将写入指定的文件。如果没有，类型映射将写入当前存储的文件名（参见上面的 "file"，默认情况下为从其读取的文件，如果有）。

as_string

生成并返回类型映射的字符串形式。

as_embedded_typemap

生成并返回类型映射的字符串形式，并在其周围加上适当的前缀，以便将其逐字包含到 XS 文件中作为嵌入式类型映射。这将返回一个类似于以下内容的字符串

TYPEMAP: <<END_OF_TYPEMAP
... typemap here (see as_string) ...
END_OF_TYPEMAP

该方法注意不要使用出现在类型映射字符串本身中的 HERE-doc 结束标记。

merge

将给定的类型映射合并到对象中。请注意，合并操作失败会导致对象处于不一致状态，因此如有必要请克隆它。

必填命名参数：typemap => $another_typemap_obj 或 file => $path_to_typemap_file，但不能同时使用两者。

可选参数：replace => 1 强制替换现有类型映射条目，不发出警告；skip => 1 跳过类型映射中已存在的条目。

is_empty

返回一个布尔值，指示此类型映射是否完全为空。

list_mapped_ctypes

返回此类型映射对象可映射的 C 类型列表。

_get_typemap_hash

返回一个哈希表，将 C 类型映射到 XS 类型。

{
  'char **' => 'T_PACKEDARRAY',
  'bool_t' => 'T_IV',
  'AV *' => 'T_AVREF',
  'InputStream' => 'T_IN',
  'double' => 'T_DOUBLE',
  # ...
}

这是有文档记录的，因为它被 ExtUtils::ParseXS 使用，但它不适合一般使用。可能会随时删除。

_get_inputmap_hash

返回一个哈希表，将 XS 类型（标识符）映射到相应的 INPUT 代码。

{
  'T_CALLBACK' => '   $var = make_perl_cb_$type($arg)
',
  'T_OUT' => '    $var = IoOFP(sv_2io($arg))
',
  'T_REF_IV_PTR' => '   if (sv_isa($arg, \\"${ntype}\\")) {
  # ...
}

这是有文档记录的，因为它被 ExtUtils::ParseXS 使用，但它不适合一般使用。可能会随时删除。

_get_outputmap_hash

返回一个哈希表，将 XS 类型（标识符）映射到相应的 OUTPUT 代码。

{
  '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;
       }
',
  # ...
}

这是有文档记录的，因为它被 ExtUtils::ParseXS 使用，但它不适合一般使用。可能会随时删除。

_get_prototype_hash

返回一个哈希表，将类型映射的 C 类型映射到其相应的原型。

{
  'char **' => '$',
  'bool_t' => '$',
  'AV *' => '$',
  'InputStream' => '$',
  'double' => '$',
  # ...
}

这是有文档记录的，因为它被 ExtUtils::ParseXS 使用，但它不适合一般使用。可能会随时删除。

clone

创建并返回完整类型映射对象的克隆。

接受命名参数：如果 shallow 为真，克隆将共享实际的单个类型/输入/输出映射对象，但不共享其存储。谨慎使用。如果没有 shallow，克隆将完全独立。

tidy_type

用于（启发式地）规范化 C 类型的函数。在一定程度上适用于 C++ 类型。

$halfway_canonical_type = tidy_type($ctype);

从 ExtUtils::ParseXS 移动。

CAVEATS

继承了 ExtUtils::ParseXS 中的一些恶意代码。

SEE ALSO

解析器很大程度上借鉴了 ExtUtils::ParseXS 中的解析器。

有关类型映射的详细信息：perlxstut，perlxs。

作者

Steffen Mueller <[email protected]>

版权 & 许可

版权所有 2009, 2010, 2011, 2012, 2013 Steffen Mueller

本程序是自由软件；您可以根据与 Perl 本身相同的条款重新发布和/或修改它。