{
"content": [
{
"type": "text",
"text": "# XML::Generator (perldoc)\n\n## NAME\n\nXML::Generator - Perl extension for generating XML\n\n## SYNOPSIS\n\nuse XML::Generator ':pretty';\nprint foo(bar({ baz => 3 }, bam()),\nbar([ 'qux' => 'http://qux.com/' ],\n\"Hey there, world\"));\n# OR\nrequire XML::Generator;\nmy $X = XML::Generator->new(':pretty');\nprint $X->foo($X->bar({ baz => 3 }, $X->bam()),\n$X->bar([ 'qux' => 'http://qux.com/' ],\n\"Hey there, world\"));\nEither of the above yield:\n\n\n\n\nHey there, world\n\n\n## DESCRIPTION\n\nIn general, once you have an XML::Generator object, you then simply call methods on that object\nnamed for each XML tag you wish to generate.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CONSTRUCTOR**\n- **IMPORT ARGUMENTS**\n- **XML CONFORMANCE**\n- **SPECIAL TAGS**\n- **CREATING A SUBCLASS** (1 subsections)\n- **AUTHORS**\n- **LICENSE**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
}
],
"structuredContent": {
"command": "XML::Generator",
"section": "",
"mode": "perldoc",
"summary": "XML::Generator - Perl extension for generating XML",
"synopsis": "use XML::Generator ':pretty';\nprint foo(bar({ baz => 3 }, bam()),\nbar([ 'qux' => 'http://qux.com/' ],\n\"Hey there, world\"));\n# OR\nrequire XML::Generator;\nmy $X = XML::Generator->new(':pretty');\nprint $X->foo($X->bar({ baz => 3 }, $X->bam()),\n$X->bar([ 'qux' => 'http://qux.com/' ],\n\"Hey there, world\"));\nEither of the above yield:\n\n\n\n\nHey there, world\n",
"tldr_summary": null,
"tldr_examples": [],
"tldr_source": null,
"flags": [],
"examples": [],
"see_also": [],
"section_outline": [
{
"name": "NAME",
"lines": 2,
"subsections": []
},
{
"name": "SYNOPSIS",
"lines": 25,
"subsections": []
},
{
"name": "DESCRIPTION",
"lines": 143,
"subsections": []
},
{
"name": "CONSTRUCTOR",
"lines": 210,
"subsections": []
},
{
"name": "IMPORT ARGUMENTS",
"lines": 19,
"subsections": []
},
{
"name": "XML CONFORMANCE",
"lines": 13,
"subsections": []
},
{
"name": "SPECIAL TAGS",
"lines": 57,
"subsections": []
},
{
"name": "CREATING A SUBCLASS",
"lines": 11,
"subsections": [
{
"name": "authors",
"lines": 111
}
]
},
{
"name": "AUTHORS",
"lines": 9,
"subsections": []
},
{
"name": "LICENSE",
"lines": 3,
"subsections": []
},
{
"name": "SEE ALSO",
"lines": 3,
"subsections": []
}
],
"sections": {
"NAME": {
"content": "XML::Generator - Perl extension for generating XML\n",
"subsections": []
},
"SYNOPSIS": {
"content": "use XML::Generator ':pretty';\n\nprint foo(bar({ baz => 3 }, bam()),\nbar([ 'qux' => 'http://qux.com/' ],\n\"Hey there, world\"));\n\n# OR\n\nrequire XML::Generator;\n\nmy $X = XML::Generator->new(':pretty');\n\nprint $X->foo($X->bar({ baz => 3 }, $X->bam()),\n$X->bar([ 'qux' => 'http://qux.com/' ],\n\"Hey there, world\"));\n\nEither of the above yield:\n\n\n\n\n\nHey there, world\n\n",
"subsections": []
},
"DESCRIPTION": {
"content": "In general, once you have an XML::Generator object, you then simply call methods on that object\nnamed for each XML tag you wish to generate.\n\nXML::Generator can also arrange for undefined subroutines in the caller's package to generate\nthe corresponding XML, by exporting an \"AUTOLOAD\" subroutine to your package. Just supply an\n':import' argument to your \"use XML::Generator;\" call. If you already have an \"AUTOLOAD\" defined\nthen XML::Generator can be configured to cooperate with it. See \"STACKABLE AUTOLOADs\".\n\nSay you want to generate this XML:\n\n\nBob\n34\nAccountant\n\n\nHere's a snippet of code that does the job, complete with pretty printing:\n\nuse XML::Generator;\nmy $gen = XML::Generator->new(':pretty');\nprint $gen->person(\n$gen->name(\"Bob\"),\n$gen->age(34),\n$gen->job(\"Accountant\")\n);\n\nThe only problem with this is if you want to use a tag name that Perl's lexer won't understand\nas a method name, such as \"shoe-size\". Fortunately, since you can store the name of a method in\na variable, there's a simple work-around:\n\nmy $shoesize = \"shoe-size\";\n$xml = $gen->$shoesize(\"12 1/2\");\n\nWhich correctly generates:\n\n12 1/2\n\nYou can use a hash ref as the first parameter if the tag should include atributes. Normally this\nmeans that the order of the attributes will be unpredictable, but if you have the Tie::IxHash\nmodule, you can use it to get the order you want, like this:\n\nuse Tie::IxHash;\ntie my %attr, 'Tie::IxHash';\n\n%attr = (name => 'Bob',\nage => 34,\njob => 'Accountant',\n'shoe-size' => '12 1/2');\n\nprint $gen->person(\\%attr);\n\nThis produces\n\n\n\nAn array ref can also be supplied as the first argument to indicate a namespace for the element\nand the attributes.\n\nIf there is one element in the array, it is considered the URI of the default namespace, and the\ntag will have an xmlns=\"URI\" attribute added automatically. If there are two elements, the first\nshould be the tag prefix to use for the namespace and the second element should be the URI. In\nthis case, the prefix will be used for the tag and an xmlns:PREFIX attribute will be\nautomatically added. Prior to version 0.99, this prefix was also automatically added to each\nattribute name. Now, the default behavior is to leave the attributes alone (although you may\nalways explicitly add a prefix to an attribute name). If the prior behavior is desired, use the\nconstructor option \"qualifiedattributes\".\n\nIf you specify more than two elements, then each pair should correspond to a tag prefix and the\ncorresponding URL. An xmlns:PREFIX attribute will be added for each pair, and the prefix from\nthe first such pair will be used as the tag's namespace. If you wish to specify a default\nnamespace, use '#default' for the prefix. If the default namespace is first, then the tag will\nuse the default namespace itself.\n\nIf you want to specify a namespace as well as attributes, you can make the second argument a\nhash ref. If you do it the other way around, the array ref will simply get stringified and\nincluded as part of the content of the tag.\n\nHere's an example to show how the attribute and namespace parameters work:\n\n$xml = $gen->account(\n$gen->open(['transaction'], 2000),\n$gen->deposit(['transaction'], { date => '1999.04.03'}, 1500)\n);\n\nThis generates:\n\n\n2000\n1500\n\n\nBecause default namespaces inherit, XML::Generator takes care to output the xmlns=\"URI\"\nattribute as few times as strictly necessary. For example,\n\n$xml = $gen->account(\n$gen->open(['transaction'], 2000),\n$gen->deposit(['transaction'], { date => '1999.04.03'},\n$gen->amount(['transaction'], 1500)\n)\n);\n\nThis generates:\n\n\n2000\n\n1500\n\n\n\nNotice how \"xmlns=\"transaction\"\" was left out of the \" tag.\n\nHere is an example that uses the two-argument form of the namespace:\n\n$xml = $gen->widget(['wru' => 'http://www.widgets-r-us.com/xml/'],\n{'id' => 123}, $gen->contents());\n\n\n\n\n\nHere is an example that uses multiple namespaces. It generates the first example from the RDF\nprimer ().\n\nmy $contactNS = [contact => \"http://www.w3.org/2000/10/swap/pim/contact#\"];\n$xml = $gen->xml(\n$gen->RDF([ rdf => \"http://www.w3.org/1999/02/22-rdf-syntax-ns#\",\n@$contactNS ],\n$gen->Person($contactNS, { 'rdf:about' => \"http://www.w3.org/People/EM/contact#me\" },\n$gen->fullName($contactNS, 'Eric Miller'),\n$gen->mailbox($contactNS, {'rdf:resource' => \"mailto:em@w3.org\"}),\n$gen->personalTitle($contactNS, 'Dr.'))));\n\n\n\n\nEric Miller\n\nDr.\n\n\n",
"subsections": []
},
"CONSTRUCTOR": {
"content": "XML::Generator->new(':option', ...);\n\nXML::Generator->new(option => 'value', ...);\n\n(Both styles may be combined)\n\nThe following options are available:\n\n:std, :standard\nEquivalent to\n\nescape => 'always',\nconformance => 'strict',\n\n:strict\nEquivalent to\n\nconformance => 'strict',\n\n:pretty[=N]\nEquivalent to\n\nescape => 'always',\nconformance => 'strict',\npretty => N # N defaults to 2\n\nnamespace\nThis value of this option must be an array reference containing one or two values. If the array\ncontains one value, it should be a URI and will be the value of an 'xmlns' attribute in the\ntop-level tag. If there are two or more elements, the first of each pair should be the namespace\ntag prefix and the second the URI of the namespace. This will enable behavior similar to the\nnamespace behavior in previous versions; the tag prefix will be applied to each tag. In\naddition, an xmlns:NAME=\"URI\" attribute will be added to the top-level tag. Prior to version\n0.99, the tag prefix was also automatically added to each attribute name, unless overridden with\nan explicit prefix. Now, the attribute names are left alone, but if the prior behavior is\ndesired, use the constructor option \"qualifiedattributes\".\n\nThe value of this option is used as the global default namespace. For example,\n\nmy $html = XML::Generator->new(\npretty => 2,\nnamespace => [HTML => \"http://www.w3.org/TR/REC-html40\"]);\nprint $html->html(\n$html->body(\n$html->font({ face => 'Arial' },\n\"Hello, there\")));\n\nwould yield\n\n\n\nHello, there\n\n\n\nHere is the same example except without all the prefixes:\n\nmy $html = XML::Generator->new(\npretty => 2,\nnamespace => [\"http://www.w3.org/TR/REC-html40\"]);\nprint $html->html(\n$html->body(\n$html->font({ 'face' => 'Arial' },\n\"Hello, there\")));\n\nwould yield\n\n\n\nHello, there\n\n\n\nqualifiedAttributes, qualifiedattributes\nSet this to a true value to emulate the attribute prefixing behavior of XML::Generator prior to\nversion 0.99. Here is an example:\n\nmy $foo = XML::Generator->new(\nnamespace => [foo => \"http://foo.com/\"],\nqualifiedAttributes => 1);\nprint $foo->bar({baz => 3});\n\nyields\n\n\n\nescape\nThe contents and the values of each attribute have any illegal XML characters escaped if this\noption is supplied. If the value is 'always', then &, < and > (and \" within attribute values)\nwill be converted into the corresponding XML entity, although & will not be converted if it\nlooks like it could be part of a valid entity (but see below). If the value is 'unescaped', then\nthe escaping will be turned off character-by-character if the character in question is preceded\nby a backslash, or for the entire string if it is supplied as a scalar reference. So, for\nexample,\n\nuse XML::Generator escape => 'always';\n\none('<'); # <\ntwo('\\&'); # \\&\nthree(\\''); # (scalar refs always allowed)\nfour('<'); # < (looks like an entity)\nfive('"'); # " (looks like an entity)\n\nbut\n\nuse XML::Generator escape => 'unescaped';\n\none('<'); # <\ntwo('\\&'); # &\nthree(\\'');# (scalar refs always allowed)\nfour('<'); # < (no special case for entities)\n\nBy default, high-bit data will be passed through unmodified, so that UTF-8 data can be generated\nwith pre-Unicode perls. If you know that your data is ASCII, use the value 'high-bit' for the\nescape option and bytes with the high bit set will be turned into numeric entities. You can\ncombine this functionality with the other escape options by comma-separating the values:\n\nmy $a = XML::Generator->new(escape => 'always,high-bit');\nprint $a->foo(\"<\\242>\");\n\nyields\n\n<¢>\n\nBecause XML::Generator always uses double quotes (\"\") around attribute values, it does not\nescape single quotes. If you want single quotes inside attribute values to be escaped, use the\nvalue 'apos' along with 'always' or 'unescaped' for the escape option. For example:\n\nmy $gen = XML::Generator->new(escape => 'always,apos');\nprint $gen->foo({'bar' => \"It's all good\"});\n\n\n\nIf you actually want & to be converted to & even if it looks like it could be part of a\nvalid entity, use the value 'even-entities' along with 'always'. Supplying 'even-entities' to\nthe 'unescaped' option is meaningless as entities are already escaped with that option.\n\npretty\nTo have nice pretty printing of the output XML (great for config files that you might also want\nto edit by hand), supply an integer for the number of spaces per level of indenting, eg.\n\nmy $gen = XML::Generator->new(pretty => 2);\nprint $gen->foo($gen->bar('baz'),\n$gen->qux({ tricky => 'no'}, 'quux'));\n\nwould yield\n\n\nbaz\nquux\n\n\nYou may also supply a non-numeric string as the argument to 'pretty', in which case the indents\nwill consist of repetitions of that string. So if you want tabbed indents, you would use:\n\nmy $gen = XML::Generator->new(pretty => \"\\t\");\n\nPretty printing does not apply to CDATA sections or Processing Instructions.\n\nconformance\nIf the value of this option is 'strict', a number of syntactic checks are performed to ensure\nthat generated XML conforms to the formal XML specification. In addition, since entity names\nbeginning with 'xml' are reserved by the W3C, inclusion of this option enables several special\ntag names: xmlpi, xmlcmnt, xmldecl, xmldtd, xmlcdata, and xml to allow generation of processing\ninstructions, comments, XML declarations, DTD's, character data sections and \"final\" XML\ndocuments, respectively.\n\nInvalid characters (http://www.w3.org/TR/xml11/#charsets) will be filtered out. To disable this\nbehavior, supply the 'filterinvalidchars' option with the value 0.\n\nSee \"XML CONFORMANCE\" and \"SPECIAL TAGS\" for more information.\n\nfilterInvalidChars, filterinvalidchars\nSet this to a 1 to enable filtering of invalid characters, or to 0 to disable the filtering. See\nhttp://www.w3.org/TR/xml11/#charsets for the set of valid characters.\n\nallowedXMLTags, allowedxmltags\nIf you have specified 'conformance' => 'strict' but need to use tags that start with 'xml', you\ncan supply a reference to an array containing those tags and they will be accepted without\nerror. It is not an error to supply this option if 'conformance' => 'strict' is not supplied,\nbut it will have no effect.\n\nempty\nThere are 5 possible values for this option:\n\nself - create empty tags as (default)\ncompact - create empty tags as \nclose - close empty tags as \nignore - don't do anything (non-compliant!)\nargs - use count of arguments to decide between and \n\nMany web browsers like the 'self' form, but any one of the forms besides 'ignore' is acceptable\nunder the XML standard.\n\n'ignore' is intended for subclasses that deal with HTML and other SGML subsets which allow\natomic tags. It is an error to specify both 'conformance' => 'strict' and 'empty' => 'ignore'.\n\n'args' will produce if there are no arguments at all, or if there is just a single undef\nargument, and otherwise.\n\nversion\nSets the default XML version for use in XML declarations. See \"xmldecl\" below.\n\nencoding\nSets the default encoding for use in XML declarations.\n\ndtd\nSpecify the dtd. The value should be an array reference with three values; the type, the name\nand the uri.\n",
"subsections": []
},
"IMPORT ARGUMENTS": {
"content": "use XML::Generator ':option';\n\nuse XML::Generator option => 'value';\n\n(Both styles may be combined)\n\n:import\nCause \"use XML::Generator;\" to export an \"AUTOLOAD\" to your package that makes undefined\nsubroutines generate XML tags corresponding to their name. Note that if you already have an\n\"AUTOLOAD\" defined, it will be overwritten.\n\n:stacked\nImplies :import, but if there is already an \"AUTOLOAD\" defined, the overriding \"AUTOLOAD\" will\nstill give it a chance to run. See \"STACKABLE AUTOLOADs\".\n\nANYTHING ELSE\nIf you supply any other options, :import is implied and the XML::Generator object that is\ncreated to generate tags will be constructed with those options.\n",
"subsections": []
},
"XML CONFORMANCE": {
"content": "When the 'conformance' => 'strict' option is supplied, a number of syntactic checks are enabled.\nAll entity and attribute names are checked to conform to the XML specification, which states\nthat they must begin with either an alphabetic character or an underscore and may then consist\nof any number of alphanumerics, underscores, periods or hyphens. Alphabetic and alphanumeric are\ninterpreted according to the current locale if 'use locale' is in effect and according to the\nUnicode standard for Perl versions >= 5.6. Furthermore, entity or attribute names are not\nallowed to begin with 'xml' (in any case), although a number of special tags beginning with\n'xml' are allowed (see \"SPECIAL TAGS\"). Note that you can also supply an explicit list of\nallowed tags with the 'allowedxmltags' option.\n\nAlso, the filterinvalidchars option is automatically set to 1 unless it is explicitly set to\n0.\n",
"subsections": []
},
"SPECIAL TAGS": {
"content": "The following special tags are available when running under strict conformance (otherwise they\ndon't act special):\n\nxmlpi\nProcessing instruction; first argument is target, remaining arguments are attribute, value\npairs. Attribute names are syntax checked, values are escaped.\n\nxmlcmnt\nComment. Arguments are concatenated and placed inside comment delimiters. Any\noccurences of '--' in the concatenated arguments are converted to '--'\n\nxmldecl (@args)\nDeclaration. This can be used to specify the version, encoding, and other XML-related\ndeclarations (i.e., anything inside the tag). @args can be used to control what is\noutput, as keyword-value pairs.\n\nBy default, the version is set to the value specified in the constructor, or to 1.0 if it was\nnot specified. This can be overridden by providing a 'version' key in @args. If you do not want\nthe version at all, explicitly provide undef as the value in @args.\n\nBy default, the encoding is set to the value specified in the constructor; if no value was\nspecified, the encoding will be left out altogether. Provide an 'encoding' key in @args to\noverride this.\n\nIf a dtd was set in the constructor, the standalone attribute of the declaration will be set to\n'no' and the doctype declaration will be appended to the XML declartion, otherwise the\nstandalone attribute will be set to 'yes'. This can be overridden by providing a 'standalone'\nkey in @args. If you do not want the standalone attribute to show up, explicitly provide undef\nas the value.\n\nxmldtd\nDTD tag creation. The format of this method is different from others. Since DTD's are\nglobal and cannot contain namespace information, the first argument should be a reference to an\narray; the elements are concatenated together to form the DTD:\n\nprint $xml->xmldtd([ 'html', 'PUBLIC', $xhtmlw3c, $xhtmldtd ])\n\nThis would produce the following declaration:\n\n\n\nAssuming that $xhtmlw3c and $xhtmldtd had the correct values.\n\nNote that you can also specify a DTD on creation using the new() method's dtd option.\n\nxmlcdata\nCharacter data section; arguments are concatenated and placed inside character\ndata section delimiters. Any occurences of ']]>' in the concatenated arguments are converted to\n']]>'.\n\nxml\n\"Final\" XML document. Must be called with one and exactly one XML::Generator-produced XML\ndocument. Any combination of XML::Generator-produced XML comments or processing instructions may\nalso be supplied as arguments. Prepends an XML declaration, and re-blesses the argument into a\n\"final\" class that can't be embedded.\n",
"subsections": []
},
"CREATING A SUBCLASS": {
"content": "For a simpler way to implement subclass-like behavior, see \"STACKABLE AUTOLOADs\".\n\nAt times, you may find it desireable to subclass XML::Generator. For example, you might want to\nprovide a more application-specific interface to the XML generation routines provided. Perhaps\nyou have a custom database application and would really like to say:\n\nmy $dbxml = new XML::Generator::MyDatabaseApp;\nprint $dbxml->xml($dbxml->customtaghandler(@data));\n\nHere, customtaghandler() may be a method that builds a recursive XML structure based on the\ncontents of @data. In fact, it may even be named for a tag you want generated, such as",
"subsections": [
{
"name": "authors",
"content": "in the case of multiple elements).\n\nCreating a subclass of XML::Generator is actually relatively straightforward, there are just\nthree things you have to remember:\n\n1. All of the useful utilities are in XML::Generator::util.\n\n2. To construct a tag you simply have to call SUPER::tagname,\nwhere \"tagname\" is the name of your tag.\n\n3. You must fully-qualify the methods in XML::Generator::util.\n\nSo, let's assume that we want to provide a custom HTML table() method:\n\npackage XML::Generator::CustomHTML;\nuse base 'XML::Generator';\n\nsub table {\nmy $self = shift;\n\n# parse our args to get namespace and attribute info\nmy($namespace, $attr, @content) =\n$self->XML::Generator::util::parseargs(@)\n\n# check for strict conformance\nif ( $self->XML::Generator::util::config('conformance') eq 'strict' ) {\n# ... special checks ...\n}\n\n# ... special formatting magic happens ...\n\n# construct our custom tags\nreturn $self->SUPER::table($attr, $self->tr($self->td(@content)));\n}\n\nThat's pretty much all there is to it. We have to explicitly call SUPER::table() since we're\ninside the class's table() method. The others can simply be called directly, assuming that we\ndon't have a tr() in the current package.\n\nIf you want to explicitly create a specific tag by name, or just want a faster approach than\nAUTOLOAD provides, you can use the tag() method directly. So, we could replace that last line\nabove with:\n\n# construct our custom tags\nreturn $self->XML::Generator::util::tag('table', $attr, ...);\n\nHere, we must explicitly call tag() with the tag name itself as its first argument so it knows\nwhat to generate. These are the methods that you might find useful:\n\nXML::Generator::util::parseargs()\nThis parses the argument list and returns the namespace (arrayref), attributes (hashref),\nand remaining content (array), in that order.\n\nXML::Generator::util::tag()\nThis does the work of generating the appropriate tag. The first argument must be the name of\nthe tag to generate.\n\nXML::Generator::util::config()\nThis retrieves options as set via the new() method.\n\nXML::Generator::util::escape()\nThis escapes any illegal XML characters.\n\nRemember that all of these methods must be fully-qualified with the XML::Generator::util package\nname. This is because AUTOLOAD is used by the main XML::Generator package to create tags. Simply\ncalling parseargs() will result in a set of XML tags called .\n\nFinally, remember that since you are subclassing XML::Generator, you do not need to provide your\nown new() method. The one from XML::Generator is designed to allow you to properly subclass it.\n\nSTACKABLE AUTOLOADs\nAs a simpler alternative to traditional subclassing, the \"AUTOLOAD\" that \"use XML::Generator;\"\nexports can be configured to work with a pre-defined \"AUTOLOAD\" with the ':stacked' option.\nSimply ensure that your \"AUTOLOAD\" is defined before \"use XML::Generator ':stacked';\" executes.\nThe \"AUTOLOAD\" will get a chance to run first; the subroutine name will be in your $AUTOLOAD as\nnormal. Return an empty list to let the default XML::Generator \"AUTOLOAD\" run or any other value\nto abort it. This value will be returned as the result of the original method call.\n\nIf there is no \"import\" defined, XML::Generator will create one. All that this \"import\" does is\nexport AUTOLOAD, but that lets your package be used as if it were a subclass of XML::Generator.\n\nAn example will help:\n\npackage MyGenerator;\n\nmy %entities = ( copy => '©',\nnbsp => ' ', ... );\n\nsub AUTOLOAD {\nmy($tag) = our $AUTOLOAD =~ /.*::(.*)/;\n\nreturn $entities{$tag} if defined $entities{$tag};\nreturn;\n}\n\nuse XML::Generator qw(:pretty :stacked);\n\nThis lets someone do:\n\nuse MyGenerator;\n\nprint html(head(title(\"My Title\", copy())));\n\nProducing:\n\n\n\nMy Title©\n\n\n"
}
]
},
"AUTHORS": {
"content": "Benjamin Holzman \nOriginal author and maintainer\n\nBron Gondwana \nFirst modular version\n\nNathan Wiger \nModular rewrite to enable subclassing\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",
"subsections": []
},
"SEE ALSO": {
"content": "The XML::Writer module\nhttp://search.cpan.org/search?mode=module&query=XML::Writer\n",
"subsections": []
}
}
}
}