{ "content": [ { "type": "text", "text": "# ExtUtils::Typemaps (perldoc)\n\n## NAME\n\nExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files\n\n## SYNOPSIS\n\n# read/create file\nmy $typemap = ExtUtils::Typemaps->new(file => 'typemap');\n# alternatively create an in-memory typemap\n# $typemap = ExtUtils::Typemaps->new();\n# alternatively create an in-memory typemap by parsing a string\n# $typemap = ExtUtils::Typemaps->new(string => $sometypemap);\n# add a mapping\n$typemap->addtypemap(ctype => 'NV', xstype => 'TNV');\n$typemap->addinputmap(\nxstype => 'TNV', code => '$var = ($type)SvNV($arg);'\n);\n$typemap->addoutputmap(\nxstype => 'TNV', code => 'svsetnv($arg, (NV)$var);'\n);\n$typemap->addstring(string => $typemapstring);\n# will be parsed and merged\n# remove a mapping (same for removetypemap and removeoutputmap...)\n$typemap->removeinputmap(xstype => 'SomeType');\n# save a typemap to a file\n$typemap->write(file => 'anotherfile.map');\n# merge the other typemap into this one\n$typemap->merge(typemap => $anothertypemap);\n\n## DESCRIPTION\n\nThis module can read, modify, create and write Perl XS typemap files. If you don't know what a\ntypemap is, please confer the perlxstut and perlxs manuals.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **CAVEATS**\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "ExtUtils::Typemaps", "section": "", "mode": "perldoc", "summary": "ExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files", "synopsis": "# read/create file\nmy $typemap = ExtUtils::Typemaps->new(file => 'typemap');\n# alternatively create an in-memory typemap\n# $typemap = ExtUtils::Typemaps->new();\n# alternatively create an in-memory typemap by parsing a string\n# $typemap = ExtUtils::Typemaps->new(string => $sometypemap);\n# add a mapping\n$typemap->addtypemap(ctype => 'NV', xstype => 'TNV');\n$typemap->addinputmap(\nxstype => 'TNV', code => '$var = ($type)SvNV($arg);'\n);\n$typemap->addoutputmap(\nxstype => 'TNV', code => 'svsetnv($arg, (NV)$var);'\n);\n$typemap->addstring(string => $typemapstring);\n# will be parsed and merged\n# remove a mapping (same for removetypemap and removeoutputmap...)\n$typemap->removeinputmap(xstype => 'SomeType');\n# save a typemap to a file\n$typemap->write(file => 'anotherfile.map');\n# merge the other typemap into this one\n$typemap->merge(typemap => $anothertypemap);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 27, "subsections": [] }, { "name": "DESCRIPTION", "lines": 9, "subsections": [] }, { "name": "METHODS", "lines": 220, "subsections": [] }, { "name": "CAVEATS", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] }, { "name": "AUTHOR", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "ExtUtils::Typemaps - Read/Write/Modify Perl/XS typemap files\n", "subsections": [] }, "SYNOPSIS": { "content": "# read/create file\nmy $typemap = ExtUtils::Typemaps->new(file => 'typemap');\n# alternatively create an in-memory typemap\n# $typemap = ExtUtils::Typemaps->new();\n# alternatively create an in-memory typemap by parsing a string\n# $typemap = ExtUtils::Typemaps->new(string => $sometypemap);\n\n# add a mapping\n$typemap->addtypemap(ctype => 'NV', xstype => 'TNV');\n$typemap->addinputmap(\nxstype => 'TNV', code => '$var = ($type)SvNV($arg);'\n);\n$typemap->addoutputmap(\nxstype => 'TNV', code => 'svsetnv($arg, (NV)$var);'\n);\n$typemap->addstring(string => $typemapstring);\n# will be parsed and merged\n\n# remove a mapping (same for removetypemap and removeoutputmap...)\n$typemap->removeinputmap(xstype => 'SomeType');\n\n# save a typemap to a file\n$typemap->write(file => 'anotherfile.map');\n\n# merge the other typemap into this one\n$typemap->merge(typemap => $anothertypemap);\n", "subsections": [] }, "DESCRIPTION": { "content": "This module can read, modify, create and write Perl XS typemap files. If you don't know what a\ntypemap is, please confer the perlxstut and perlxs manuals.\n\nThe module is not entirely round-trip safe: For example it currently simply strips all comments.\nThe order of entries in the maps is, however, preserved.\n\nWe check for duplicate entries in the typemap, but do not check for missing \"TYPEMAP\" entries\nfor \"INPUTMAP\" or \"OUTPUTMAP\" entries since these might be hidden in a different typemap.\n", "subsections": [] }, "METHODS": { "content": "new\nReturns a new typemap object. Takes an optional \"file\" parameter. If set, the given file will be\nread. If the file doesn't exist, an empty typemap is returned.\n\nAlternatively, if the \"string\" parameter is given, the supplied string will be parsed instead of\na file.\n\nfile\nGet/set the file that the typemap is written to when the \"write\" method is called.\n\naddtypemap\nAdd a \"TYPEMAP\" entry to the typemap.\n\nRequired named arguments: The \"ctype\" (e.g. \"ctype => 'double'\") and the \"xstype\" (e.g. \"xstype\n=> 'TNV'\").\n\nOptional named arguments: \"replace => 1\" forces removal/replacement of existing \"TYPEMAP\"\nentries of the same \"ctype\". \"skip => 1\" triggers a *\"first come first serve\"* logic by which\nnew entries that conflict with existing entries are silently ignored.\n\nAs an alternative to the named parameters usage, you may pass in an \"ExtUtils::Typemaps::Type\"\nobject as first argument, a copy of which will be added to the typemap. In that case, only the\n\"replace\" or \"skip\" named parameters may be used after the object. Example:\n\n$map->addtypemap($typeobj, replace => 1);\n\naddinputmap\nAdd an \"INPUT\" entry to the typemap.\n\nRequired named arguments: The \"xstype\" (e.g. \"xstype => 'TNV'\") and the \"code\" to associate\nwith it for input.\n\nOptional named arguments: \"replace => 1\" forces removal/replacement of existing \"INPUT\" entries\nof the same \"xstype\". \"skip => 1\" triggers a *\"first come first serve\"* logic by which new\nentries that conflict with existing entries are silently ignored.\n\nAs an alternative to the named parameters usage, you may pass in an\n\"ExtUtils::Typemaps::InputMap\" object as first argument, a copy of which will be added to the\ntypemap. In that case, only the \"replace\" or \"skip\" named parameters may be used after the\nobject. Example:\n\n$map->addinputmap($typeobj, replace => 1);\n\naddoutputmap\nAdd an \"OUTPUT\" entry to the typemap. Works exactly the same as \"addinputmap\".\n\naddstring\nParses a string as a typemap and merge it into the typemap object.\n\nRequired named argument: \"string\" to specify the string to parse.\n\nremovetypemap\nRemoves a \"TYPEMAP\" entry from the typemap.\n\nRequired named argument: \"ctype\" to specify the entry to remove from the typemap.\n\nAlternatively, you may pass a single \"ExtUtils::Typemaps::Type\" object.\n\nremoveinputmap\nRemoves an \"INPUT\" entry from the typemap.\n\nRequired named argument: \"xstype\" to specify the entry to remove from the typemap.\n\nAlternatively, you may pass a single \"ExtUtils::Typemaps::InputMap\" object.\n\nremoveinputmap\nRemoves an \"OUTPUT\" entry from the typemap.\n\nRequired named argument: \"xstype\" to specify the entry to remove from the typemap.\n\nAlternatively, you may pass a single \"ExtUtils::Typemaps::OutputMap\" object.\n\ngettypemap\nFetches an entry of the TYPEMAP section of the typemap.\n\nMandatory named arguments: The \"ctype\" of the entry.\n\nReturns the \"ExtUtils::Typemaps::Type\" object for the entry if found.\n\ngetinputmap\nFetches an entry of the INPUT section of the typemap.\n\nMandatory named arguments: The \"xstype\" of the entry or the \"ctype\" of the typemap that can be\nused to find the \"xstype\". To wit, the following pieces of code are equivalent:\n\nmy $type = $typemap->gettypemap(ctype => $ctype)\nmy $inputmap = $typemap->getinputmap(xstype => $type->xstype);\n\nmy $inputmap = $typemap->getinputmap(ctype => $ctype);\n\nReturns the \"ExtUtils::Typemaps::InputMap\" object for the entry if found.\n\ngetoutputmap\nFetches an entry of the OUTPUT section of the typemap.\n\nMandatory named arguments: The \"xstype\" of the entry or the \"ctype\" of the typemap that can be\nused to resolve the \"xstype\". (See above for an example.)\n\nReturns the \"ExtUtils::Typemaps::InputMap\" object for the entry if found.\n\nwrite\nWrite the typemap to a file. Optionally takes a \"file\" argument. If given, the typemap will be\nwritten to the specified file. If not, the typemap is written to the currently stored file name\n(see \"file\" above, this defaults to the file it was read from if any).\n\nasstring\nGenerates and returns the string form of the typemap.\n\nasembeddedtypemap\nGenerates and returns the string form of the typemap with the appropriate prefix around it for\nverbatim inclusion into an XS file as an embedded typemap. This will return a string like\n\nTYPEMAP: < $anothertypemapobj\" or \"file =>\n$pathtotypemapfile\" but not both.\n\nOptional arguments: \"replace => 1\" to force replacement of existing typemap entries without\nwarning or \"skip => 1\" to skip entries that exist already in the typemap.\n\nisempty\nReturns a bool indicating whether this typemap is entirely empty.\n\nlistmappedctypes\nReturns a list of the C types that are mappable by this typemap object.\n\ngettypemaphash\nReturns a hash mapping the C types to the XS types:\n\n{\n'char ' => 'TPACKEDARRAY',\n'boolt' => 'TIV',\n'AV *' => 'TAVREF',\n'InputStream' => 'TIN',\n'double' => 'TDOUBLE',\n# ...\n}\n\nThis is documented because it is used by \"ExtUtils::ParseXS\", but it's not intended for general\nconsumption. May be removed at any time.\n\ngetinputmaphash\nReturns a hash mapping the XS types (identifiers) to the corresponding INPUT code:\n\n{\n'TCALLBACK' => ' $var = makeperlcb$type($arg)\n',\n'TOUT' => ' $var = IoOFP(sv2io($arg))\n',\n'TREFIVPTR' => ' if (svisa($arg, \\\\\"${ntype}\\\\\")) {\n# ...\n}\n\nThis is documented because it is used by \"ExtUtils::ParseXS\", but it's not intended for general\nconsumption. May be removed at any time.\n\ngetoutputmaphash\nReturns a hash mapping the XS types (identifiers) to the corresponding OUTPUT code:\n\n{\n'TCALLBACK' => ' svsetpvn($arg, $var.context.value().chp(),\n$var.context.value().size());\n',\n'TOUT' => ' {\nGV *gv = (GV *)svnewmortal();\ngvinitpvn(gv, gvstashpvs(\"$Package\",1),\n\"ANONIO\",10,0);\nif ( doopen(gv, \"+>&\", 3, FALSE, 0, 0, $var) )\nsvsetsv(\n$arg,\nsvbless(newRV((SV*)gv), gvstashpv(\"$Package\",1))\n);\nelse\n$arg = &PLsvundef;\n}\n',\n# ...\n}\n\nThis is documented because it is used by \"ExtUtils::ParseXS\", but it's not intended for general\nconsumption. May be removed at any time.\n\ngetprototypehash\nReturns a hash mapping the C types of the typemap to their corresponding prototypes.\n\n{\n'char ' => '$',\n'boolt' => '$',\n'AV *' => '$',\n'InputStream' => '$',\n'double' => '$',\n# ...\n}\n\nThis is documented because it is used by \"ExtUtils::ParseXS\", but it's not intended for general\nconsumption. May be removed at any time.\n\nclone\nCreates and returns a clone of a full typemaps object.\n\nTakes named parameters: If \"shallow\" is true, the clone will share the actual individual\ntype/input/outputmap objects, but not share their storage. Use with caution. Without \"shallow\",\nthe clone will be fully independent.\n\ntidytype\nFunction to (heuristically) canonicalize a C type. Works to some degree with C++ types.\n\n$halfwaycanonicaltype = tidytype($ctype);\n\nMoved from \"ExtUtils::ParseXS\".\n", "subsections": [] }, "CAVEATS": { "content": "Inherits some evil code from \"ExtUtils::ParseXS\".\n", "subsections": [] }, "SEE ALSO": { "content": "The parser is heavily inspired from the one in ExtUtils::ParseXS.\n\nFor details on typemaps: perlxstut, perlxs.\n", "subsections": [] }, "AUTHOR": { "content": "Steffen Mueller \"\n\nCOPYRIGHT & LICENSE\nCopyright 2009, 2010, 2011, 2012, 2013 Steffen Mueller\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] } } } }