ExtUtils::Typemaps

(原始碼, CPAN)

版本 3.51

內容

名稱
語法
說明
方法
注意事項
另請參閱
作者
版權與授權

#名稱

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 手冊。

此模組並非完全可逆：例如，它目前僅會移除所有註解。不過，映射中條目的順序會被保留。

我們會檢查類型映射中是否有重複條目，但不會檢查 TYPEMAP 條目中是否有遺漏的 INPUTMAP 或 OUTPUTMAP 條目，因為這些條目可能隱藏在不同的類型映射中。

#方法

#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 文件結束標記。

#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

傳回對應 typemap 的 C 類型至其對應原型之雜湊。

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

這有文件記載，因為它是由 ExtUtils::ParseXS 使用，但它並非供一般使用。可能會隨時移除。

#clone

建立並傳回完整 typemaps 物件的複製。

採用命名參數：如果 shallow 為 true，複製將共用實際的個別類型/輸入/輸出地圖物件，但不會共用其儲存空間。請小心使用。如果沒有 shallow，複製將完全獨立。

#tidy_type

用於（啟發式地）正規化 C 類型的函式。在某種程度上適用於 C++ 類型。

$halfway_canonical_type = tidy_type($ctype);

從 ExtUtils::ParseXS 移入。

#CAVEATS

繼承自 ExtUtils::ParseXS 的部分邪惡程式碼。

#另請參閱

此剖析器在很大程度上受到 ExtUtils::ParseXS 中剖析器的啟發。

有關 typemaps 的詳細資訊：perlxstut、perlxs。

#作者

Steffen Mueller <smueller@cpan.org>

#著作權和授權

著作權所有 2009、2010、2011、2012、2013 Steffen Mueller

此程式為免費軟體；您可以在與 Perl 相同的條款下重新散布或修改它。