{ "mode": "perldoc", "parameter": "XML::Twig", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/XML%3A%3ATwig/json", "generated": "2026-06-10T17:23:00Z", "synopsis": "Note that this documentation is intended as a reference to the module.\nComplete docs, including a tutorial, examples, an easier to use HTML version, a quick reference\ncard and a FAQ are available at \nSmall documents (loaded in memory as a tree):\nmy $twig=XML::Twig->new(); # create the twig\n$twig->parsefile( 'doc.xml'); # build it\nmyprocess( $twig); # use twig methods to process it\n$twig->print; # output the twig\nHuge documents (processed in combined stream/tree mode):\n# at most one div will be loaded in memory\nmy $twig=XML::Twig->new(\ntwighandlers =>\n{ title => sub { $->settag( 'h2') }, # change title tags to h2\n# $ is the current element\npara => sub { $->settag( 'p') }, # change para to p\nhidden => sub { $->delete; }, # remove hidden elements\nlist => \\&mylistprocess, # process list elements\ndiv => sub { $[0]->flush; }, # output and free memory\n},\nprettyprint => 'indented', # output will be nicely formatted\nemptytags => 'html', # outputs \n);\n$twig->parsefile( 'mybig.xml');\nsub mylistprocess\n{ my( $twig, $list)= @;\n# ...\n}\nSee XML::Twig 101 for other ways to use the module, as a filter for example.", "sections": { "NAME": { "content": "XML::Twig - A perl module for processing huge XML documents in tree mode.\n", "subsections": [] }, "SYNOPSIS": { "content": "Note that this documentation is intended as a reference to the module.\n\nComplete docs, including a tutorial, examples, an easier to use HTML version, a quick reference\ncard and a FAQ are available at \n\nSmall documents (loaded in memory as a tree):\n\nmy $twig=XML::Twig->new(); # create the twig\n$twig->parsefile( 'doc.xml'); # build it\nmyprocess( $twig); # use twig methods to process it\n$twig->print; # output the twig\n\nHuge documents (processed in combined stream/tree mode):\n\n# at most one div will be loaded in memory\nmy $twig=XML::Twig->new(\ntwighandlers =>\n{ title => sub { $->settag( 'h2') }, # change title tags to h2\n# $ is the current element\npara => sub { $->settag( 'p') }, # change para to p\nhidden => sub { $->delete; }, # remove hidden elements\nlist => \\&mylistprocess, # process list elements\ndiv => sub { $[0]->flush; }, # output and free memory\n},\nprettyprint => 'indented', # output will be nicely formatted\nemptytags => 'html', # outputs \n);\n$twig->parsefile( 'mybig.xml');\n\nsub mylistprocess\n{ my( $twig, $list)= @;\n# ...\n}\n\nSee XML::Twig 101 for other ways to use the module, as a filter for example.\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides a way to process XML documents. It is build on top of \"XML::Parser\".\n\nThe module offers a tree interface to the document, while allowing you to output the parts of it\nthat have been completely processed.\n\nIt allows minimal resource (CPU and memory) usage by building the tree only for the parts of the\ndocuments that need actual processing, through the use of the \"twigroots \" and\n\"twigprintoutsideroots \" options. The \"finish \" and \"finishprint \" methods also help to\nincrease performances.\n\nXML::Twig tries to make simple things easy so it tries its best to takes care of a lot of the\n(usually) annoying (but sometimes necessary) features that come with XML and XML::Parser.\n", "subsections": [] }, "TOOLS": { "content": "XML::Twig comes with a few command-line utilities:\n\nxmlpp - xml pretty-printer\nXML pretty printer using XML::Twig\n\nxmlgrep - grep XML files looking for specific elements\n\"xmlgrep\" does a grep on XML files. Instead of using regular expressions it uses XPath\nexpressions (in fact the subset of XPath supported by XML::Twig).\n\nxmlsplit - cut a big XML file into smaller chunks\n\"xmlsplit\" takes a (presumably big) XML file and split it in several smaller files, based on\nvarious criteria (level in the tree, size or an XPath expression)\n\nxmlmerge - merge back XML files split with xmlsplit\n\"xmlmerge\" takes several xml files that have been split using \"xmlsplit\" and recreates a\nsingle file.\n\nxmlspellcheck - spellcheck XML files\n\"xmlspellcheck\" lets you spell check the content of an XML file. It extracts the text (the\ncontent of elements and optionally of attributes), call a spell checker on it and then recreates\nthe XML document.\n\nXML::Twig 101\nXML::Twig can be used either on \"small\" XML documents (that fit in memory) or on huge ones, by\nprocessing parts of the document and outputting or discarding them once they are processed.\n", "subsections": [ { "name": "Loading an XML document and processing it", "content": "my $t= XML::Twig->new();\n$t->parse( 'titlep 1p 2');\nmy $root= $t->root;\n$root->settag( 'html'); # change doc to html\n$title= $root->firstchild( 'title'); # get the title\n$title->settag( 'h1'); # turn it into h1\nmy @para= $root->children( 'para'); # get the para children\nforeach my $para (@para)\n{ $para->settag( 'p'); } # turn them into p\n$t->print; # output the document\n\nOther useful methods include:\n\natt: \"$elt->{'att'}->{'foo'}\" return the \"foo\" attribute for an element,\n\nsetatt : \"$elt->setatt( foo => \"bar\")\" sets the \"foo\" attribute to the \"bar\" value,\n\nnextsibling: \"$elt->{nextsibling}\" return the next sibling in the document (in the example\n\"$title->{nextsibling}\" is the first \"para\", you can also (and actually should) use\n\"$elt->nextsibling( 'para')\" to get it\n\nThe document can also be transformed through the use of the cut, copy, paste and move methods:\n\"$title->cut; $title->paste( after => $p);\" for example\n\nAnd much, much more, see XML::Twig::Elt.\n" }, { "name": "Processing an XML document chunk by chunk", "content": "One of the strengths of XML::Twig is that it let you work with files that do not fit in memory\n(BTW storing an XML document in memory as a tree is quite memory-expensive, the expansion factor\nbeing often around 10).\n\nTo do this you can define handlers, that will be called once a specific element has been\ncompletely parsed. In these handlers you can access the element and process it as you see fit,\nusing the navigation and the cut-n-paste methods, plus lots of convenient ones like \"prefix \".\nOnce the element is completely processed you can then \"flush \" it, which will output it and free\nthe memory. You can also \"purge \" it if you don't need to output it (if you are just extracting\nsome data from the document for example). The handler will be called again once the next\nrelevant element has been parsed.\n\nmy $t= XML::Twig->new( twighandlers =>\n{ section => \\§ion,\npara => sub { $->settag( 'p'); }\n},\n);\n$t->parsefile( 'doc.xml');\n\n# the handler is called once a section is completely parsed, ie when\n# the end tag for section is found, it receives the twig itself and\n# the element (including all its sub-elements) as arguments\nsub section\n{ my( $t, $section)= @; # arguments for all twighandlers\n$section->settag( 'div'); # change the tag name\n# let's use the attribute nb as a prefix to the title\nmy $title= $section->firstchild( 'title'); # find the title\nmy $nb= $title->{'att'}->{'nb'}; # get the attribute\n$title->prefix( \"$nb - \"); # easy isn't it?\n$section->flush; # outputs the section and frees memory\n}\n\nThere is of course more to it: you can trigger handlers on more elaborate conditions than just\nthe name of the element, \"section/title\" for example.\n\nmy $t= XML::Twig->new( twighandlers =>\n{ 'section/title' => sub { $->print } }\n)\n->parsefile( 'doc.xml');\n\nHere \"sub { $->print }\" simply prints the current element ($ is aliased to the element in the\nhandler).\n\nYou can also trigger a handler on a test on an attribute:\n\nmy $t= XML::Twig->new( twighandlers =>\n{ 'section[@level=\"1\"]' => sub { $->print } }\n);\n->parsefile( 'doc.xml');\n\nYou can also use \"starttaghandlers \" to process an element as soon as the start tag is found.\nBesides \"prefix \" you can also use \"suffix \",\n" }, { "name": "Processing just parts of an XML document", "content": "The twigroots mode builds only the required sub-trees from the document Anything outside of the\ntwig roots will just be ignored:\n\nmy $t= XML::Twig->new(\n# the twig will include just the root and selected titles\ntwigroots => { 'section/title' => \\&printnpurge,\n'annex/title' => \\&printnpurge\n}\n);\n$t->parsefile( 'doc.xml');\n\nsub printnpurge\n{ my( $t, $elt)= @;\nprint $elt->text; # print the text (including sub-element texts)\n$t->purge; # frees the memory\n}\n\nYou can use that mode when you want to process parts of a documents but are not interested in\nthe rest and you don't want to pay the price, either in time or memory, to build the tree for\nthe it.\n" }, { "name": "Building an XML filter", "content": "You can combine the \"twigroots\" and the \"twigprintoutsideroots\" options to build filters,\nwhich let you modify selected elements and will output the rest of the document as is.\n\nThis would convert prices in $ to prices in Euro in a document:\n\nmy $t= XML::Twig->new(\ntwigroots => { 'price' => \\&convert, }, # process prices\ntwigprintoutsideroots => 1, # print the rest\n);\n$t->parsefile( 'doc.xml');\n\nsub convert\n{ my( $t, $price)= @;\nmy $currency= $price->{'att'}->{'currency'}; # get the currency\nif( $currency eq 'USD')\n{ $usdprice= $price->text; # get the price\n# %rate is just a conversion table\nmy $europrice= $usdprice * $rate{usd2euro};\n$price->settext( $europrice); # set the new price\n$price->setatt( currency => 'EUR'); # don't forget this!\n}\n$price->print; # output the price\n}\n\nXML::Twig and various versions of Perl, XML::Parser and expat:\nXML::Twig is a lot more sensitive to variations in versions of perl, XML::Parser and expat than\nto the OS, so this should cover some reasonable configurations.\n\nThe \"recommended configuration\" is perl 5.8.3+ (for good Unicode support), XML::Parser 2.31+ and\nexpat 1.95.5+\n\nSee for the CPAN testers reports on\nXML::Twig, which list all tested configurations.\n\nAn Atom feed of the CPAN Testers results is available at\n\n\nFinally:\n\nXML::Twig does NOT work with expat 1.95.4\nXML::Twig only works with XML::Parser 2.27 in perl 5.6.*\nNote that I can't compile XML::Parser 2.27 anymore, so I can't guarantee that it still works\n\nXML::Parser 2.28 does not really work\n\nWhen in doubt, upgrade expat, XML::Parser and Scalar::Util\n\nFinally, for some optional features, XML::Twig depends on some additional modules. The complete\nlist, which depends somewhat on the version of Perl that you are running, is given by running\n\"t/zzdumpconfig.t\"\n" } ] }, "Simplifying XML processing": { "content": "Whitespaces\nWhitespaces that look non-significant are discarded, this behaviour can be controlled using\nthe \"keepspaces \", \"keepspacesin \" and \"discardspacesin \" options.\n\nEncoding\nYou can specify that you want the output in the same encoding as the input (provided you\nhave valid XML, which means you have to specify the encoding either in the document or when\nyou create the Twig object) using the \"keepencoding \" option\n\nYou can also use \"outputencoding\" to convert the internal UTF-8 format to the required\nencoding.\n\nComments and Processing Instructions (PI)\nComments and PI's can be hidden from the processing, but still appear in the output (they\nare carried by the \"real\" element closer to them)\n\nPretty Printing\nXML::Twig can output the document pretty printed so it is easier to read for us humans.\n\nSurviving an untimely death\nXML parsers are supposed to react violently when fed improper XML. XML::Parser just dies.\n\nXML::Twig provides the \"safeparse \" and the \"safeparsefile \" methods which wrap the parse\nin an eval and return either the parsed twig or 0 in case of failure.\n\nPrivate attributes\nAttributes with a name starting with # (illegal in XML) will not be output, so you can\nsafely use them to store temporary values during processing. Note that you can store\nanything in a private attribute, not just text, it's just a regular Perl variable, so a\nreference to an object or a huge data structure is perfectly fine.\n", "subsections": [] }, "CLASSES": { "content": "XML::Twig uses a very limited number of classes. The ones you are most likely to use are\n\"XML::Twig\" of course, which represents a complete XML document, including the document itself\n(the root of the document itself is \"root\"), its handlers, its input or output filters... The\nother main class is \"XML::Twig::Elt\", which models an XML element. Element here has a very wide\ndefinition: it can be a regular element, or but also text, with an element \"tag\" of \"#PCDATA\"\n(or \"#CDATA\"), an entity (tag is \"#ENT\"), a Processing Instruction (\"#PI\"), a comment\n(\"#COMMENT\").\n\nThose are the 2 commonly used classes.\n\nYou might want to look the \"eltclass\" option if you want to subclass \"XML::Twig::Elt\".\n\nAttributes are just attached to their parent element, they are not objects per se. (Please use\nthe provided methods \"att\" and \"setatt\" to access them, if you access them as a hash, then your\ncode becomes implementation dependent and might break in the future).\n\nOther classes that are seldom used are \"XML::Twig::Entitylist\" and \"XML::Twig::Entity\".\n\nIf you use \"XML::Twig::XPath\" instead of \"XML::Twig\", elements are then created as\n\"XML::Twig::XPath::Elt\"\n", "subsections": [] }, "METHODS": { "content": "XML::Twig\nA twig is a subclass of XML::Parser, so all XML::Parser methods can be called on a twig object,\nincluding parse and parsefile. \"setHandlers\" on the other hand cannot be used, see \"BUGS \"\n\nnew This is a class method, the constructor for XML::Twig. Options are passed as keyword value\npairs. Recognized options are the same as XML::Parser, plus some (in fact a lot!) XML::Twig\nspecifics.\n\nNew Options:\n\ntwighandlers\nThis argument consists of a hash \"{ expression =\" \\&handler}> where expression is a an\n*XPath-like expression* (+ some others).\n\nXPath expressions are limited to using the child and descendant axis (indeed you can't\nspecify an axis), and predicates cannot be nested. You can use the \"string\", or\n\"string()\" function (except in \"twigroots\" triggers).\n\nAdditionally you can use regexps (/ delimited) to match attribute and string values.\n\nExamples:\n\nfoo\nfoo/bar\nfoo//bar\n/foo/bar\n/foo//bar\n/foo/bar[@att1 = \"val1\" and @att2 = \"val2\"]/baz[@a >= 1]\nfoo[string()=~ /^duh!+/]\n/foo[string(bar)=~ /\\d+/]/baz[@att != 3]\n\n#CDATA can be used to call a handler for a CDATA section. #COMMENT can be used to call a\nhandler for comments\n\nSome additional (non-XPath) expressions are also provided for convenience:\n\nprocessing instructions\n'?' or '#PI' triggers the handler for any processing instruction, and '?' or\n'#PI ' triggers a handler for processing instruction with the given target(\nex: '#PI xml-stylesheet').\n\nlevel()\nTriggers the handler on any element at that level in the tree (root is level 1)\n\nall\nTriggers the handler for all elements in the tree\n\ndefault\nTriggers the handler for each element that does NOT have any other handler.\n\nExpressions are evaluated against the input document. Which means that even if you have\nchanged the tag of an element (changing the tag of a parent element from a handler for\nexample) the change will not impact the expression evaluation. There is an exception to\nthis: \"private\" attributes (which name start with a '#', and can only be created during\nthe parsing, as they are not valid XML) are checked against the current twig.\n\nHandlers are triggered in fixed order, sorted by their type (xpath expressions first,\nthen regexps, then level), then by whether they specify a full path (starting at the\nroot element) or not, then by number of steps in the expression, then number of\npredicates, then number of tests in predicates. Handlers where the last step does not\nspecify a step (\"foo/bar/*\") are triggered after other XPath handlers. Finally \"all\"\nhandlers are triggered last.\n\nImportant: once a handler has been triggered if it returns 0 then no other handler is\ncalled, except a \"all\" handler which will be called anyway.\n\nIf a handler returns a true value and other handlers apply, then the next applicable\nhandler will be called. Repeat, rinse, lather..; The exception to that rule is when the\n\"donotchainhandlers\" option is set, in which case only the first handler will be\ncalled.\n\nNote that it might be a good idea to explicitly return a short true value (like 1) from\nhandlers: this ensures that other applicable handlers are called even if the last\nstatement for the handler happens to evaluate to false. This might also speedup the code\nby avoiding the result of the last statement of the code to be copied and passed to the\ncode managing handlers. It can really pay to have 1 instead of a long string returned.\n\nWhen the closing tag for an element is parsed the corresponding handler is called, with\n2 arguments: the twig and the \"Element \". The twig includes the document tree that has\nbeen built so far, the element is the complete sub-tree for the element. The fact that\nthe handler is called only when the closing tag for the element is found means that\nhandlers for inner elements are called before handlers for outer elements.\n\n$ is also set to the element, so it is easy to write inline handlers like\n\npara => sub { $->settag( 'p'); }\n\nText is stored in elements whose tag name is #PCDATA (due to mixed content, text and\nsub-element in an element there is no way to store the text as just an attribute of the\nenclosing element, this is similar to the DOM model).\n\nWarning: if you have used purge or flush on the twig the element might not be complete,\nsome of its children might have been entirely flushed or purged, and the start tag might\neven have been printed (by \"flush\") already, so changing its tag might not give the\nexpected result.\n\ntwigroots\nThis argument lets you build the tree only for those elements you are interested in.\n\nExample: my $t= XML::Twig->new( twigroots => { title => 1, subtitle => 1});\n$t->parsefile( file);\nmy $t= XML::Twig->new( twigroots => { 'section/title' => 1});\n$t->parsefile( file);\n\nreturn a twig containing a document including only \"title\" and \"subtitle\" elements, as\nchildren of the root element.\n\nYou can use *genericattributecondition*, *attributecondition*, *fullpath*,\n*partialpath*, *tag*, *tagregexp*, *default* and *all* to trigger the building of\nthe twig. *stringcondition* and *regexpcondition* cannot be used as the content of the\nelement, and the string, have not yet been parsed when the condition is checked.\n\nWARNING: path are checked for the document. Even if the \"twigroots\" option is used they\nwill be checked against the full document tree, not the virtual tree created by\nXML::Twig\n\nWARNING: twigroots elements should NOT be nested, that would hopelessly confuse\nXML::Twig ;--(\n\nNote: you can set handlers (twighandlers) using twigroots Example: my $t=\nXML::Twig->new( twigroots => { title => sub { $[1]->print;}, subtitle =>\n\\&processsubtitle } ); $t->parsefile( file);\n\ntwigprintoutsideroots\nTo be used in conjunction with the \"twigroots\" argument. When set to a true value this\nwill print the document outside of the \"twigroots\" elements.\n\nExample: my $t= XML::Twig->new( twigroots => { title => \\&numbertitle },\ntwigprintoutsideroots => 1,\n);\n$t->parsefile( file);\n{ my $nb;\nsub numbertitle\n{ my( $twig, $title);\n$nb++;\n$title->prefix( \"$nb \");\n$title->print;\n}\n}\n\nThis example prints the document outside of the title element, calls \"numbertitle\" for\neach \"title\" element, prints it, and then resumes printing the document. The twig is\nbuilt only for the \"title\" elements.\n\nIf the value is a reference to a file handle then the document outside the \"twigroots\"\nelements will be output to this file handle:\n\nopen( my $out, '>', 'outfile.xml') or die \"cannot open out file.xml outfile:$!\";\nmy $t= XML::Twig->new( twigroots => { title => \\&numbertitle },\n# default output to $out\ntwigprintoutsideroots => $out,\n);\n\n{ my $nb;\nsub numbertitle\n{ my( $twig, $title);\n$nb++;\n$title->prefix( \"$nb \");\n$title->print( $out); # you have to print to \\*OUT here\n}\n}\n\nstarttaghandlers\nA hash \"{ expression =\" \\&handler}>. Sets element handlers that are called when the\nelement is open (at the end of the XML::Parser \"Start\" handler). The handlers are called\nwith 2 params: the twig and the element. The element is empty at that point, its\nattributes are created though.\n\nYou can use *genericattributecondition*, *attributecondition*, *fullpath*,\n*partialpath*, *tag*, *tagregexp*, *default* and *all* to trigger the handler.\n\n*stringcondition* and *regexpcondition* cannot be used as the content of the element,\nand the string, have not yet been parsed when the condition is checked.\n\nThe main uses for those handlers are to change the tag name (you might have to do it as\nsoon as you find the open tag if you plan to \"flush\" the twig at some point in the\nelement, and to create temporary attributes that will be used when processing\nsub-element with \"twighanlders\".\n\nNote: \"starttag\" handlers can be called outside of \"twigroots\" if this argument is\nused. Since the element object is not built, in this case handlers are called with the\nfollowing arguments: $t (the twig), $tag (the tag of the element) and %att (a hash of\nthe attributes of the element).\n\nIf the \"twigprintoutsideroots\" argument is also used, if the last handler called\nreturns a \"true\" value, then the start tag will be output as it appeared in the original\ndocument, if the handler returns a \"false\" value then the start tag will not be printed\n(so you can print a modified string yourself for example).\n\nNote that you can use the ignore method in \"starttaghandlers\" (and only there).\n\nendtaghandlers\nA hash \"{ expression =\" \\&handler}>. Sets element handlers that are called when the\nelement is closed (at the end of the XML::Parser \"End\" handler). The handlers are called\nwith 2 params: the twig and the tag of the element.\n\n*twighandlers* are called when an element is completely parsed, so why have this\nredundant option? There is only one use for \"endtaghandlers\": when using the\n\"twigroots\" option, to trigger a handler for an element outside the roots. It is for\nexample very useful to number titles in a document using nested sections:\n\nmy @no= (0);\nmy $no;\nmy $t= XML::Twig->new(\nstarttaghandlers =>\n{ section => sub { $no[$#no]++; $no= join '.', @no; push @no, 0; } },\ntwigroots =>\n{ title => sub { $->prefix( $no); $->print; } },\nendtaghandlers => { section => sub { pop @no; } },\ntwigprintoutsideroots => 1\n);\n$t->parsefile( $file);\n\nUsing the \"endtaghandlers\" argument without \"twigroots\" will result in an error.\n\ndonotchainhandlers\nIf this option is set to a true value, then only one handler will be called for each\nelement, even if several satisfy the condition\n\nNote that the \"all\" handler will still be called regardless\n\nignoreelts\nThis option lets you ignore elements when building the twig. This is useful in cases\nwhere you cannot use \"twigroots\" to ignore elements, for example if the element to\nignore is a sibling of elements you are interested in.\n\nExample:\n\nmy $twig= XML::Twig->new( ignoreelts => { elt => 'discard' });\n$twig->parsefile( 'doc.xml');\n\nThis will build the complete twig for the document, except that all \"elt\" elements (and\ntheir children) will be left out.\n\nThe keys in the hash are triggers, limited to the same subset as \"starttaghandlers\".\nThe values can be \"discard\", to discard the element, \"print\", to output the element\nas-is, \"string\" to store the text of the ignored element(s), including markup, in a\nfield of the twig: \"$t->{twigbufferedstring}\" or a reference to a scalar, in which\ncase the text of the ignored element(s), including markup, will be stored in the scalar.\nAny other value will be treated as \"discard\".\n\ncharhandler\nA reference to a subroutine that will be called every time \"PCDATA\" is found.\n\nThe subroutine receives the string as argument, and returns the modified string:\n\n# WE WANT ALL STRINGS IN UPPER CASE\nsub mycharhandler\n{ my( $text)= @;\n$text= uc( $text);\nreturn $text;\n}\n\neltclass\nThe name of a class used to store elements. this class should inherit from\n\"XML::Twig::Elt\" (and by default it is \"XML::Twig::Elt\"). This option is used to\nsubclass the element class and extend it with new methods.\n\nThis option is needed because during the parsing of the XML, elements are created by\n\"XML::Twig\", without any control from the user code.\n\nkeepattsorder\nSetting this option to a true value causes the attribute hash to be tied to a\n\"Tie::IxHash\" object. This means that \"Tie::IxHash\" needs to be installed for this\noption to be available. It also means that the hash keeps its order, so you will get the\nattributes in order. This allows outputting the attributes in the same order as they\nwere in the original document.\n\nkeepencoding\nThis is a (slightly?) evil option: if the XML document is not UTF-8 encoded and you want\nto keep it that way, then setting keepencoding will use the\"Expat\" originalstring\nmethod for character, thus keeping the original encoding, as well as the original\nentities in the strings.\n\nSee the \"t/test6.t\" test file to see what results you can expect from the various\nencoding options.\n\nWARNING: if the original encoding is multi-byte then attribute parsing will be EXTREMELY\nunsafe under any Perl before 5.6, as it uses regular expressions which do not deal\nproperly with multi-byte characters. You can specify an alternate function to parse the\nstart tags with the \"parsestarttag\" option (see below)\n\nWARNING: this option is NOT used when parsing with XML::Parser non-blocking parser\n(\"parsestart\", \"parsemore\", \"parsedone\" methods) which you probably should not use\nwith XML::Twig anyway as they are totally untested!\n\noutputencoding\nThis option generates an outputfilter using \"Encode\", \"Text::Iconv\" or \"Unicode::Map8\"\nand \"Unicode::Strings\", and sets the encoding in the XML declaration. This is the\neasiest way to deal with encodings, if you need more sophisticated features, look at\n\"outputfilter\" below\n\noutputfilter\nThis option is used to convert the character encoding of the output document. It is\npassed either a string corresponding to a predefined filter or a subroutine reference.\nThe filter will be called every time a document or element is processed by the \"print\"\nfunctions (\"print\", \"sprint\", \"flush\").\n\nPre-defined filters:\n\nlatin1\nuses either \"Encode\", \"Text::Iconv\" or \"Unicode::Map8\" and \"Unicode::String\" or a\nregexp (which works only with XML::Parser 2.27), in this order, to convert all\ncharacters to ISO-8859-15 (usually latin1 is synonym to ISO-8859-1, but in practice\nit seems that ISO-8859-15, which includes the euro sign, is more useful and probably\nwhat most people want).\n\nhtml\ndoes the same conversion as \"latin1\", plus encodes entities using \"HTML::Entities\"\n(oddly enough you will need to have HTML::Entities installed for it to be\navailable). This should only be used if the tags and attribute names themselves are\nin US-ASCII, or they will be converted and the output will not be valid XML any more\n\nsafe\nconverts the output to ASCII (US) only plus *character entities* (\"&#nnn;\") this\nshould be used only if the tags and attribute names themselves are in US-ASCII, or\nthey will be converted and the output will not be valid XML any more\n\nsafehex\nsame as \"safe\" except that the character entities are in hex (\"&#xnnn;\")\n\nencodeconvert ($encoding)\nReturn a subref that can be used to convert utf8 strings to $encoding). Uses\n\"Encode\".\n\nmy $conv = XML::Twig::encodeconvert( 'latin1');\nmy $t = XML::Twig->new(outputfilter => $conv);\n\niconvconvert ($encoding)\nthis function is used to create a filter subroutine that will be used to convert the\ncharacters to the target encoding using \"Text::Iconv\" (which needs to be installed,\nlook at the documentation for the module and for the \"iconv\" library to find out\nwhich encodings are available on your system, \"iconv -l\" should give you a list of\navailable encodings)\n\nmy $conv = XML::Twig::iconvconvert( 'latin1');\nmy $t = XML::Twig->new(outputfilter => $conv);\n\nunicodeconvert ($encoding)\nthis function is used to create a filter subroutine that will be used to convert the\ncharacters to the target encoding using \"Unicode::Strings\" and \"Unicode::Map8\"\n(which need to be installed, look at the documentation for the modules to find out\nwhich encodings are available on your system)\n\nmy $conv = XML::Twig::unicodeconvert( 'latin1');\nmy $t = XML::Twig->new(outputfilter => $conv);\n\nThe \"text\" and \"att\" methods do not use the filter, so their result are always in\nunicode.\n\nThose predeclared filters are based on subroutines that can be used by themselves (as\n\"XML::Twig::foo\").\n\nhtmlencode ($string)\nUse \"HTML::Entities\" to encode a utf8 string\n\nsafeencode ($string)\nUse either a regexp (perl < 5.8) or \"Encode\" to encode non-ascii characters in the\nstring in \"&#;\" format\n\nsafeencodehex ($string)\nUse either a regexp (perl < 5.8) or \"Encode\" to encode non-ascii characters in the\nstring in \"&#x;\" format\n\nregexp2latin1 ($string)\nUse a regexp to encode a utf8 string into latin 1 (ISO-8859-1). Does not work with\nPerl 5.8.0!\n\noutputtextfilter\nsame as outputfilter, except it doesn't apply to the brackets and quotes around\nattribute values. This is useful for all filters that could change the tagging,\nbasically anything that does not just change the encoding of the output. \"html\", \"safe\"\nand \"safehex\" are better used with this option.\n\ninputfilter\nThis option is similar to \"outputfilter\" except the filter is applied to the characters\nbefore they are stored in the twig, at parsing time.\n\nremovecdata\nSetting this option to a true value will force the twig to output CDATA sections as\nregular (escaped) PCDATA\n\nparsestarttag\nIf you use the \"keepencoding\" option then this option can be used to replace the\ndefault parsing function. You should provide a coderef (a reference to a subroutine) as\nthe argument, this subroutine takes the original tag (given by XML::Parser::Expat\n\"originalstring()\" method) and returns a tag and the attributes in a hash (or in a list\nattributename/attribute value).\n\nnoxxe\nprevents external entities to be parsed.\n\nThis is a security feature, in case the input XML cannot be trusted. With this option\nset to a true value defining external entities in the document will cause the parse to\nfail.\n\nThis prevents an entity like \"\" to make the\npassword fiel available in the document.\n\nexpandexternalents\nWhen this option is used external entities (that are defined) are expanded when the\ndocument is output using \"print\" functions such as \"print \", \"sprint \", \"flush \" and\n\"xmlstring \". Note that in the twig the entity will be stored as an element with a tag\n'\"#ENT\"', the entity will not be expanded there, so you might want to process the\nentities before outputting it.\n\nIf an external entity is not available, then the parse will fail.\n\nA special case is when the value of this option is -1. In that case a missing entity\nwill not cause the parser to die, but its \"name\", \"sysid\" and \"pubid\" will be stored in\nthe twig as \"$twig->{twigmissingsystementities}\" (a reference to an array of hashes {\nname => , sysid => , pubid => }). Yes, this is a bit of a hack, but\nit's useful in some cases.\n\nWARNING: setting expandexternalents to 0 or -1 currently doesn't work as expected; cf.\n. To completelty turn off\nexpanding external entities use \"noxxe\".\n\nnoxxe\nIf this argument is set to a true value, expanding of external entities is turned off.\n\nloadDTD\nIf this argument is set to a true value, \"parse\" or \"parsefile\" on the twig will load\nthe DTD information. This information can then be accessed through the twig, in a\n\"DTDhandler\" for example. This will load even an external DTD.\n\nDefault and fixed values for attributes will also be filled, based on the DTD.\n\nNote that to do this the module will generate a temporary file in the current directory.\nIf this is a problem let me know and I will add an option to specify an alternate\ndirectory.\n\nSee \"DTD Handling\" for more information\n\nDTDbase \nIf the DTD is in a different directory, looks for it there, useful to make up somewhat\nfor the lack of catalog support in \"expat\". You still need a SYSTEM declaration\n\nDTDhandler\nSet a handler that will be called once the doctype (and the DTD) have been loaded, with\n2 arguments, the twig and the DTD.\n\nnoprolog\nDoes not output a prolog (XML declaration and DTD)\n\nid This optional argument gives the name of an attribute that can be used as an ID in the\ndocument. Elements whose ID is known can be accessed through the eltid method. id\ndefaults to 'id'. See \"BUGS \"\n\ndiscardspaces\nIf this optional argument is set to a true value then spaces are discarded when they\nlook non-significant: strings containing only spaces and at least one line feed are\ndiscarded. This argument is set to true by default.\n\nThe exact algorithm to drop spaces is: strings including only spaces (perl \\s) and at\nleast one \\n right before an open or close tag are dropped.\n\ndiscardallspaces\nIf this argument is set to a true value, spaces are discarded more aggressively than\nwith \"discardspaces\": strings not including a \\n are also dropped. This option is\nappropriate for data-oriented XML.\n\nkeepspaces\nIf this optional argument is set to a true value then all spaces in the document are\nkept, and stored as \"PCDATA\".\n\nWarning: adding this option can result in changes in the twig generated: space that was\npreviously discarded might end up in a new text element. see the difference by calling\nthe following code with 0 and 1 as arguments:\n\nperl -MXML::Twig -e'print XML::Twig->new( keepspaces => shift)->parse( \" \\n\")->dump'\n\n\"keepspaces\" and \"discardspaces\" cannot be both set.\n\ndiscardspacesin\nThis argument sets \"keepspaces\" to true but will cause the twig builder to discard\nspaces in the elements listed.\n\nThe syntax for using this argument is:\n\nXML::Twig->new( discardspacesin => [ 'elt1', 'elt2']);\n\nkeepspacesin\nThis argument sets \"discardspaces\" to true but will cause the twig builder to keep\nspaces in the elements listed.\n\nThe syntax for using this argument is:\n\nXML::Twig->new( keepspacesin => [ 'elt1', 'elt2']);\n\nWarning: adding this option can result in changes in the twig generated: space that was\npreviously discarded might end up in a new text element.\n\nprettyprint\nSet the pretty print method, amongst '\"none\"' (default), '\"nsgmls\"', '\"nice\"',\n'\"indented\"', '\"indentedc\"', '\"indenteda\"', '\"indentedclosetag\"', '\"cvs\"',\n'\"wrapped\"', '\"record\"' and '\"recordc\"'\n\nprettyprint formats:\n\nnone\nThe document is output as one ling string, with no line breaks except those found\nwithin text elements\n\nnsgmls\nLine breaks are inserted in safe places: that is within tags, between a tag and an\nattribute, between attributes and before the > at the end of a tag.\n\nThis is quite ugly but better than \"none\", and it is very safe, the document will\nstill be valid (conforming to its DTD).\n\nThis is how the SGML parser \"sgmls\" splits documents, hence the name.\n\nnice\nThis option inserts line breaks before any tag that does not contain text (so\nelement with textual content are not broken as the \\n is the significant).\n\nWARNING: this option leaves the document well-formed but might make it invalid (not\nconformant to its DTD). If you have elements declared as\n\n\n\nthen a \"foo\" element including a \"bar\" one will be printed as\n\n\nbar is just pcdata\n\n\nThis is invalid, as the parser will take the line break after the \"foo\" tag as a\nsign that the element contains PCDATA, it will then die when it finds the \"bar\" tag.\nThis may or may not be important for you, but be aware of it!\n\nindented\nSame as \"nice\" (and with the same warning) but indents elements according to their\nlevel\n\nindentedc\nSame as \"indented\" but a little more compact: the closing tags are on the same line\nas the preceding text\n\nindentedclosetag\nSame as \"indented\" except that the closing tag is also indented, to line up with the\ntags within the element\n\nidenteda\nThis formats XML files in a line-oriented version control friendly way. The format\nis described in (that's an Oracle document with an\ninsanely long URL).\n\nNote that to be totaly conformant to the \"spec\", the order of attributes should not\nbe changed, so if they are not already in alphabetical order you will need to use\nthe \"keepattsorder\" option.\n\ncvs Same as \"identeda\".\n\nwrapped\nSame as \"indentedc\" but lines are wrapped using Text::Wrap::wrap. The default\nlength for lines is the default for $Text::Wrap::columns, and can be changed by\nchanging that variable.\n\nrecord\nThis is a record-oriented pretty print, that display data in records, one field per\nline (which looks a LOT like \"indented\")\n\nrecordc\nStands for record compact, one record per line\n\nemptytags\nSet the empty tag display style ('\"normal\"', '\"html\"' or '\"expand\"').\n\n\"normal\" outputs an empty tag '\"\"', \"html\" adds a space '\"\"' for elements\nthat can be empty in XHTML and \"expand\" outputs '\"\"'\n\nquote\nSet the quote character for attributes ('\"single\"' or '\"double\"').\n\nescapegt\nBy default XML::Twig does not escape the character > in its output, as it is not\nmandated by the XML spec. With this option on, > will be replaced by \">\"\n\ncomments\nSet the way comments are processed: '\"drop\"' (default), '\"keep\"' or '\"process\"'\n\nComments processing options:\n\ndrop\ndrops the comments, they are not read, nor printed to the output\n\nkeep\ncomments are loaded and will appear on the output, they are not accessible within\nthe twig and will not interfere with processing though\n\nNote: comments in the middle of a text element such as\n\n

text more text -->

\n\nare kept at their original position in the text. Using \"print\" methods like \"print\"\nor \"sprint\" will return the comments in the text. Using \"text\" or \"field\" on the\nother hand will not.\n\nAny use of \"setpcdata\" on the \"#PCDATA\" element (directly or through other methods\nlike \"setcontent\") will delete the comment(s).\n\nprocess\ncomments are loaded in the twig and will be treated as regular elements (their \"tag\"\nis \"#COMMENT\") this can interfere with processing if you expect\n\"$elt->{firstchild}\" to be an element but find a comment there. Validation will not\nprotect you from this as comments can happen anywhere. You can use\n\"$elt->firstchild( 'tag')\" (which is a good habit anyway) to get where you want.\n\nConsider using \"process\" if you are outputting SAX events from XML::Twig.\n\npi Set the way processing instructions are processed: '\"drop\"', '\"keep\"' (default) or\n'\"process\"'\n\nNote that you can also set PI handlers in the \"twighandlers\" option:\n\n'?' => \\&handler\n'?target' => \\&handler 2\n\nThe handlers will be called with 2 parameters, the twig and the PI element if \"pi\" is\nset to \"process\", and with 3, the twig, the target and the data if \"pi\" is set to\n\"keep\". Of course they will not be called if \"pi\" is set to \"drop\".\n\nIf \"pi\" is set to \"keep\" the handler should return a string that will be used as-is as\nthe PI text (it should look like \"\" \" or '' if you want to remove the\nPI),\n\nOnly one handler will be called, \"?target\" or \"?\" if no specific handler for that target\nis available.\n\nmapxmlns\nThis option is passed a hashref that maps uri's to prefixes. The prefixes in the\ndocument will be replaced by the ones in the map. The mapped prefixes can (actually have\nto) be used to trigger handlers, navigate or query the document.\n\nHere is an example:\n\nmy $t= XML::Twig->new( mapxmlns => {'http://www.w3.org/2000/svg' => \"svg\"},\ntwighandlers =>\n{ 'svg:circle' => sub { $->setatt( r => 20) } },\nprettyprint => 'indented',\n)\n->parse( '\n\n'\n)\n->print;\n\nThis will output:\n\n\n\n\n\nkeeporiginalprefix\nWhen used with \"mapxmlns\" this option will make \"XML::Twig\" use the original namespace\nprefixes when outputting a document. The mapped prefix will still be used for triggering\nhandlers and in navigation and query methods.\n\nmy $t= XML::Twig->new( mapxmlns => {'http://www.w3.org/2000/svg' => \"svg\"},\ntwighandlers =>\n{ 'svg:circle' => sub { $->setatt( r => 20) } },\nkeeporiginalprefix => 1,\nprettyprint => 'indented',\n)\n->parse( '\n\n'\n)\n->print;\n\nThis will output:\n\n\n\n\n\noriginaluri ($prefix)\ncalled within a handler, this will return the uri bound to the namespace prefix in the\noriginal document.\n\nindex ($arrayref or $hashref)\nThis option creates lists of specific elements during the parsing of the XML. It takes a\nreference to either a list of triggering expressions or to a hash name => expression,\nand for each one generates the list of elements that match the expression. The list can\nbe accessed through the \"index\" method.\n\nexample:\n\n# using an array ref\nmy $t= XML::Twig->new( index => [ 'div', 'table' ])\n->parsefile( \"foo.xml\");\nmy $divs= $t->index( 'div');\nmy $firstdiv= $divs->[0];\nmy $lasttable= $t->index( table => -1);\n\n# using a hashref to name the indexes\nmy $t= XML::Twig->new( index => { email => 'a[@href=~/^ \\s*mailto:/]'})\n->parsefile( \"foo.xml\");\nmy $lastemails= $t->index( email => -1);\n\nNote that the index is not maintained after the parsing. If elements are deleted,\nrenamed or otherwise hurt during processing, the index is NOT updated. (changing the id\nelement OTOH will update the index)\n\nattaccessors \ncreates methods that give direct access to attribute:\n\nmy $t= XML::Twig->new( attaccessors => [ 'href', 'src'])\n->parsefile( $file);\nmy $firsthref= $t->firstelt( 'img')->src; # same as ->att( 'src')\n$t->firstelt( 'img')->src( 'newlogo.png') # changes the attribute value\n\neltaccessors\ncreates methods that give direct access to the first child element (in scalar context)\nor the list of elements (in list context):\n\nthe list of accessors to create can be given 1 2 different ways: in an array, or in a\nhash alias => expression my $t= XML::Twig->new( eltaccessors => [ 'head']) ->parsefile(\n$file); my $titletext= $t->root->head->field( 'title'); # same as $titletext=\n$t->root->firstchild( 'head')->field( 'title');\n\nmy $t= XML::Twig->new( eltaccessors => { warnings => 'p[@class=\"warning\"]', d2 => 'div[2]'}, )\n->parsefile( $file);\nmy $body= $t->firstelt( 'body');\nmy @warnings= $body->warnings; # same as $body->children( 'p[@class=\"warning\"]');\nmy $s2= $body->d2; # same as $body->firstchild( 'div[2]')\n\nfieldaccessors\ncreates methods that give direct access to the first child element text:\n\nmy $t= XML::Twig->new( fieldaccessors => [ 'h1'])\n->parsefile( $file);\nmy $divtitletext= $t->firstelt( 'div')->title;\n# same as $titletext= $t->firstelt( 'div')->field( 'title');\n\nusetidy\nset this option to use HTML::Tidy instead of HTML::TreeBuilder to convert HTML to XML.\nHTML, especially real (real \"crap\") HTML found in the wild, so depending on the data,\none module or the other does a better job at the conversion. Also, HTML::Tidy can be a\nbit difficult to install, so XML::Twig offers both option. TIMTOWTDI\n\noutputhtmldoctype\nwhen using HTML::TreeBuilder to convert HTML, this option causes the DOCTYPE declaration\nto be output, which may be important for some legacy browsers. Without that option the\nDOCTYPE definition is NOT output. Also if the definition is completely wrong (ie not\neasily parsable), it is not output either.\n\nNote: I HATE the Java-like name of arguments used by most XML modules. So in pure\nTIMTOWTDI fashion all arguments can be written either as \"UglyJavaLikeName\" or as\n\"readableperlname\": \"twigprintoutsideroots\" or \"TwigPrintOutsideRoots\" (or even\n\"twigPrintOutsideRoots\" {shudder}). XML::Twig normalizes them before processing them.\n\nparse ( $source)\nThe $source parameter should either be a string containing the whole XML document, or it\nshould be an open \"IO::Handle\" (aka a filehandle).\n\nA die call is thrown if a parse error occurs. Otherwise it will return the twig built by the\nparse. Use \"safeparse\" if you want the parsing to return even when an error occurs.\n\nIf this method is called as a class method (\"XML::Twig->parse( $somexmlorhtml)\") then an\nXML::Twig object is created, using the parameters except the last one (eg \"XML::Twig->parse(\nprettyprint => 'indented', $somexmlorhtml)\") and \"xparse\" is called on it.\n\nNote that when parsing a filehandle, the handle should NOT be open with an encoding (ie open\nwith \"open( my $in, '<', $filename)\". The file will be parsed by \"expat\", so specifying the\nencoding actually causes problems for the parser (as in: it can crash it, see\nhttps://rt.cpan.org/Ticket/Display.html?id=78877). For parsing a file it is actually\nrecommended to use \"parsefile\" on the file name, instead of on the open file.\n\nparsestring\nThis is just an alias for \"parse\" for backwards compatibility.\n\nparsefile (FILE [, OPT => OPTVALUE [...]])\nOpen \"FILE\" for reading, then call \"parse\" with the open handle. The file is closed no\nmatter how \"parse\" returns.\n\nA \"die\" call is thrown if a parse error occurs. Otherwise it will return the twig built by\nthe parse. Use \"safeparsefile\" if you want the parsing to return even when an error occurs.\n\nparsefileinplace ( $file, $optionalextension)\nParse and update a file \"in place\". It does this by creating a temp file, selecting it as\nthe default for print() statements (and methods), then parsing the input file. If the\nparsing is successful, then the temp file is moved to replace the input file.\n\nIf an extension is given then the original file is backed-up (the rules for the extension\nare the same as the rule for the -i option in perl).\n\nparsefilehtmlinplace ( $file, $optionalextension)\nSame as parsefileinplace, except that it parses HTML instead of XML\n\nparseurl ($url $optionaluseragent)\nGets the data from $url and parse it. The data is piped to the parser in chunks the size of\nthe XML::Parser::Expat buffer, so memory consumption and hopefully speed are optimal.\n\nFor most (read \"small\") XML it is probably as efficient (and easier to debug) to just \"get\"\nthe XML file and then parse it as a string.\n\nuse XML::Twig;\nuse LWP::Simple;\nmy $twig= XML::Twig->new();\n$twig->parse( LWP::Simple::get( $URL ));\n\nor\n\nuse XML::Twig;\nmy $twig= XML::Twig->nparse( $URL);\n\nIf the $optionaluseragent argument is used then it is used, otherwise a new one is\ncreated.\n\nsafeparse ( SOURCE [, OPT => OPTVALUE [...]])\nThis method is similar to \"parse\" except that it wraps the parsing in an \"eval\" block. It\nreturns the twig on success and 0 on failure (the twig object also contains the parsed\ntwig). $@ contains the error message on failure.\n\nNote that the parsing still stops as soon as an error is detected, there is no way to keep\ngoing after an error.\n\nsafeparsefile (FILE [, OPT => OPTVALUE [...]])\nThis method is similar to \"parsefile\" except that it wraps the parsing in an \"eval\" block.\nIt returns the twig on success and 0 on failure (the twig object also contains the parsed\ntwig) . $@ contains the error message on failure\n\nNote that the parsing still stops as soon as an error is detected, there is no way to keep\ngoing after an error.\n\nsafeparseurl ($url $optionaluseragent)\nSame as \"parseurl\" except that it wraps the parsing in an \"eval\" block. It returns the twig\non success and 0 on failure (the twig object also contains the parsed twig) . $@ contains\nthe error message on failure\n\nparsehtml ($stringorfh)\nparse an HTML string or file handle (by converting it to XML using HTML::TreeBuilder, which\nneeds to be available).\n\nThis works nicely, but some information gets lost in the process: newlines are removed, and\n(at least on the version I use), comments get an extra CDATA section inside ( \nbecomes \n\nparsefilehtml ($file)\nparse an HTML file (by converting it to XML using HTML::TreeBuilder, which needs to be\navailable, or HTML::Tidy if the \"usetidy\" option was used). The file is loaded completely\nin memory and converted to XML before being parsed.\n\nthis method is to be used with caution though, as it doesn't know about the file encoding,\nit is usually better to use \"parsehtml\", which gives you a chance to open the file with the\nproper encoding layer.\n\nparseurlhtml ($url $optionaluseragent)\nparse an URL as html the same way \"parsehtml\" does\n\nsafeparseurlhtml ($url $optionaluseragent)\nSame as \"parseurlhtml\"> except that it wraps the parsing in an \"eval\" block. It returns the\ntwig on success and 0 on failure (the twig object also contains the parsed twig) . $@\ncontains the error message on failure\n\nsafeparsefilehtml ($file $optionaluseragent)\nSame as \"parsefilehtml\"> except that it wraps the parsing in an \"eval\" block. It returns\nthe twig on success and 0 on failure (the twig object also contains the parsed twig) . $@\ncontains the error message on failure\n\nsafeparsehtml ($stringorfh)\nSame as \"parsehtml\" except that it wraps the parsing in an \"eval\" block. It returns the\ntwig on success and 0 on failure (the twig object also contains the parsed twig) . $@\ncontains the error message on failure\n\nxparse ($thingtoparse)\nparse the $thingtoparse, whether it is a filehandle, a string, an HTML file, an HTML URL,\nan URL or a file.\n\nNote that this is mostly a convenience method for one-off scripts. For example files that\nend in '.htm' or '.html' are parsed first as XML, and if this fails as HTML. This is\ncertainly not the most efficient way to do this in general.\n\nnparse ($optionaltwigoptions, $thingtoparse)\ncreate a twig with the $optionaloptions, and parse the $thingtoparse, whether it is a\nfilehandle, a string, an HTML file, an HTML URL, an URL or a file.\n\nExamples:\n\nXML::Twig->nparse( \"file.xml\");\nXML::Twig->nparse( errorcontext => 1, \"file://file.xml\");\n\nnparsepp ($optionaltwigoptions, $thingtoparse)\nsame as \"nparse\" but also sets the \"prettyprint\" option to \"indented\".\n\nnparsee ($optionaltwigoptions, $thingtoparse)\nsame as \"nparse\" but also sets the \"errorcontext\" option to 1.\n\nnparseppe ($optionaltwigoptions, $thingtoparse)\nsame as \"nparse\" but also sets the \"prettyprint\" option to \"indented\" and the\n\"errorcontext\" option to 1.\n\nparser\nThis method returns the \"expat\" object (actually the XML::Parser::Expat object) used during\nparsing. It is useful for example to call XML::Parser::Expat methods on it. To get the line\nof a tag for example use \"$t->parser->currentline\".\n\nsetTwigHandlers ($handlers)\nSet the twighandlers. $handlers is a reference to a hash similar to the one in the\n\"twighandlers\" option of new. All previous handlers are unset. The method returns the\nreference to the previous handlers.\n\nsetTwigHandler ($exp $handler)\nSet a single twighandler for elements matching $exp. $handler is a reference to a\nsubroutine. If the handler was previously set then the reference to the previous handler is\nreturned.\n\nsetStartTagHandlers ($handlers)\nSet the starttag handlers. $handlers is a reference to a hash similar to the one in the\n\"starttaghandlers\" option of new. All previous handlers are unset. The method returns the\nreference to the previous handlers.\n\nsetStartTagHandler ($exp $handler)\nSet a single starttag handlers for elements matching $exp. $handler is a reference to a\nsubroutine. If the handler was previously set then the reference to the previous handler is\nreturned.\n\nsetEndTagHandlers ($handlers)\nSet the endtag handlers. $handlers is a reference to a hash similar to the one in the\n\"endtaghandlers\" option of new. All previous handlers are unset. The method returns the\nreference to the previous handlers.\n\nsetEndTagHandler ($exp $handler)\nSet a single endtag handlers for elements matching $exp. $handler is a reference to a\nsubroutine. If the handler was previously set then the reference to the previous handler is\nreturned.\n\nsetTwigRoots ($handlers)\nSame as using the \"twigroots\" option when creating the twig\n\nsetCharHandler ($exp $handler)\nSet a \"charhandler\"\n\nsetIgnoreEltsHandler ($exp)\nSet a \"ignoreelt\" handler (elements that match $exp will be ignored\n\nsetIgnoreEltsHandlers ($exp)\nSet all \"ignoreelt\" handlers (previous handlers are replaced)\n\ndtd Return the dtd (an XML::Twig::DTD object) of a twig\n\nxmldecl\nReturn the XML declaration for the document, or a default one if it doesn't have one\n\ndoctype\nReturn the doctype for the document\n\ndoctypename\nreturns the doctype of the document from the doctype declaration\n\nsystemid\nreturns the system value of the DTD of the document from the doctype declaration\n\npublicid\nreturns the public doctype of the document from the doctype declaration\n\ninternalsubset\nreturns the internal subset of the DTD\n\ndtdtext\nReturn the DTD text\n\ndtdprint\nPrint the DTD\n\nmodel ($tag)\nReturn the model (in the DTD) for the element $tag\n\nroot\nReturn the root element of a twig\n\nsetroot ($elt)\nSet the root of a twig\n\nfirstelt ($optionalcondition)\nReturn the first element matching $optionalcondition of a twig, if no condition is given\nthen the root is returned\n\nlastelt ($optionalcondition)\nReturn the last element matching $optionalcondition of a twig, if no condition is given\nthen the last element of the twig is returned\n\neltid ($id)\nReturn the element whose \"id\" attribute is $id\n\ngetEltById\nSame as \"eltid\"\n\nindex ($indexname, $optionalindex)\nIf the $optionalindex argument is present, return the corresponding element in the index\n(created using the \"index\" option for \"XML::Twig-\"new>)\n\nIf the argument is not present, return an arrayref to the index\n\nnormalize\nmerge together all consecutive pcdata elements in the document (if for example you have\nturned some elements into pcdata using \"erase\", this will give you a \"clean\" document in\nwhich there all text elements are as long as possible).\n\nencoding\nThis method returns the encoding of the XML document, as defined by the \"encoding\" attribute\nin the XML declaration (ie it is \"undef\" if the attribute is not defined)\n\nsetencoding\nThis method sets the value of the \"encoding\" attribute in the XML declaration. Note that if\nthe document did not have a declaration it is generated (with an XML version of 1.0)\n\nxmlversion\nThis method returns the XML version, as defined by the \"version\" attribute in the XML\ndeclaration (ie it is \"undef\" if the attribute is not defined)\n\nsetxmlversion\nThis method sets the value of the \"version\" attribute in the XML declaration. If the\ndeclaration did not exist it is created.\n\nstandalone\nThis method returns the value of the \"standalone\" declaration for the document\n\nsetstandalone\nThis method sets the value of the \"standalone\" attribute in the XML declaration. Note that\nif the document did not have a declaration it is generated (with an XML version of 1.0)\n\nsetoutputencoding\nSet the \"encoding\" \"attribute\" in the XML declaration\n\nsetdoctype ($name, $system, $public, $internal)\nSet the doctype of the element. If an argument is \"undef\" (or not present) then its former\nvalue is retained, if a false ('' or 0) value is passed then the former value is deleted;\n\nentitylist\nReturn the entity list of a twig\n\nentitynames\nReturn the list of all defined entities\n\nentity ($entityname)\nReturn the entity\n\nnotationlist\nReturn the notation list of a twig\n\nnotationnames\nReturn the list of all defined notations\n\nnotation ($notationname)\nReturn the notation\n\nchangegi ($oldgi, $newgi)\nPerforms a (very fast) global change. All elements $oldgi are now $newgi. This is a bit\ndangerous though and should be avoided if < possible, as the new tag might be ignored in\nsubsequent processing.\n\nSee \"BUGS \"\n\nflush ($optionalfilehandle, %options)\nFlushes a twig up to (and including) the current element, then deletes all unnecessary\nelements from the tree that's kept in memory. \"flush\" keeps track of which elements need to\nbe open/closed, so if you flush from handlers you don't have to worry about anything. Just\nkeep flushing the twig every time you're done with a sub-tree and it will come out\nwell-formed. After the whole parsing don't forget to\"flush\" one more time to print the end\nof the document. The doctype and entity declarations are also printed.\n\nflush take an optional filehandle as an argument.\n\nIf you use \"flush\" at any point during parsing, the document will be flushed one last time\nat the end of the parsing, to the proper filehandle.\n\noptions: use the \"updateDTD\" option if you have updated the (internal) DTD and/or the\nentity list and you want the updated DTD to be output\n\nThe \"prettyprint\" option sets the pretty printing of the document.\n\nExample: $t->flush( UpdateDTD => 1);\n$t->flush( $filehandle, prettyprint => 'indented');\n$t->flush( \\*FILE);\n\nflushupto ($elt, $optionalfilehandle, %options)\nFlushes up to the $elt element. This allows you to keep part of the tree in memory when you\n\"flush\".\n\noptions: see flush.\n\npurge\nDoes the same as a \"flush\" except it does not print the twig. It just deletes all elements\nthat have been completely parsed so far.\n\npurgeupto ($elt)\nPurges up to the $elt element. This allows you to keep part of the tree in memory when you\n\"purge\".\n\nprint ($optionalfilehandle, %options)\nPrints the whole document associated with the twig. To be used only AFTER the parse.\n\noptions: see \"flush\".\n\nprinttofile ($filename, %options)\nPrints the whole document associated with the twig to file $filename. To be used only AFTER\nthe parse.\n\noptions: see \"flush\".\n\nsafeprinttofile ($filename, %options)\nPrints the whole document associated with the twig to file $filename. This variant, which\nprobably only works on *nix prints to a temp file, then move the temp file to overwrite the\noriginal file.\n\nThis is a bit safer when 2 processes an potentiallywrite the same file: only the last one\nwill succeed, but the file won't be corruted. I often use this for cron jobs, so testing the\ncode doesn't interfere with the cron job running at the same time.\n\noptions: see \"flush\".\n\nsprint\nReturn the text of the whole document associated with the twig. To be used only AFTER the\nparse.\n\noptions: see \"flush\".\n\ntrim\nTrim the document: gets rid of initial and trailing spaces, and replaces multiple spaces by\na single one.\n\ntoSAX1 ($handler)\nSend SAX events for the twig to the SAX1 handler $handler\n\ntoSAX2 ($handler)\nSend SAX events for the twig to the SAX2 handler $handler\n\nflushtoSAX1 ($handler)\nSame as flush, except that SAX events are sent to the SAX1 handler $handler instead of the\ntwig being printed\n\nflushtoSAX2 ($handler)\nSame as flush, except that SAX events are sent to the SAX2 handler $handler instead of the\ntwig being printed\n\nignore\nThis method should be called during parsing, usually in \"starttaghandlers\". It causes the\nelement to be skipped during the parsing: the twig is not built for this element, it will\nnot be accessible during parsing or after it. The element will not take up any memory and\nparsing will be faster.\n\nNote that this method can also be called on an element. If the element is a parent of the\ncurrent element then this element will be ignored (the twig will not be built any more for\nit and what has already been built will be deleted).\n\nsetprettyprint ($style)\nSet the pretty print method, amongst '\"none\"' (default), '\"nsgmls\"', '\"nice\"', '\"indented\"',\n\"indentedc\", '\"wrapped\"', '\"record\"' and '\"recordc\"'\n\nWARNING: the pretty print style is a GLOBAL variable, so once set it's applied to ALL\n\"print\"'s (and \"sprint\"'s). Same goes if you use XML::Twig with \"modperl\" . This should not\nbe a problem as the XML that's generated is valid anyway, and XML processors (as well as\nHTML processors, including browsers) should not care. Let me know if this is a big problem,\nbut at the moment the performance/cleanliness trade-off clearly favors the global approach.\n\nsetemptytagstyle ($style)\nSet the empty tag display style ('\"normal\"', '\"html\"' or '\"expand\"'). As with\n\"setprettyprint\" this sets a global flag.\n\n\"normal\" outputs an empty tag '\"\"', \"html\" adds a space '\"\"' for elements that\ncan be empty in XHTML and \"expand\" outputs '\"\"'\n\nsetremovecdata ($flag)\nset (or unset) the flag that forces the twig to output CDATA sections as regular (escaped)\nPCDATA\n\nprintprolog ($optionalfilehandle, %options)\nPrints the prolog (XML declaration + DTD + entity declarations) of a document.\n\noptions: see \"flush\".\n\nprolog ($optionalfilehandle, %options)\nReturn the prolog (XML declaration + DTD + entity declarations) of a document.\n\noptions: see \"flush\".\n\nfinish\nCall Expat \"finish\" method. Unsets all handlers (including internal ones that set context),\nbut expat continues parsing to the end of the document or until it finds an error. It should\nfinish up a lot faster than with the handlers set.\n\nfinishprint\nStops twig processing, flush the twig and proceed to finish printing the document as fast as\npossible. Use this method when modifying a document and the modification is done.\n\nfinishnow\nStops twig processing, does not finish parsing the document (which could actually be not\nwell-formed after the point where \"finishnow\" is called). Execution resumes after the\n\"Lparse\"> or \"parsefile\" call. The content of the twig is what has been parsed so far (all\nopen elements at the time \"finishnow\" is called are considered closed).\n\nsetexpandexternalentities\nSame as using the \"expandexternalents\" option when creating the twig\n\nsetinputfilter\nSame as using the \"inputfilter\" option when creating the twig\n\nsetkeepattsorder\nSame as using the \"keepattsorder\" option when creating the twig\n\nsetkeepencoding\nSame as using the \"keepencoding\" option when creating the twig\n\nescapegt\nusually XML::Twig does not escape > in its output. Using this option makes it replace > by\n>\n\ndonotescapegt\nreverts XML::Twig behavior to its default of not escaping > in its output.\n\nsetoutputfilter\nSame as using the \"outputfilter\" option when creating the twig\n\nsetoutputtextfilter\nSame as using the \"outputtextfilter\" option when creating the twig\n\naddstylesheet ($type, @options)\nAdds an external stylesheet to an XML document.\n\nSupported types and options:\n\nxsl option: the url of the stylesheet\n\nExample:\n\n$t->addstylesheet( xsl => \"xslstyle.xsl\");\n\nwill generate the following PI at the beginning of the document:\n\n\n\ncss option: the url of the stylesheet\n\nactivetwig\na class method that returns the last processed twig, so you don't necessarily need the\nobject to call methods on it.\n\nMethods inherited from XML::Parser::Expat\nA twig inherits all the relevant methods from XML::Parser::Expat. These methods can only be\nused during the parsing phase (they will generate a fatal error otherwise).\n\nInherited methods are:\n\ndepth\nReturns the size of the context list.\n\ninelement\nReturns true if NAME is equal to the name of the innermost currently opened element. If\nnamespace processing is being used and you want to check against a name that may be in a\nnamespace, then use the generatensname method to create the NAME argument.\n\nwithinelement\nReturns the number of times the given name appears in the context list. If namespace\nprocessing is being used and you want to check against a name that may be in a\nnamespace, then use the generatensname method to create the NAME argument.\n\ncontext\nReturns a list of element names that represent open elements, with the last one being\nthe innermost. Inside start and end tag handlers, this will be the tag of the parent\nelement.\n\ncurrentline\nReturns the line number of the current position of the parse.\n\ncurrentcolumn\nReturns the column number of the current position of the parse.\n\ncurrentbyte\nReturns the current position of the parse.\n\npositionincontext\nReturns a string that shows the current parse position. LINES should be an integer >= 0\nthat represents the number of lines on either side of the current parse line to place\ninto the returned string.\n\nbase ([NEWBASE])\nReturns the current value of the base for resolving relative URIs. If NEWBASE is\nsupplied, changes the base to that value.\n\ncurrentelement\nReturns the name of the innermost currently opened element. Inside start or end\nhandlers, returns the parent of the element associated with those tags.\n\nelementindex\nReturns an integer that is the depth-first visit order of the current element. This will\nbe zero outside of the root element. For example, this will return 1 when called from\nthe start handler for the root element start tag.\n\nrecognizedstring\nReturns the string from the document that was recognized in order to call the current\nhandler. For instance, when called from a start handler, it will give us the start-tag\nstring. The string is encoded in UTF-8. This method doesn't return a meaningful string\ninside declaration handlers.\n\noriginalstring\nReturns the verbatim string from the document that was recognized in order to call the\ncurrent handler. The string is in the original document encoding. This method doesn't\nreturn a meaningful string inside declaration handlers.\n\nxpcroak\nConcatenate onto the given message the current line number within the XML document plus\nthe message implied by ErrorContext. Then croak with the formed message.\n\nxpcarp\nConcatenate onto the given message the current line number within the XML document plus\nthe message implied by ErrorContext. Then carp with the formed message.\n\nxmlescape(TEXT [, CHAR [, CHAR ...]])\nReturns TEXT with markup characters turned into character entities. Any additional\ncharacters provided as arguments are also turned into character references where found\nin TEXT.\n\n(this method is broken on some versions of expat/XML::Parser)\n\npath ( $optionaltag)\nReturn the element context in a form similar to XPath's short form: '\"/root/tag1/../tag\"'\n\ngetxpath ( $optionalarrayref, $xpath, $optionaloffset)\nPerforms a \"getxpath\" on the document root (see )\n\nIf the $optionalarrayref argument is used the array must contain elements. The $xpath\nexpression is applied to each element in turn and the result is union of all results. This\nway a first query can be refined in further steps.\n\nfindnodes ( $optionalarrayref, $xpath, $optionaloffset)\nsame as \"getxpath\"\n\nfindnodes ( $optionalarrayref, $xpath, $optionaloffset)\nsame as \"getxpath\" (similar to the XML::LibXML method)\n\nfindvalue ( $optionalarrayref, $xpath, $optionaloffset)\nReturn the \"join\" of all texts of the results of applying \"getxpath\" to the node (similar\nto the XML::LibXML method)\n\nfindvalues ( $optionalarrayref, $xpath, $optionaloffset)\nReturn an array of all texts of the results of applying \"getxpath\" to the node\n\nsubstext ($regexp, $replace)\nsubstext does text substitution on the whole document, similar to perl's \" s///\" operator.\n\ndispose\nUseful only if you don't have \"Scalar::Util\" or \"WeakRef\" installed.\n\nReclaims properly the memory used by an XML::Twig object. As the object has circular\nreferences it never goes out of scope, so if you want to parse lots of XML documents then\nthe memory leak becomes a problem. Use \"$twig->dispose\" to clear this problem.\n\nattaccessors (listofattributenames)\nA convenience method that creates l-valued accessors for attributes. So\n\"$twig->createaccessors( 'foo')\" will create a \"foo\" method that can be called on elements:\n\n$elt->foo; # equivalent to $elt->{'att'}->{'foo'};\n$elt->foo( 'bar'); # equivalent to $elt->setatt( foo => 'bar');\n\nThe methods are l-valued only under those perl's that support this feature (5.6 and above)\n\ncreateaccessors (listofattributenames)\nSame as attaccessors\n\neltaccessors (listofattributenames)\nA convenience method that creates accessors for elements. So \"$twig->createaccessors(\n'foo')\" will create a \"foo\" method that can be called on elements:\n\n$elt->foo; # equivalent to $elt->firstchild( 'foo');\n\nfieldaccessors (listofattributenames)\nA convenience method that creates accessors for element values (\"field\"). So\n\"$twig->createaccessors( 'foo')\" will create a \"foo\" method that can be called on elements:\n\n$elt->foo; # equivalent to $elt->field( 'foo');\n\nsetdonotescapeampinatts\nAn evil method, that I only document because Test::Pod::Coverage complaints otherwise, but\nreally, you don't want to know about it.\n\nXML::Twig::Elt\nnew ($optionaltag, $optionalatts, @optionalcontent)\nThe \"tag\" is optional (but then you can't have a content ), the $optionalatts argument is a\nreference to a hash of attributes, the content can be just a string or a list of strings and\nelement. A content of '\"#EMPTY\"' creates an empty element;\n\nExamples: my $elt= XML::Twig::Elt->new();\nmy $elt= XML::Twig::Elt->new( para => { align => 'center' });\nmy $elt= XML::Twig::Elt->new( para => { align => 'center' }, 'foo');\nmy $elt= XML::Twig::Elt->new( br => '#EMPTY');\nmy $elt= XML::Twig::Elt->new( 'para');\nmy $elt= XML::Twig::Elt->new( para => 'this is a para');\nmy $elt= XML::Twig::Elt->new( para => $elt3, 'another para');\n\nThe strings are not parsed, the element is not attached to any twig.\n\nWARNING: if you rely on ID's then you will have to set the id yourself. At this point the\nelement does not belong to a twig yet, so the ID attribute is not known so it won't be\nstored in the ID list.\n\nNote that \"#COMMENT\", \"#PCDATA\" or \"#CDATA\" are valid tag names, that will create text\nelements.\n\nTo create an element \"foo\" containing a CDATA section:\n\nmy $foo= XML::Twig::Elt->new( '#CDATA' => \"content of the CDATA section\")\n->wrapin( 'foo');\n\nAn attribute of '#CDATA', will create the content of the element as CDATA:\n\nmy $elt= XML::Twig::Elt->new( 'p' => { '#CDATA' => 1}, 'foo < bar');\n\ncreates an element\n\n

\n\nparse ($string, %args)\nCreates an element from an XML string. The string is actually parsed as a new twig, then the\nroot of that twig is returned. The arguments in %args are passed to the twig. As always if\nthe parse fails the parser will die, so use an eval if you want to trap syntax errors.\n\nAs obviously the element does not exist beforehand this method has to be called on the\nclass:\n\nmy $elt= parse XML::Twig::Elt( \" string to parse, with \n, actually tons of \nh\");\n\nsetinnerxml ($string)\nSets the content of the element to be the tree created from the string\n\nsetinnerhtml ($string)\nSets the content of the element, after parsing the string with an HTML parser (HTML::Parser)\n\nsetouterxml ($string)\nReplaces the element with the tree created from the string\n\nprint ($optionalfilehandle, $optionalprettyprintstyle)\nPrints an entire element, including the tags, optionally to a $optionalfilehandle,\noptionally with a $prettyprintstyle.\n\nThe print outputs XML data so base entities are escaped.\n\nprinttofile ($filename, %options)\nPrints the element to file $filename.\n\noptions: see \"flush\". =item sprint ($elt, $optionalnoenclosingtag)\n\nReturn the xml string for an entire element, including the tags. If the optional second\nargument is true then only the string inside the element is returned (the start and end tag\nfor $elt are not). The text is XML-escaped: base entities (& and < in text, & < and \" in\nattribute values) are turned into entities.\n\ngi Return the gi of the element (the gi is the \"generic identifier\" the tag name in SGML\nparlance).\n\n\"tag\" and \"name\" are synonyms of \"gi\".\n\ntag Same as \"gi\"\n\nname\nSame as \"tag\"\n\nsetgi ($tag)\nSet the gi (tag) of an element\n\nsettag ($tag)\nSet the tag (=\"tag\") of an element\n\nsetname ($name)\nSet the name (=\"tag\") of an element\n\nroot\nReturn the root of the twig in which the element is contained.\n\ntwig\nReturn the twig containing the element.\n\nparent ($optionalcondition)\nReturn the parent of the element, or the first ancestor matching the $optionalcondition\n\nfirstchild ($optionalcondition)\nReturn the first child of the element, or the first child matching the $optionalcondition\n\nhaschild ($optionalcondition)\nReturn the first child of the element, or the first child matching the $optionalcondition\n(same as firstchild)\n\nhaschildren ($optionalcondition)\nReturn the first child of the element, or the first child matching the $optionalcondition\n(same as firstchild)\n\nfirstchildtext ($optionalcondition)\nReturn the text of the first child of the element, or the first child matching the\n$optionalcondition If there is no firstchild then returns ''. This avoids getting the\nchild, checking for its existence then getting the text for trivial cases.\n\nSimilar methods are available for the other navigation methods:\n\nlastchildtext\nprevsiblingtext\nnextsiblingtext\nprevelttext\nnextelttext\nchildtext\nparenttext\n\nAll this methods also exist in \"trimmed\" variant:\n\nfirstchildtrimmedtext\nlastchildtrimmedtext\nprevsiblingtrimmedtext\nnextsiblingtrimmedtext\nprevelttrimmedtext\nnextelttrimmedtext\nchildtrimmedtext\nparenttrimmedtext\n\nfield ($condition)\nSame method as \"firstchildtext\" with a different name\n\nfields ($conditionlist)\nReturn the list of field (text of first child matching the conditions), missing fields are\nreturned as the empty string.\n\nSame method as \"firstchildtext\" with a different name\n\ntrimmedfield ($optionalcondition)\nSame method as \"firstchildtrimmedtext\" with a different name\n\nsetfield ($condition, $optionalatts, @listofeltandstrings)\nSet the content of the first child of the element that matches $condition, the rest of the\narguments is the same as for \"setcontent\"\n\nIf no child matches $condition and if $condition is a valid XML element name, then a new\nelement by that name is created and inserted as the last child.\n\nfirstchildmatches ($optionalcondition)\nReturn the element if the first child of the element (if it exists) passes the\n$optionalcondition \"undef\" otherwise\n\nif( $elt->firstchildmatches( 'title')) ...\n\nis equivalent to\n\nif( $elt->{firstchild} && $elt->{firstchild}->passes( 'title'))\n\n\"firstchildis\" is another name for this method\n\nSimilar methods are available for the other navigation methods:\n\nlastchildmatches\nprevsiblingmatches\nnextsiblingmatches\npreveltmatches\nnexteltmatches\nchildmatches\nparentmatches\n\nisfirstchild ($optionalcondition)\nreturns true (the element) if the element is the first child of its parent (optionally that\nsatisfies the $optionalcondition)\n\nislastchild ($optionalcondition)\nreturns true (the element) if the element is the last child of its parent (optionally that\nsatisfies the $optionalcondition)\n\nprevsibling ($optionalcondition)\nReturn the previous sibling of the element, or the previous sibling matching\n$optionalcondition\n\nnextsibling ($optionalcondition)\nReturn the next sibling of the element, or the first one matching $optionalcondition.\n\nnextelt ($optionalelt, $optionalcondition)\nReturn the next elt (optionally matching $optionalcondition) of the element. This is\ndefined as the next element which opens after the current element opens. Which usually means\nthe first child of the element. Counter-intuitive as it might look this allows you to loop\nthrough the whole document by starting from the root.\n\nThe $optionalelt is the root of a subtree. When the \"nextelt\" is out of the subtree then\nthe method returns undef. You can then walk a sub-tree with:\n\nmy $elt= $subtreeroot;\nwhile( $elt= $elt->nextelt( $subtreeroot))\n{ # insert processing code here\n}\n\nprevelt ($optionalcondition)\nReturn the previous elt (optionally matching $optionalcondition) of the element. This is\nthe first element which opens before the current one. It is usually either the last\ndescendant of the previous sibling or simply the parent\n\nnextnelt ($offset, $optionalcondition)\nReturn the $offset-th element that matches the $optionalcondition\n\nfollowingelt\nReturn the following element (as per the XPath following axis)\n\nprecedingelt\nReturn the preceding element (as per the XPath preceding axis)\n\nfollowingelts\nReturn the list of following elements (as per the XPath following axis)\n\nprecedingelts\nReturn the list of preceding elements (as per the XPath preceding axis)\n\nchildren ($optionalcondition)\nReturn the list of children (optionally which matches $optionalcondition) of the element.\nThe list is in document order.\n\nchildrencount ($optionalcondition)\nReturn the number of children of the element (optionally which matches $optionalcondition)\n\nchildrentext ($optionalcondition)\nIn array context, returns an array containing the text of children of the element\n(optionally which matches $optionalcondition)\n\nIn scalar context, returns the concatenation of the text of children of the element\n\nchildrentrimmedtext ($optionalcondition)\nIn array context, returns an array containing the trimmed text of children of the element\n(optionally which matches $optionalcondition)\n\nIn scalar context, returns the concatenation of the trimmed text of children of the element\n\nchildrencopy ($optionalcondition)\nReturn a list of elements that are copies of the children of the element, optionally which\nmatches $optionalcondition\n\ndescendants ($optionalcondition)\nReturn the list of all descendants (optionally which matches $optionalcondition) of the\nelement. This is the equivalent of the \"getElementsByTagName\" of the DOM (by the way, if you\nare really a DOM addict, you can use \"getElementsByTagName\" instead)\n\ngetElementsByTagName ($optionalcondition)\nSame as \"descendants\"\n\nfindbytagname ($optionalcondition)\nSame as \"descendants\"\n\ndescendantsorself ($optionalcondition)\nSame as \"descendants\" except that the element itself is included in the list if it matches\nthe $optionalcondition\n\nfirstdescendant ($optionalcondition)\nReturn the first descendant of the element that matches the condition\n\nlastdescendant ($optionalcondition)\nReturn the last descendant of the element that matches the condition\n\nancestors ($optionalcondition)\nReturn the list of ancestors (optionally matching $optionalcondition) of the element. The\nlist is ordered from the innermost ancestor to the outermost one\n\nNOTE: the element itself is not part of the list, in order to include it you will have to\nuse ancestorsorself\n\nancestorsorself ($optionalcondition)\nReturn the list of ancestors (optionally matching $optionalcondition) of the element,\nincluding the element (if it matches the condition>). The list is ordered from the innermost\nancestor to the outermost one\n\npasses ($condition)\nReturn the element if it passes the $condition\n\natt ($att)\nReturn the value of attribute $att or \"undef\"\n\nlatt ($att)\nReturn the value of attribute $att or \"undef\"\n\nthis method is an lvalue, so you can do \"$elt->latt( 'foo')= 'bar'\" or \"$elt->latt(\n'foo')++;\"\n\nsetatt ($att, $attvalue)\nSet the attribute of the element to the given value\n\nYou can actually set several attributes this way:\n\n$elt->setatt( att1 => \"val1\", att2 => \"val2\");\n\ndelatt ($att)\nDelete the attribute for the element\n\nYou can actually delete several attributes at once:\n\n$elt->delatt( 'att1', 'att2', 'att3');\n\nattexists ($att)\nReturns true if the attribute $att exists for the element, false otherwise\n\ncut Cut the element from the tree. The element still exists, it can be copied or pasted\nsomewhere else, it is just not attached to the tree anymore.\n\nNote that the \"old\" links to the parent, previous and next siblings can still be accessed\nusing the former* methods\n\nformernextsibling\nReturns the former next sibling of a cut node (or undef if the node has not been cut)\n\nThis makes it easier to write loops where you cut elements:\n\nmy $child= $parent->firstchild( 'achild');\nwhile( $child->{'att'}->{'cut'})\n{ $child->cut; $child= ($child->{former} && $child->{former}->{nextsibling}); }\n\nformerprevsibling\nReturns the former previous sibling of a cut node (or undef if the node has not been cut)\n\nformerparent\nReturns the former parent of a cut node (or undef if the node has not been cut)\n\ncutchildren ($optionalcondition)\nCut all the children of the element (or all of those which satisfy the $optionalcondition).\n\nReturn the list of children\n\ncutdescendants ($optionalcondition)\nCut all the descendants of the element (or all of those which satisfy the\n$optionalcondition).\n\nReturn the list of descendants\n\ncopy ($elt)\nReturn a copy of the element. The copy is a \"deep\" copy: all sub-elements of the element are\nduplicated.\n\npaste ($optionalposition, $ref)\nPaste a (previously \"cut\" or newly generated) element. Die if the element already belongs to\na tree.\n\nNote that the calling element is pasted:\n\n$child->paste( firstchild => $existingparent);\n$newsibling->paste( after => $thissiblingisalreadyinthetree);\n\nor\n\nmy $newelt= XML::Twig::Elt->new( tag => $content);\n$newelt->paste( $position => $existingelt);\n\nExample:\n\nmy $t= XML::Twig->new->parse( 'doc.xml')\nmy $toc= $t->root->new( 'toc');\n$toc->paste( $t->root); # $toc is pasted as first child of the root\nforeach my $title ($t->findnodes( '/doc/section/title'))\n{ my $titletoc= $title->copy;\n# paste $titletoc as the last child of toc\n$titletoc->paste( lastchild => $toc)\n}\n\nPosition options:\n\nfirstchild (default)\nThe element is pasted as the first child of $ref\n\nlastchild\nThe element is pasted as the last child of $ref\n\nbefore\nThe element is pasted before $ref, as its previous sibling.\n\nafter\nThe element is pasted after $ref, as its next sibling.\n\nwithin\nIn this case an extra argument, $offset, should be supplied. The element will be pasted\nin the reference element (or in its first text child) at the given offset. To achieve\nthis the reference element will be split at the offset.\n\nNote that you can call directly the underlying method:\n\npastebefore\npasteafter\npastefirstchild\npastelastchild\npastewithin\n\nmove ($optionalposition, $ref)\nMove an element in the tree. This is just a \"cut\" then a \"paste\". The syntax is the same as\n\"paste\".\n\nreplace ($ref)\nReplaces an element in the tree. Sometimes it is just not possible to\"cut\" an element then\n\"paste\" another in its place, so \"replace\" comes in handy. The calling element replaces\n$ref.\n\nreplacewith (@elts)\nReplaces the calling element with one or more elements\n\ndelete\nCut the element and frees the memory.\n\nprefix ($text, $optionaloption)\nAdd a prefix to an element. If the element is a \"PCDATA\" element the text is added to the\npcdata, if the elements first child is a \"PCDATA\" then the text is added to it's pcdata,\notherwise a new \"PCDATA\" element is created and pasted as the first child of the element.\n\nIf the option is \"asis\" then the prefix is added asis: it is created in a separate \"PCDATA\"\nelement with an \"asis\" property. You can then write:\n\n$elt1->prefix( '', 'asis');\n\nto create a \"\" in the output of \"print\".\n\nsuffix ($text, $optionaloption)\nAdd a suffix to an element. If the element is a \"PCDATA\" element the text is added to the\npcdata, if the elements last child is a \"PCDATA\" then the text is added to it's pcdata,\notherwise a new PCDATA element is created and pasted as the last child of the element.\n\nIf the option is \"asis\" then the suffix is added asis: it is created in a separate \"PCDATA\"\nelement with an \"asis\" property. You can then write:\n\n$elt2->suffix( '', 'asis');\n\ntrim\nTrim the element in-place: spaces at the beginning and at the end of the element are\ndiscarded and multiple spaces within the element (or its descendants) are replaced by a\nsingle space.\n\nNote that in some cases you can still end up with multiple spaces, if they are split between\nseveral elements:\n\n text hah! yep\n\ngets trimmed to\n\ntext hah! yep\n\nThis is somewhere in between a bug and a feature.\n\nnormalize\nmerge together all consecutive pcdata elements in the element (if for example you have\nturned some elements into pcdata using \"erase\", this will give you a \"clean\" element in\nwhich there all text fragments are as long as possible).\n\nsimplify (%options)\nReturn a data structure suspiciously similar to XML::Simple's. Options are identical to\nXMLin options, see XML::Simple doc for more details (or use DATA::dumper or YAML to dump the\ndata structure)\n\nNote: there is no magic here, if you write \"$twig->parsefile( $file )->simplify();\" then it\nwill load the entire document in memory. I am afraid you will have to put some work into it\nto get just the bits you want and discard the rest. Look at the synopsis or the XML::Twig\n101 section at the top of the docs for more information.\n\ncontentkey\nforcearray\nkeyattr\nnoattr\nnormalizespace\naka normalisespace\n\nvariables (%varhash)\n%varhash is a hash { name => value }\n\nThis option allows variables in the XML to be expanded when the file is read. (there is\nno facility for putting the variable names back if you regenerate XML using XMLout).\n\nA 'variable' is any text of the form ${name} (or $name) which occurs in an attribute\nvalue or in the text content of an element. If 'name' matches a key in the supplied\nhashref, ${name} will be replaced with the corresponding value from the hashref. If no\nmatching key is found, the variable will not be replaced.\n\nvaratt ($attributename)\nThis option gives the name of an attribute that will be used to create variables in the\nXML:\n\n\n

/usr/local\n$prefix/bin\n\n\nuse \"var => 'name'\" to get $prefix replaced by /usr/local in the generated data\nstructure\n\nBy default variables are captured by the following regexp: /$(\\w+)/\n\nvarregexp (regexp)\nThis option changes the regexp used to capture variables. The variable name should be in\n$1\n\ngrouptags { grouping tag => grouped tag, grouping tag 2 => grouped tag 2...}\nOption used to simplify the structure: elements listed will not be used. Their children\nwill be, they will be considered children of the element parent.\n\nIf the element is:\n\n\nlocalhost\n\n/home/mrodrigu/standards\n$base/tools\n\n\n\n\n\n\n\nThen calling simplify with \"grouptags => { dirs => 'dir', templates => 'template'}\"\nmakes the data structure be exactly as if the start and end tags for \"dirs\" and\n\"templates\" were not there.\n\nA YAML dump of the structure\n\nbase: '/home/mrodrigu/standards'\nhost: laptop.xmltwig.org\nserver: localhost\ntemplate:\n- stddef.templ\n- dummy.templ\ntools: '$base/tools'\n\nsplitat ($offset)\nSplit a text (\"PCDATA\" or \"CDATA\") element in 2 at $offset, the original element now holds\nthe first part of the string and a new element holds the right part. The new element is\nreturned\n\nIf the element is not a text element then the first text child of the element is split\n\nsplit ( $optionalregexp, $tag1, $atts1, $tag2, $atts2...)\nSplit the text descendants of an element in place, the text is split using the $regexp, if\nthe regexp includes () then the matched separators will be wrapped in elements. $1 is\nwrapped in $tag1, with attributes $atts1 if $atts1 is given (as a hashref), $2 is wrapped in\n$tag2...\n\nif $elt is \"

tati tata tutu tati titi tata tati tata

\"\n\n$elt->split( qr/(ta)ti/, 'foo', {type => 'toto'} )\n\nwill change $elt to\n\n

ta tata tutu ta\ntiti tata ta tata

\n\nThe regexp can be passed either as a string or as \"qr//\" (perl 5.005 and later), it defaults\nto \\s+ just as the \"split\" built-in (but this would be quite a useless behaviour without the\n$optionaltag parameter)\n\n$optionaltag defaults to PCDATA or CDATA, depending on the initial element type\n\nThe list of descendants is returned (including un-touched original elements and newly\ncreated ones)\n\nmark ( $regexp, $optionaltag, $optionalattributeref)\nThis method behaves exactly as split, except only the newly created elements are returned\n\nwrapchildren ( $regexpstring, $tag, $optionalattributehashref)\nWrap the children of the element that match the regexp in an element $tag. If\n$optionalattributehashref is passed then the new element will have these attributes.\n\nThe $regexpstring includes tags, within pointy brackets, as in \"<para>+\" and the\nusual Perl modifiers (+*?...). Tags can be further qualified with attributes: \"<para\ntype=\"warning\" classif=\"cosmicsecret\">+\". The values for attributes should be xml-escaped:\n\"<candy type=\"M&Ms\">*\" (\"<\", \"&\" \">\" and \"\"\" should be escaped).\n\nNote that elements might get extra \"id\" attributes in the process. See addid. Use stripatt\nto remove unwanted id's.\n\nHere is an example:\n\nIf the element $elt has the following content:\n\n<elt>\n<p>para 1</p>\n<ll11>list 1 item 1 para 1</ll11>\n<ll1>list 1 item 1 para 2</ll1>\n<ll1n>list 1 item 2 para 1 (only para)</ll1n>\n<ll1n>list 1 item 3 para 1</ll1n>\n<ll1>list 1 item 3 para 2</ll1>\n<ll1>list 1 item 3 para 3</ll1>\n<ll11>list 2 item 1 para 1</ll11>\n<ll1>list 2 item 1 para 2</ll1>\n<ll1n>list 2 item 2 para 1 (only para)</ll1n>\n<ll1n>list 2 item 3 para 1</ll1n>\n<ll1>list 2 item 3 para 2</ll1>\n<ll1>list 2 item 3 para 3</ll1>\n</elt>\n\nThen the code\n\n$elt->wrapchildren( q{<ll11><ll1>*} , li => { type => \"ul1\" });\n$elt->wrapchildren( q{<ll1n><ll1>*} , li => { type => \"ul\" });\n\n$elt->wrapchildren( q{<li type=\"ul1\"><li type=\"ul\">+}, \"ul\");\n$elt->stripatt( 'id');\n$elt->stripatt( 'type');\n$elt->print;\n\nwill output:\n\n<elt>\n<p>para 1</p>\n<ul>\n<li>\n<ll11>list 1 item 1 para 1</ll11>\n<ll1>list 1 item 1 para 2</ll1>\n</li>\n<li>\n<ll1n>list 1 item 2 para 1 (only para)</ll1n>\n</li>\n<li>\n<ll1n>list 1 item 3 para 1</ll1n>\n<ll1>list 1 item 3 para 2</ll1>\n<ll1>list 1 item 3 para 3</ll1>\n</li>\n</ul>\n<ul>\n<li>\n<ll11>list 2 item 1 para 1</ll11>\n<ll1>list 2 item 1 para 2</ll1>\n</li>\n<li>\n<ll1n>list 2 item 2 para 1 (only para)</ll1n>\n</li>\n<li>\n<ll1n>list 2 item 3 para 1</ll1n>\n<ll1>list 2 item 3 para 2</ll1>\n<ll1>list 2 item 3 para 3</ll1>\n</li>\n</ul>\n</elt>\n\nsubstext ($regexp, $replace)\nsubstext does text substitution, similar to perl's \" s///\" operator.\n\n$regexp must be a perl regexp, created with the \"qr\" operator.\n\n$replace can include \"$1, $2\"... from the $regexp. It can also be used to create element and\nentities, by using \"&elt( tag => { att => val }, text)\" (similar syntax as \"new\") and \"&ent(\nname)\".\n\nHere is a rather complex example:\n\n$elt->substext( qr{(?<!do not )link to (http://([^\\s,]*))},\n'see &elt( a =>{ href => $1 }, $2)'\n);\n\nThis will replace text like *link to http://www.xmltwig.org* by *see <a\nhref=\"www.xmltwig.org\">www.xmltwig.org</a>*, but not *do not link to...*\n\nGenerating entities (here replacing spaces with  ):\n\n$elt->substext( qr{ }, '&ent( \" \")');\n\nor, using a variable:\n\nmy $ent=\" \";\n$elt->substext( qr{ }, \"&ent( '$ent')\");\n\nNote that the substitution is always global, as in using the \"g\" modifier in a perl\nsubstitution, and that it is performed on all text descendants of the element.\n\nBug: in the $regexp, you can only use \"\\1\", \"\\2\"... if the replacement expression does not\ninclude elements or attributes. eg\n\n$t->substext( qr/((t[aiou])\\2)/, '$2'); # ok, replaces toto, tata, titi, tutu by to, ta, ti, tu\n$t->substext( qr/((t[aiou])\\2)/, '&elt(p => $1)' ); # NOK, does not find toto...\n\naddid ($optionalcoderef)\nAdd an id to the element.\n\nThe id is an attribute, \"id\" by default, see the \"id\" option for XML::Twig \"new\" to change\nit. Use an id starting with \"#\" to get an id that's not output by print, flush or sprint,\nyet that allows you to use the eltid method to get the element easily.\n\nIf the element already has an id, no new id is generated.\n\nBy default the method create an id of the form \"twigid<nnnn>\", where \"<nnnn>\" is a number,\nincremented each time the method is called successfully.\n\nsetidseed ($prefix)\nby default the id generated by \"addid\" is \"twigid<nnnn>\", \"setidseed\" changes the\nprefix to $prefix and resets the number to 1\n\nstripatt ($att)\nRemove the attribute $att from all descendants of the element (including the element)\n\nReturn the element\n\nchangeattname ($oldname, $newname)\nChange the name of the attribute from $oldname to $newname. If there is no attribute\n$oldname nothing happens.\n\nlcattnames\nLower cases the name all the attributes of the element.\n", "subsections": [ { "name": "sort_children_on_value", "content": "Sort the children of the element in place according to their text. All children are sorted.\n\nReturn the element, with its children sorted.\n\n%options are\n\ntype : numeric | alpha (default: alpha)\norder : normal | reverse (default: normal)\n\nReturn the element, with its children sorted\n\nsortchildrenonatt ($att, %options)\nSort the children of the element in place according to attribute $att. %options are the same\nas for \"sortchildrenonvalue\"\n\nReturn the element.\n\nsortchildrenonfield ($tag, %options)\nSort the children of the element in place, according to the field $tag (the text of the\nfirst child of the child with this tag). %options are the same as for\n\"sortchildrenonvalue\".\n\nReturn the element, with its children sorted\n" }, { "name": "sort_children", "content": "Sort the children of the element in place. The $getkey argument is a reference to a\nfunction that returns the sort key when passed an element.\n\nFor example:\n\n$elt->sortchildren( sub { $[0]->{'att'}->{\"nb\"} + $[0]->text },\ntype => 'numeric', order => 'reverse'\n);\n\nfieldtoatt ($cond, $att)\nTurn the text of the first sub-element matched by $cond into the value of attribute $att of\nthe element. If $att is omitted then $cond is used as the name of the attribute, which makes\nsense only if $cond is a valid element (and attribute) name.\n\nThe sub-element is then cut.\n\natttofield ($att, $tag)\nTake the value of attribute $att and create a sub-element $tag as first child of the\nelement. If $tag is omitted then $att is used as the name of the sub-element.\n\ngetxpath ($xpath, $optionaloffset)\nReturn a list of elements satisfying the $xpath. $xpath is an XPATH-like expression.\n\nA subset of the XPATH abbreviated syntax is covered:\n\ntag\ntag[1] (or any other positive number)\ntag[last()]\ntag[@att] (the attribute exists for the element)\ntag[@att=\"val\"]\ntag[@att=~ /regexp/]\ntag[att1=\"val1\" and att2=\"val2\"]\ntag[att1=\"val1\" or att2=\"val2\"]\ntag[string()=\"toto\"] (returns tag elements which text (as per the text method)\nis toto)\ntag[string()=~/regexp/] (returns tag elements which text (as per the text\nmethod) matches regexp)\nexpressions can start with / (search starts at the document root)\nexpressions can start with . (search starts at the current element)\n// can be used to get all descendants instead of just direct children\n* matches any tag\n\nSo the following examples from the XPath\nrecommendation<http://www.w3.org/TR/xpath.html#path-abbrev> work:\n\npara selects the para element children of the context node\n* selects all element children of the context node\npara[1] selects the first para child of the context node\npara[last()] selects the last para child of the context node\n*/para selects all para grandchildren of the context node\n/doc/chapter[5]/section[2] selects the second section of the fifth chapter\nof the doc\nchapter//para selects the para element descendants of the chapter element\nchildren of the context node\n//para selects all the para descendants of the document root and thus selects\nall para elements in the same document as the context node\n//olist/item selects all the item elements in the same document as the\ncontext node that have an olist parent\n.//para selects the para element descendants of the context node\n.. selects the parent of the context node\npara[@type=\"warning\"] selects all para children of the context node that have\na type attribute with value warning\nemployee[@secretary and @assistant] selects all the employee children of the\ncontext node that have both a secretary attribute and an assistant\nattribute\n\nThe elements will be returned in the document order.\n\nIf $optionaloffset is used then only one element will be returned, the one with the\nappropriate offset in the list, starting at 0\n\nQuoting and interpolating variables can be a pain when the Perl syntax and the XPATH syntax\ncollide, so use alternate quoting mechanisms like q or qq (I like q{} and qq{} myself).\n\nHere are some more examples to get you started:\n\nmy $p1= \"p1\";\nmy $p2= \"p2\";\nmy @res= $t->getxpath( qq{p[string( \"$p1\") or string( \"$p2\")]});\n\nmy $a= \"a1\";\nmy @res= $t->getxpath( qq{//*[@att=\"$a\"]});\n\nmy $val= \"a1\";\nmy $exp= qq{//p[ \\@att='$val']}; # you need to use \\@ or you will get a warning\nmy @res= $t->getxpath( $exp);\n\nNote that the only supported regexps delimiters are / and that you must backslash all / in\nregexps AND in regular strings.\n\nXML::Twig does not provide natively full XPATH support, but you can use \"XML::Twig::XPath\"\nto get \"findnodes\" to use \"XML::XPath\" as the XPath engine, with full coverage of the spec.\n\n\"XML::Twig::XPath\" to get \"findnodes\" to use \"XML::XPath\" as the XPath engine, with full\ncoverage of the spec.\n\nfindnodes\nsame as\"getxpath\"\n\nfindnodes\nsame as \"getxpath\"\n\ntext @optionaloptions\nReturn a string consisting of all the \"PCDATA\" and \"CDATA\" in an element, without any tags.\nThe text is not XML-escaped: base entities such as \"&\" and \"<\" are not escaped.\n\nThe '\"norecurse\"' option will only return the text of the element, not of any included\nsub-elements (same as \"textonly\").\n\ntextonly\nSame as \"text\" except that the text returned doesn't include the text of sub-elements.\n\ntrimmedtext\nSame as \"text\" except that the text is trimmed: leading and trailing spaces are discarded,\nconsecutive spaces are collapsed\n\nsettext ($string)\nSet the text for the element: if the element is a \"PCDATA\", just set its text, otherwise cut\nall the children of the element and create a single \"PCDATA\" child for it, which holds the\ntext.\n\nmerge ($elt2)\nMove the content of $elt2 within the element\n\ninsert ($tag1, [$optionalatts1], $tag2, [$optionalatts2],...)\nFor each tag in the list inserts an element $tag as the only child of the element. The\nelement gets the optional attributes in\"$optionalatts<n>.\" All children of the element are\nset as children of the new element. The upper level element is returned.\n\n$p->insert( table => { border=> 1}, 'tr', 'td')\n\nput $p in a table with a visible border, a single \"tr\" and a single \"td\" and return the\n\"table\" element:\n\n<p><table border=\"1\"><tr><td>original content of p</td></tr></table></p>\n\nwrapin (@tag)\nWrap elements in @tag as the successive ancestors of the element, returns the new element.\n\"$elt->wrapin( 'td', 'tr', 'table')\" wraps the element as a single cell in a table for\nexample.\n\nOptionally each tag can be followed by a hashref of attributes, that will be set on the\nwrapping element:\n\n$elt->wrapin( p => { class => \"advisory\" }, div => { class => \"intro\", id => \"divintro\" });\n\ninsertnewelt ($optposition, $tag, $optattshashref, @optcontent)\nCombines a \"new \" and a \"paste \": creates a new element using $tag, $optattshashref and\n@optcontent which are arguments similar to those for \"new\", then paste it, using\n$optposition or 'firstchild', relative to $elt.\n\nReturn the newly created element\n\nerase\nErase the element: the element is deleted and all of its children are pasted in its place.\n\nsetcontent ( $optionalatts, @listofeltandstrings) ( $optionalatts, '#EMPTY')\nSet the content for the element, from a list of strings and elements. Cuts all the element\nchildren, then pastes the list elements as the children. This method will create a \"PCDATA\"\nelement for any strings in the list.\n\nThe $optionalatts argument is the ref of a hash of attributes. If this argument is used\nthen the previous attributes are deleted, otherwise they are left untouched.\n\nWARNING: if you rely on ID's then you will have to set the id yourself. At this point the\nelement does not belong to a twig yet, so the ID attribute is not known so it won't be\nstored in the ID list.\n\nA content of '\"#EMPTY\"' creates an empty element;\n\nnamespace ($optionalprefix)\nReturn the URI of the namespace that $optionalprefix or the element name belongs to. If the\nname doesn't belong to any namespace, \"undef\" is returned.\n\nlocalname\nReturn the local name (without the prefix) for the element\n\nnsprefix\nReturn the namespace prefix for the element\n\ncurrentnsprefixes\nReturn a list of namespace prefixes valid for the element. The order of the prefixes in the\nlist has no meaning. If the default namespace is currently bound, '' appears in the list.\n\ninheritatt ($att, @optionaltaglist)\nReturn the value of an attribute inherited from parent tags. The value returned is found by\nlooking for the attribute in the element then in turn in each of its ancestors. If the\n@optionaltaglist is supplied only those ancestors whose tag is in the list will be\nchecked.\n\nallchildrenare ($optionalcondition)\nreturn 1 if all children of the element pass the $optionalcondition, 0 otherwise\n\nlevel ($optionalcondition)\nReturn the depth of the element in the twig (root is 0). If $optionalcondition is given\nthen only ancestors that match the condition are counted.\n\nWARNING: in a tree created using the \"twigroots\" option this will not return the level in\nthe document tree, level 0 will be the document root, level 1 will be the \"twigroots\"\nelements. During the parsing (in a \"twighandler\") you can use the \"depth\" method on the\ntwig object to get the real parsing depth.\n\nin ($potentialparent)\nReturn true if the element is in the potentialparent ($potentialparent is an element)\n\nincontext ($cond, $optionallevel)\nReturn true if the element is included in an element which passes $cond optionally within\n$optionallevel levels. The returned value is the including element.\n\npcdata\nReturn the text of a \"PCDATA\" element or \"undef\" if the element is not \"PCDATA\".\n\npcdataxmlstring\nReturn the text of a \"PCDATA\" element or undef if the element is not \"PCDATA\". The text is\n\"XML-escaped\" ('&' and '<' are replaced by '&' and '<')\n\nsetpcdata ($text)\nSet the text of a \"PCDATA\" element. This method does not check that the element is indeed a\n\"PCDATA\" so usually you should use \"settext\" instead.\n\nappendpcdata ($text)\nAdd the text at the end of a \"PCDATA\" element.\n\niscdata\nReturn 1 if the element is a \"CDATA\" element, returns 0 otherwise.\n\nistext\nReturn 1 if the element is a \"CDATA\" or \"PCDATA\" element, returns 0 otherwise.\n\ncdata\nReturn the text of a \"CDATA\" element or \"undef\" if the element is not \"CDATA\".\n\ncdatastring\nReturn the XML string of a \"CDATA\" element, including the opening and closing markers.\n\nsetcdata ($text)\nSet the text of a \"CDATA\" element.\n\nappendcdata ($text)\nAdd the text at the end of a \"CDATA\" element.\n\nremovecdata\nTurns all \"CDATA\" sections in the element into regular \"PCDATA\" elements. This is useful\nwhen converting XML to HTML, as browsers do not support CDATA sections.\n\nextradata\nReturn the extradata (comments and PI's) attached to an element\n\nsetextradata ($extradata)\nSet the extradata (comments and PI's) attached to an element\n\nappendextradata ($extradata)\nAppend extradata to the existing extradata before the element (if no previous extradata\nexists then it is created)\n\nsetasis\nSet a property of the element that causes it to be output without being XML escaped by the\nprint functions: if it contains \"a < b\" it will be output as such and not as \"a < b\".\nThis can be useful to create text elements that will be output as markup. Note that all\n\"PCDATA\" descendants of the element are also marked as having the property (they are the\nones that are actually impacted by the change).\n\nIf the element is a \"CDATA\" element it will also be output asis, without the \"CDATA\"\nmarkers. The same goes for any \"CDATA\" descendant of the element\n\nsetnotasis\nUnsets the \"asis\" property for the element and its text descendants.\n\nisasis\nReturn the \"asis\" property status of the element ( 1 or \"undef\")\n\nclosed\nReturn true if the element has been closed. Might be useful if you are somewhere in the\ntree, during the parse, and have no idea whether a parent element is completely loaded or\nnot.\n\ngettype\nReturn the type of the element: '\"#ELT\"' for \"real\" elements, or '\"#PCDATA\"', '\"#CDATA\"',\n'\"#COMMENT\"', '\"#ENT\"', '\"#PI\"'\n\niselt\nReturn the tag if the element is a \"real\" element, or 0 if it is \"PCDATA\", \"CDATA\"...\n\ncontainsonlytext\nReturn 1 if the element does not contain any other \"real\" element\n\ncontainsonly ($exp)\nReturn the list of children if all children of the element match the expression $exp\n\nif( $para->containsonly( 'tt')) { ... }\n\ncontainsasingle ($exp)\nIf the element contains a single child that matches the expression $exp returns that\nelement. Otherwise returns 0.\n\nisfield\nsame as \"containsonlytext\"\n\nispcdata\nReturn 1 if the element is a \"PCDATA\" element, returns 0 otherwise.\n\nisent\nReturn 1 if the element is an entity (an unexpanded entity) element, return 0 otherwise.\n\nisempty\nReturn 1 if the element is empty, 0 otherwise\n\nsetempty\nFlags the element as empty. No further check is made, so if the element is actually not\nempty the output will be messed. The only effect of this method is that the output will be\n\"<tag att=\"value\"\"/>\".\n\nsetnotempty\nFlags the element as not empty. if it is actually empty then the element will be output as\n\"<tag att=\"value\"\"></tag>\"\n\nispi\nReturn 1 if the element is a processing instruction (\"#PI\") element, return 0 otherwise.\n\ntarget\nReturn the target of a processing instruction\n\nsettarget ($target)\nSet the target of a processing instruction\n\ndata\nReturn the data part of a processing instruction\n\nsetdata ($data)\nSet the data of a processing instruction\n\nsetpi ($target, $data)\nSet the target and data of a processing instruction\n\npistring\nReturn the string form of a processing instruction (\"<?target data?>\")\n\niscomment\nReturn 1 if the element is a comment (\"#COMMENT\") element, return 0 otherwise.\n\nsetcomment ($commenttext)\nSet the text for a comment\n\ncomment\nReturn the content of a comment (just the text, not the \"<!--\" and \"-->\")\n\ncommentstring\nReturn the XML string for a comment (\"<!-- comment -->\")\n\nNote that an XML comment cannot start or end with a '-', or include '--'\n(http://www.w3.org/TR/2008/REC-xml-20081126/#sec-comments), if that is the case (because you\nhave created the comment yourself presumably, as it could not be in the input XML), then a\nspace will be inserted before an initial '-', after a trailing one or between two '-' in the\ncomment (which could presumably mangle javascript \"hidden\" in an XHTML comment);\n\nsetent ($entity)\nSet an (non-expanded) entity (\"#ENT\"). $entity) is the entity text (\"&ent;\")\n\nent Return the entity for an entity (\"#ENT\") element (\"&ent;\")\n\nentname\nReturn the entity name for an entity (\"#ENT\") element (\"ent\")\n\nentstring\nReturn the entity, either expanded if the expanded version is available, or non-expanded\n(\"&ent;\") otherwise\n\nchild ($offset, $optionalcondition)\nReturn the $offset-th child of the element, optionally the $offset-th child that matches\n$optionalcondition. The children are treated as a list, so \"$elt->child( 0)\" is the first\nchild, while \"$elt->child( -1)\" is the last child.\n\nchildtext ($offset, $optionalcondition)\nReturn the text of a child or \"undef\" if the sibling does not exist. Arguments are the same\nas child.\n\nlastchild ($optionalcondition)\nReturn the last child of the element, or the last child matching $optionalcondition (ie the\nlast of the element children matching the condition).\n\nlastchildtext ($optionalcondition)\nSame as \"firstchildtext\" but for the last child.\n\nsibling ($offset, $optionalcondition)\nReturn the next or previous $offset-th sibling of the element, or the $offset-th one\nmatching $optionalcondition. If $offset is negative then a previous sibling is returned, if\n$offset is positive then a next sibling is returned. \"$offset=0\" returns the element if\nthere is no condition or if the element matches the condition>, \"undef\" otherwise.\n\nsiblingtext ($offset, $optionalcondition)\nReturn the text of a sibling or \"undef\" if the sibling does not exist. Arguments are the\nsame as \"sibling\".\n\nprevsiblings ($optionalcondition)\nReturn the list of previous siblings (optionally matching $optionalcondition) for the\nelement. The elements are ordered in document order.\n\nnextsiblings ($optionalcondition)\nReturn the list of siblings (optionally matching $optionalcondition) following the element.\nThe elements are ordered in document order.\n\nsiblings ($optionalcondition)\nReturn the list of siblings (optionally matching $optionalcondition) of the element\n(excluding the element itself). The elements are ordered in document order.\n\npos ($optionalcondition)\nReturn the position of the element in the children list. The first child has a position of 1\n(as in XPath).\n\nIf the $optionalcondition is given then only siblings that match the condition are counted.\nIf the element itself does not match the condition then 0 is returned.\n\natts\nReturn a hash ref containing the element attributes\n\nsetatts ({ att1=>$att1val, att2=> $att2val... })\nSet the element attributes with the hash ref supplied as the argument. The previous\nattributes are lost (ie the attributes set by \"setatts\" replace all of the attributes of\nthe element).\n\nYou can also pass a list instead of a hashref: \"$elt->setatts( att1 => 'val1',...)\"\n\ndelatts\nDeletes all the element attributes.\n\nattnb\nReturn the number of attributes for the element\n\nhasatts\nReturn true if the element has attributes (in fact return the number of attributes, thus\nbeing an alias to \"attnb\"\n\nhasnoatts\nReturn true if the element has no attributes, false (0) otherwise\n\nattnames\nreturn a list of the attribute names for the element\n\nattxmlstring ($att, $options)\nReturn the attribute value, where '&', '<' and quote (\" or the value of the quote option at\ntwig creation) are XML-escaped.\n\nThe options are passed as a hashref, setting \"escapegt\" to a true value will also escape\n'>' ($elt( 'myatt', { escapegt => 1 });\n\nsetid ($id)\nSet the \"id\" attribute of the element to the value. See \"eltid \" to change the id attribute\nname\n\nid Gets the id attribute value\n\ndelid ($id)\nDeletes the \"id\" attribute of the element and remove it from the id list for the document\n\nclass\nReturn the \"class\" attribute for the element (methods on the \"class\" attribute are quite\nconvenient when dealing with XHTML, or plain XML that will eventually be displayed using\nCSS)\n\nlclass\nsame as class, except that this method is an lvalue, so you can do \"$elt->lclass= \"foo\"\"\n\nsetclass ($class)\nSet the \"class\" attribute for the element to $class\n\naddclass ($class)\nAdd $class to the element \"class\" attribute: the new class is added only if it is not\nalready present.\n\nNote that classes are then sorted alphabetically, so the \"class\" attribute can be changed\neven if the class is already there\n\nremoveclass ($class)\nRemove $class from the element \"class\" attribute.\n\nNote that classes are then sorted alphabetically, so the \"class\" attribute can be changed\neven if the class is already there\n\naddtoclass ($class)\nalias for addclass\n\natttoclass ($att)\nSet the \"class\" attribute to the value of attribute $att\n\naddatttoclass ($att)\nAdd the value of attribute $att to the \"class\" attribute of the element\n\nmoveatttoclass ($att)\nAdd the value of attribute $att to the \"class\" attribute of the element and delete the\nattribute\n\ntagtoclass\nSet the \"class\" attribute of the element to the element tag\n\naddtagtoclass\nAdd the element tag to its \"class\" attribute\n\nsettagclass ($newtag)\nAdd the element tag to its \"class\" attribute and sets the tag to $newtag\n\ninclass ($class)\nReturn true (1) if the element is in the class $class (if $class is one of the tokens in the\nelement \"class\" attribute)\n\ntagtospan\nChange the element tag tp \"span\" and set its class to the old tag\n\ntagtodiv\nChange the element tag tp \"div\" and set its class to the old tag\n\nDESTROY\nFrees the element from memory.\n\nstarttag\nReturn the string for the start tag for the element, including the \"/>\" at the end of an\nempty element tag\n\nendtag\nReturn the string for the end tag of an element. For an empty element, this returns the\nempty string ('').\n\nxmlstring @optionaloptions\nEquivalent to \"$elt->sprint( 1)\", returns the string for the entire element, excluding the\nelement's tags (but nested element tags are present)\n\nThe '\"norecurse\"' option will only return the text of the element, not of any included\nsub-elements (same as \"xmltextonly\").\n\ninnerxml\nAnother synonym for xmlstring\n\nouterxml\nAnother synonym for sprint\n\nxmltext\nReturn the text of the element, encoded (and processed by the current \"outputfilter\" or\n\"outputencoding\" options, without any tag.\n\nxmltextonly\nSame as \"xmltext\" except that the text returned doesn't include the text of sub-elements.\n\nsetprettyprint ($style)\nSet the pretty print method, amongst '\"none\"' (default), '\"nsgmls\"', '\"nice\"', '\"indented\"',\n'\"record\"' and '\"recordc\"'\n\nprettyprint styles:\n\nnone\nthe default, no \"\\n\" is used\n\nnsgmls\nnsgmls style, with \"\\n\" added within tags\n\nnice\nadds \"\\n\" wherever possible (NOT SAFE, can lead to invalid XML)\n\nindented\nsame as \"nice\" plus indents elements (NOT SAFE, can lead to invalid XML)\n\nrecord\ntable-oriented pretty print, one field per line\n\nrecordc\ntable-oriented pretty print, more compact than \"record\", one record per line\n\nsetemptytagstyle ($style)\nSet the method to output empty tags, amongst '\"normal\"' (default), '\"html\"', and '\"expand\"',\n\n\"normal\" outputs an empty tag '\"<tag/>\"', \"html\" adds a space '\"<tag />\"' for elements that\ncan be empty in XHTML and \"expand\" outputs '\"<tag></tag>\"'\n\nsetremovecdata ($flag)\nset (or unset) the flag that forces the twig to output CDATA sections as regular (escaped)\nPCDATA\n\nsetindent ($string)\nSet the indentation for the indented pretty print style (default is 2 spaces)\n\nsetquote ($quote)\nSet the quotes used for attributes. can be '\"double\"' (default) or '\"single\"'\n\ncmp ($elt)\nCompare the order of the 2 elements in a twig.\n\nC<$a> is the <A>..</A> element, C<$b> is the <B>...</B> element\n\ndocument $a->cmp( $b)\n<A> ... </A> ... <B> ... </B> -1\n<A> ... <B> ... </B> ... </A> -1\n<B> ... </B> ... <A> ... </A> 1\n<B> ... <A> ... </A> ... </B> 1\n$a == $b 0\n$a and $b not in the same tree undef\n\nbefore ($elt)\nReturn 1 if $elt starts before the element, 0 otherwise. If the 2 elements are not in the\nsame twig then return \"undef\".\n\nif( $a->cmp( $b) == -1) { return 1; } else { return 0; }\n\nafter ($elt)\nReturn 1 if $elt starts after the element, 0 otherwise. If the 2 elements are not in the\nsame twig then return \"undef\".\n\nif( $a->cmp( $b) == -1) { return 1; } else { return 0; }\n\nother comparison methods\n\nlt\nle\ngt\nge\n\npath\nReturn the element context in a form similar to XPath's short form: '\"/root/tag1/../tag\"'\n\nxpath\nReturn a unique XPath expression that can be used to find the element again.\n\nIt looks like \"/doc/sect[3]/title\": unique elements do not have an index, the others do.\n\nflush\nflushes the twig up to the current element (strictly equivalent to \"$elt->root->flush\")\n\nprivate methods\nLow-level methods on the twig:\n\nsetparent ($parent)\nsetfirstchild ($firstchild)\nsetlastchild ($lastchild)\nsetprevsibling ($prevsibling)\nsetnextsibling ($nextsibling)\nsettwigcurrent\ndeltwigcurrent\ntwigcurrent\ncontainstext\n\nThose methods should not be used, unless of course you find some creative and interesting,\nnot to mention useful, ways to do it.\n\ncond\nMost of the navigation functions accept a condition as an optional argument The first element\n(or all elements for \"children \" or \"ancestors \") that passes the condition is returned.\n\nThe condition is a single step of an XPath expression using the XPath subset defined by\n\"getxpath\". Additional conditions are:\n\nThe condition can be\n\n#ELT\nreturn a \"real\" element (not a PCDATA, CDATA, comment or pi element)\n\n#TEXT\nreturn a PCDATA or CDATA element\n\nregular expression\nreturn an element whose tag matches the regexp. The regexp has to be created with \"qr//\"\n(hence this is available only on perl 5.005 and above)\n\ncode reference\napplies the code, passing the current element as argument, if the code returns true then the\nelement is returned, if it returns false then the code is applied to the next candidate.\n\nXML::Twig::XPath\nXML::Twig implements a subset of XPath through the \"getxpath\" method.\n\nIf you want to use the whole XPath power, then you can use \"XML::Twig::XPath\" instead. In this\ncase \"XML::Twig\" uses \"XML::XPath\" to execute XPath queries. You will of course need\n\"XML::XPath\" installed to be able to use \"XML::Twig::XPath\".\n\nSee XML::XPath for more information.\n\nThe methods you can use are:\n\nfindnodes ($path)\nreturn a list of nodes found by $path.\n\nfindnodesasstring ($path)\nreturn the nodes found reproduced as XML. The result is not guaranteed to be valid XML\nthough.\n\nfindvalue ($path)\nreturn the concatenation of the text content of the result nodes\n\nIn order for \"XML::XPath\" to be used as the XPath engine the following methods are included in\n\"XML::Twig\":\n\nin XML::Twig\n\ngetRootNode\ngetParentNode\ngetChildNodes\n\nin XML::Twig::Elt\n\nstringvalue\ntoString\ngetName\ngetRootNode\ngetNextSibling\ngetPreviousSibling\nisElementNode\nisTextNode\nisPI\nisPINode\nisProcessingInstructionNode\nisComment\nisCommentNode\ngetTarget\ngetChildNodes\ngetElementById\n\nXML::Twig::XPath::Elt\nThe methods you can use are the same as on \"XML::Twig::XPath\" elements:\n\nfindnodes ($path)\nreturn a list of nodes found by $path.\n\nfindnodesasstring ($path)\nreturn the nodes found reproduced as XML. The result is not guaranteed to be valid XML\nthough.\n\nfindvalue ($path)\nreturn the concatenation of the text content of the result nodes\n\nXML::Twig::Entitylist\nnew Create an entity list.\n\nadd ($ent)\nAdd an entity to an entity list.\n\naddnewent ($name, $val, $sysid, $pubid, $ndata, $param)\nCreate a new entity and add it to the entity list\n\ndelete ($ent or $tag).\nDelete an entity (defined by its name or by the Entity object) from the list.\n\nprint ($optionalfilehandle)\nPrint the entity list.\n\nlist\nReturn the list as an array\n\nXML::Twig::Entity\nnew ($name, $val, $sysid, $pubid, $ndata, $param)\nSame arguments as the Entity handler for XML::Parser.\n\nprint ($optionalfilehandle)\nPrint an entity declaration.\n\nname\nReturn the name of the entity\n\nval Return the value of the entity\n\nsysid\nReturn the system id for the entity (for NDATA entities)\n\npubid\nReturn the public id for the entity (for NDATA entities)\n\nndata\nReturn true if the entity is an NDATA entity\n\nparam\nReturn true if the entity is a parameter entity\n\ntext\nReturn the entity declaration text.\n\nXML::Twig::Notationlist\nnew Create an notation list.\n\nadd ($notation)\nAdd an notation to an notation list.\n\naddnewnotation ($name, $base, $sysid, $pubid)\nCreate a new notation and add it to the notation list\n\ndelete ($notation or $tag).\nDelete an notation (defined by its name or by the Notation object) from the list.\n\nprint ($optionalfilehandle)\nPrint the notation list.\n\nlist\nReturn the list as an array\n\nXML::Twig::Notation\nnew ($name, $base, $sysid, $pubid)\nSame argumnotations as the Notation handler for XML::Parser.\n\nprint ($optionalfilehandle)\nPrint an notation declaration.\n\nname\nReturn the name of the notation\n\nbase\nReturn the base to be used for resolving a relative URI\n\nsysid\nReturn the system id for the notation\n\npubid\nReturn the public id for the notation\n\ntext\nReturn the notation declaration text.\n" } ] }, "EXAMPLES": { "content": "Additional examples (and a complete tutorial) can be found on the XML::Twig\nPage<http://www.xmltwig.org/xmltwig/>\n\nTo figure out what flush does call the following script with an XML file and an element name as\narguments\n\nuse XML::Twig;\n\nmy ($file, $elt)= @ARGV;\nmy $t= XML::Twig->new( twighandlers =>\n{ $elt => sub {$[0]->flush; print \"\\n[flushed here]\\n\";} });\n$t->parsefile( $file, ErrorContext => 2);\n$t->flush;\nprint \"\\n\";\n", "subsections": [] }, "NOTES": { "content": "", "subsections": [ { "name": "Subclassing XML::Twig", "content": "Useful methods:\n\neltclass\nIn order to subclass \"XML::Twig\" you will probably need to subclass also \"XML::Twig::Elt\".\nUse the \"eltclass\" option when you create the \"XML::Twig\" object to get the elements\ncreated in a different class (which should be a subclass of \"XML::Twig::Elt\".\n\naddoptions\nIf you inherit \"XML::Twig\" new method but want to add more options to it you can use this\nmethod to prevent XML::Twig to issue warnings for those additional options.\n\nDTD Handling\nThere are 3 possibilities here. They are:\n\nNo DTD\nNo doctype, no DTD information, no entity information, the world is simple...\n\nInternal DTD\nThe XML document includes an internal DTD, and maybe entity declarations.\n\nIf you use the loadDTD option when creating the twig the DTD information and the entity\ndeclarations can be accessed.\n\nThe DTD and the entity declarations will be \"flush\"'ed (or \"print\"'ed) either as is (if they\nhave not been modified) or as reconstructed (poorly, comments are lost, order is not kept,\ndue to it's content this DTD should not be viewed by anyone) if they have been modified. You\ncan also modify them directly by changing the \"$twig->{twigdoctype}->{internal}\" field\n(straight from XML::Parser, see the \"Doctype\" handler doc)\n\nExternal DTD\nThe XML document includes a reference to an external DTD, and maybe entity declarations.\n\nIf you use the \"loadDTD\" when creating the twig the DTD information and the entity\ndeclarations can be accessed. The entity declarations will be \"flush\"'ed (or \"print\"'ed)\neither as is (if they have not been modified) or as reconstructed (badly, comments are lost,\norder is not kept).\n\nYou can change the doctype through the \"$twig->setdoctype\" method and print the dtd through\nthe \"$twig->dtdtext\" or \"$twig->dtdprint\" methods.\n\nIf you need to modify the entity list this is probably the easiest way to do it.\n" }, { "name": "Flush", "content": "Remember that element handlers are called when the element is CLOSED, so if you have handlers\nfor nested elements the inner handlers will be called first. It makes it for example trickier\nthan it would seem to number nested sections (or clauses, or divs), as the titles in the inner\nsections are handled before the outer sections.\n" } ] }, "BUGS": { "content": "segfault during parsing\nThis happens when parsing huge documents, or lots of small ones, with a version of Perl\nbefore 5.16.\n\nThis is due to a bug in the way weak references are handled in Perl itself.\n\nThe fix is either to upgrade to Perl 5.16 or later (\"perlbrew\" is a great tool to manage\nseveral installations of perl on the same machine).\n\nAnother, NOT RECOMMENDED, way of fixing the problem, is to switch off weak references by\nwriting \"XML::Twig::setweakrefs( 0);\" at the top of the code. This is totally unsupported,\nand may lead to other problems though,\n\nentity handling\nDue to XML::Parser behaviour, non-base entities in attribute values disappear if they are\nnot declared in the document: \"att=\"val&ent;\"\" will be turned into \"att => val\", unless you\nuse the \"keepencoding\" argument to \"XML::Twig->new\"\n\nDTD handling\nThe DTD handling methods are quite bugged. No one uses them and it seems very difficult to\nget them to work in all cases, including with several slightly incompatible versions of\nXML::Parser and of libexpat.\n\nBasically you can read the DTD, output it back properly, and update entities, but not much\nmore.\n\nSo use XML::Twig with standalone documents, or with documents referring to an external DTD,\nbut don't expect it to properly parse and even output back the DTD.\n\nmemory leak\nIf you use a REALLY old Perl (5.005!) and a lot of twigs you might find that you leak quite\na lot of memory (about 2Ks per twig). You can use the \"dispose \" method to free that memory\nafter you are done.\n\nIf you create elements the same thing might happen, use the \"delete\" method to get rid of\nthem.\n\nAlternatively installing the \"Scalar::Util\" (or \"WeakRef\") module on a version of Perl that\nsupports it (>5.6.0) will get rid of the memory leaks automagically.\n\nID list\nThe ID list is NOT updated when elements are cut or deleted.\n\nchangegi\nThis method will not function properly if you do:\n\n$twig->changegi( $old1, $new);\n$twig->changegi( $old2, $new);\n$twig->changegi( $new, $evennewer);\n\nsanity check on XML::Parser method calls\nXML::Twig should really prevent calls to some XML::Parser methods, especially the\n\"setHandlers\" method.\n\npretty printing\nPretty printing (at least using the '\"indented\"' style) is hard to get right! Only elements\nthat belong to the document will be properly indented. Printing elements that do not belong\nto the twig makes it impossible for XML::Twig to figure out their depth, and thus their\nindentation level.\n\nAlso there is an unavoidable bug when using \"flush\" and pretty printing for elements with\nmixed content that start with an embedded element:\n\n<elt><b>b</b>toto<b>bold</b></elt>\n\nwill be output as\n\n<elt>\n<b>b</b>toto<b>bold</b></elt>\n\nif you flush the twig when you find the \"<b>\" element\n", "subsections": [] }, "Globals": { "content": "These are the things that can mess up calling code, especially if threaded. They might also\ncause problem under modperl.\n\nExported constants\nWhether you want them or not you get them! These are subroutines to use as constant when\ncreating or testing elements\n\nPCDATA return '#PCDATA'\nCDATA return '#CDATA'\nPI return '#PI', I had the choice between PROC and PI :--(\n\nModule scoped values: constants\nthese should cause no trouble:\n\n%baseent= ( '>' => '>',\n'<' => '<',\n'&' => '&',\n\"'\" => ''',\n'\"' => '"',\n);\nCDATASTART = \"<![CDATA[\";\nCDATAEND = \"]]>\";\nPISTART = \"<?\";\nPIEND = \"?>\";\nCOMMENTSTART = \"<!--\";\nCOMMENTEND = \"-->\";\n\npretty print styles\n\n( $NSGMLS, $NICE, $INDENTED, $INDENTEDC, $WRAPPED, $RECORD1, $RECORD2)= (1..7);\n\nempty tag output style\n\n( $HTML, $EXPAND)= (1..2);\n\nModule scoped values: might be changed\nMost of these deal with pretty printing, so the worst that can happen is probably that XML\noutput does not look right, but is still valid and processed identically by XML processors.\n\n$emptytagstyle can mess up HTML bowsers though and changing $ID would most likely create\nproblems.\n\n$pretty=0; # pretty print style\n$quote='\"'; # quote for attributes\n$INDENT= ' '; # indent for indented pretty print\n$emptytagstyle= 0; # how to display empty tags\n$ID # attribute used as an id ('id' by default)\n\nModule scoped values: definitely changed\nThese 2 variables are used to replace tags by an index, thus saving some space when creating\na twig. If they really cause you too much trouble, let me know, it is probably possible to\ncreate either a switch or at least a version of XML::Twig that does not perform this\noptimization.\n\n%gi2index; # tag => index\n@index2gi; # list of tags\n\nIf you need to manipulate all those values, you can use the following methods on the XML::Twig\nobject:\n\nglobalstate\nReturn a hashref with all the global variables used by XML::Twig\n\nThe hash has the following fields: \"pretty\", \"quote\", \"indent\", \"emptytagstyle\",\n\"keepencoding\", \"expandexternalentities\", \"outputfilter\", \"outputtextfilter\",\n\"keepattsorder\"\n\nsetglobalstate ($state)\nSet the global state, $state is a hashref\n\nsaveglobalstate\nSave the current global state\n\nrestoreglobalstate\nRestore the previously saved (using \"Lsaveglobalstate\"> state\n", "subsections": [] }, "TODO": { "content": "SAX handlers\nAllowing XML::Twig to work on top of any SAX parser\n\nmultiple twigs are not well supported\nA number of twig features are just global at the moment. These include the ID list and the\n\"tag pool\" (if you use \"changegi\" then you change the tag for ALL twigs).\n\nA future version will try to support this while trying not to be to hard on performance (at\nleast when a single twig is used!).\n", "subsections": [] }, "AUTHOR": { "content": "Michel Rodriguez <mirod@cpan.org>\n", "subsections": [] }, "LICENSE": { "content": "This library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nBug reports should be sent using: RT <http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-Twig>\n\nComments can be sent to mirod@cpan.org\n\nThe XML::Twig page is at <http://www.xmltwig.org/xmltwig/> It includes the development version\nof the module, a slightly better version of the documentation, examples, a tutorial and a:\nProcessing XML efficiently with Perl and XML::Twig:\n<http://www.xmltwig.org/xmltwig/tutorial/index.html>\n", "subsections": [] }, "SEE ALSO": { "content": "Complete docs, including a tutorial, examples, an easier to use HTML version of the docs, a\nquick reference card and a FAQ are available at <http://www.xmltwig.org/xmltwig/>\n\ngit repository at <http://github.com/mirod/xmltwig>\n\nXML::Parser, XML::Parser::Expat, XML::XPath, Encode, Text::Iconv, Scalar::Utils\n", "subsections": [ { "name": "Alternative Modules", "content": "XML::Twig is not the only XML::Processing module available on CPAN (far from it!).\n\nThe main alternative I would recommend is XML::LibXML.\n\nHere is a quick comparison of the 2 modules:\n\nXML::LibXML, actually \"libxml2\" on which it is based, sticks to the standards, and implements a\ngood number of them in a rather strict way: XML, XPath, DOM, RelaxNG, I must be forgetting a\ncouple (XInclude?). It is fast and rather frugal memory-wise.\n\nXML::Twig is older: when I started writing it XML::Parser/expat was the only game in town. It\nimplements XML and that's about it (plus a subset of XPath, and you can use XML::Twig::XPath if\nyou have XML::XPathEngine installed for full support). It is slower and requires more memory for\na full tree than XML::LibXML. On the plus side (yes, there is a plus side!) it lets you process\na big document in chunks, and thus let you tackle documents that couldn't be loaded in memory by\nXML::LibXML, and it offers a lot (and I mean a LOT!) of higher-level methods, for everything,\nfrom adding structure to \"low-level\" XML, to shortcuts for XHTML conversions and more. It also\nDWIMs quite a bit, getting comments and non-significant whitespaces out of the way but\npreserving them in the output for example. As it does not stick to the DOM, is also usually\nleads to shorter code than in XML::LibXML.\n\nBeyond the pure features of the 2 modules, XML::LibXML seems to be preferred by \"XML-purists\",\nwhile XML::Twig seems to be more used by Perl Hackers who have to deal with XML. As you have\nnoted, XML::Twig also comes with quite a lot of docs, but I am sure if you ask for help about\nXML::LibXML here or on Perlmonks you will get answers.\n\nNote that it is actually quite hard for me to compare the 2 modules: on one hand I know\nXML::Twig inside-out and I can get it to do pretty much anything I need to (or I improve it\n;--), while I have a very basic knowledge of XML::LibXML. So feature-wise, I'd rather use\nXML::Twig ;--). On the other hand, I am painfully aware of some of the deficiencies, potential\nbugs and plain ugly code that lurk in XML::Twig, even though you are unlikely to be affected by\nthem (unless for example you need to change the DTD of a document programmatically), while I\nhaven't looked much into XML::LibXML so it still looks shinny and clean to me.\n\nThat said, if you need to process a document that is too big to fit memory and XML::Twig is too\nslow for you, my reluctant advice would be to use \"bare\" XML::Parser. It won't be as easy to use\nas XML::Twig: basically with XML::Twig you trade some speed (depending on what you do from a\nfactor 3 to... none) for ease-of-use, but it will be easier IMHO than using SAX (albeit not\nstandard), and at this point a LOT faster (see the last test in\n<http://www.xmltwig.org/article/simplebenchmark/>).\n" } ] } }, "summary": "XML::Twig - A perl module for processing huge XML documents in tree mode.", "flags": [], "examples": [ "Additional examples (and a complete tutorial) can be found on the XML::Twig", "Page<http://www.xmltwig.org/xmltwig/>", "To figure out what flush does call the following script with an XML file and an element name as", "arguments", "use XML::Twig;", "my ($file, $elt)= @ARGV;", "my $t= XML::Twig->new( twighandlers =>", "{ $elt => sub {$[0]->flush; print \"\\n[flushed here]\\n\";} });", "$t->parsefile( $file, ErrorContext => 2);", "$t->flush;", "print \"\\n\";" ], "see_also": [] }