{
    "content": [
        {
            "type": "text",
            "text": "# XML::PatAct::ToObjects (perldoc)\n\n## NAME\n\nXML::PatAct::ToObjects - An action module for creating Perl objects\n\n## SYNOPSIS\n\nuse XML::PatAct::ToObjects;\nmy $patterns = [ PATTERN => [ OPTIONS ],\nPATTERN => \"PERL-CODE\",\n... ];\nmy $matcher = XML::PatAct::ToObjects->new( Patterns => $patterns,\nMatcher => $matcher,\nCopyId => 1,\nCopyAttributes => 1 );\n\n## DESCRIPTION\n\nXML::PatAct::ToObjects is a PerlSAX handler for applying pattern-action lists to XML parses or\ntrees. XML::PatAct::ToObjects creates Perl objects of the types and contents of the action items\nyou define.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (6 subsections)\n- **EXAMPLE**\n- **TODO**\n- **AUTHOR**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "XML::PatAct::ToObjects",
        "section": "",
        "mode": "perldoc",
        "summary": "XML::PatAct::ToObjects - An action module for creating Perl objects",
        "synopsis": "use XML::PatAct::ToObjects;\nmy $patterns = [ PATTERN => [ OPTIONS ],\nPATTERN => \"PERL-CODE\",\n... ];\nmy $matcher = XML::PatAct::ToObjects->new( Patterns => $patterns,\nMatcher => $matcher,\nCopyId => 1,\nCopyAttributes => 1 );",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "Ignore this element, but continue processing it's children (compare to -ignore). \"-pcdata\" may be used with this option."
            },
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "Ignore (discard) this element and it's children (compare to -holder)."
            },
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "Character data in this element should be copied to the \"Contents\" field. -make *PACKAGE* Create an object blessed into *PACKAGE*, and continue processing this element and it's children. *PACKAGE* may be the type `\"HASH\"' to simply create an anonyous hash. -args *ARGUMENTS* Use *ARGUMENTS* in creating the object specified by -make. This is commonly used to copy element attributes into fields in the newly created object. For example: -make => 'HASH', -args => 'URL => %{href}' would copy the `\"href\"' attribute in an element to the `\"URL\"' field of the newly created hash. -field *FIELD* Store this element, object, or children of this element in the parent object's field named by *FIELD*. -push-field *FIELD* Similar to -field, except that *FIELD* is an array and the contents are pushed onto that array. -value *VALUE* Use *VALUE* as a literal value to store in *FIELD*, otherwise ignoring this element and it's children. Only valid with -field or -push-field. `\"%{*ATTRIBUTE*}\"' notation can be used to substitute the value of an attribute into the literal value."
            },
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "Convert the contents of this element to a string (as in \"XML::Grove::AsString\") and store in *FIELD*. Only valid with -field or -push-field."
            },
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "Copy this element to *FIELD* without further processing. The element can then be processed later as the Perl objects are manipulated. Only valid with -field or -push-field. If ToObjects is used with PerlSAX, this will use XML::Grove::Builder to build the grove element."
            },
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "Used with -make, -grove-contents creates an object but then takes all of the content of that element and stores it in Contents. If an action item is a string, that string is treated as a fragment of Perl code. The following simple substitutions are performed on the fragment to provide easy access to the information being converted: @ELEM@ The object that caused this action to be called. If ToObjects is used with PerlSAX this will be a hash with the element name and attributes, with XML::Grove this will be the element object, with Data::Grove it will be the matching object, and with XML::DOM it will be an XML::DOM::Element."
            }
        ],
        "examples": [
            "The example pattern-action list below will convert the following XML representing a Database",
            "schema:",
            "<schema>",
            "<table>",
            "<name>MyTable</name>",
            "<summary>A short summary</summary>",
            "<description>A long description that may",
            "contain a subset of HTML</description>",
            "<column>",
            "<name>MyColumn1</name>",
            "<summary>A short summary</summary>",
            "<description>A long description</description>",
            "<unique/>",
            "<non-null/>",
            "<default>42</default>",
            "</column>",
            "</table>",
            "</schema>",
            "into Perl objects looking like:",
            "{ Name => \"MyTable\",",
            "Summary => \"A short summary\",",
            "Description => $groveobject,",
            "Columns => [",
            "{ Name => \"MyColumn1\",",
            "Summary => \"A short summary\",",
            "Description => $groveobject,",
            "Unique => 1,",
            "NonNull => 1,",
            "Default => 42",
            "Here is a Perl script and pattern-action list that will perform the conversion using the simple",
            "name matching pattern module XML::PatAct::MatchName. The script accepts a Schema XML file as an",
            "argument ($ARGV[0]) to the script. This script creates a grove as one of it's objects, so it",
            "requires the XML::Grove module.",
            "use XML::Parser::PerlSAX;",
            "use XML::PatAct::MatchName;",
            "use XML::PatAct::ToObjects;",
            "my $patterns = [",
            "'schema'      => [ qw{ -holder                                  } ],",
            "'table'       => [ qw{ -make Schema::Table                      } ],",
            "'name'        => [ qw{ -field Name -as-string                   } ],",
            "'summary'     => [ qw{ -field Summary -as-string                } ],",
            "'description' => [ qw{ -field Description -grove                } ],",
            "'column'      => [ qw{ -make Schema::Column -push-field Columns } ],",
            "'unique'      => [ qw{ -field Unique -value 1                   } ],",
            "'non-null'    => [ qw{ -field NonNull -value 1                  } ],",
            "'default'     => [ qw{ -field Default -as-string                } ],",
            "];",
            "my $matcher = XML::PatAct::MatchName->new( Patterns => $patterns );",
            "my $handler = XML::PatAct::ToObjects->new( Patterns => $patterns,",
            "Matcher => $matcher);",
            "my $parser = XML::Parser::PerlSAX->new( Handler => $handler );",
            "my $schema = $parser->parse(Source => { SystemId => $ARGV[0] } );"
        ],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 11,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 28,
                "subsections": [
                    {
                        "name": "-holder",
                        "lines": 3
                    },
                    {
                        "name": "-ignore",
                        "lines": 2
                    },
                    {
                        "name": "-pcdata",
                        "lines": 28
                    },
                    {
                        "name": "-as-string",
                        "lines": 3
                    },
                    {
                        "name": "-grove",
                        "lines": 5
                    },
                    {
                        "name": "-grove-contents",
                        "lines": 13
                    }
                ]
            },
            {
                "name": "EXAMPLE",
                "lines": 66,
                "subsections": []
            },
            {
                "name": "TODO",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 1,
                "subsections": [
                    {
                        "name": "perl",
                        "lines": 2
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "XML::PatAct::ToObjects - An action module for creating Perl objects\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use XML::PatAct::ToObjects;\n\nmy $patterns = [ PATTERN => [ OPTIONS ],\nPATTERN => \"PERL-CODE\",\n... ];\n\nmy $matcher = XML::PatAct::ToObjects->new( Patterns => $patterns,\nMatcher => $matcher,\nCopyId => 1,\nCopyAttributes => 1 );\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "XML::PatAct::ToObjects is a PerlSAX handler for applying pattern-action lists to XML parses or\ntrees. XML::PatAct::ToObjects creates Perl objects of the types and contents of the action items\nyou define.\n\nNew XML::PatAct::ToObject instances are creating by calling `new()'. Parameters can be passed as\na list of key, value pairs or a hash. `new()' requires the Patterns and Matcher parameters, the\nrest are optional:\n\nPatterns\nThe pattern-action list to apply.\n\nMatcher\nAn instance of the pattern or query matching module.\n\nCopyId\nCauses the `ID' attribute, if any, in a source XML element to be copied to an `ID' attribute\nin newly created objects. Note that IDs may be lost of no pattern matches that element or an\nobject is not created (\"-make\") for that element.\n\nCopyAttributes\nCauses all attributes of the element to be copied to the newly created objects.\n\nEach action can either be a list of options defined below or a string containing a fragment of\nPerl code. If the action is a string of Perl code then simple then some simple substitutions are\nmade as described further below.\n\nOptions that can be used in an action item containing an option-list:\n",
                "subsections": [
                    {
                        "name": "-holder",
                        "content": "Ignore this element, but continue processing it's children (compare to -ignore). \"-pcdata\"\nmay be used with this option.\n"
                    },
                    {
                        "name": "-ignore",
                        "content": "Ignore (discard) this element and it's children (compare to -holder).\n"
                    },
                    {
                        "name": "-pcdata",
                        "content": "Character data in this element should be copied to the \"Contents\" field.\n\n-make *PACKAGE*\nCreate an object blessed into *PACKAGE*, and continue processing this element and it's\nchildren. *PACKAGE* may be the type `\"HASH\"' to simply create an anonyous hash.\n\n-args *ARGUMENTS*\nUse *ARGUMENTS* in creating the object specified by -make. This is commonly used to copy\nelement attributes into fields in the newly created object. For example:\n\n-make => 'HASH', -args => 'URL => %{href}'\n\nwould copy the `\"href\"' attribute in an element to the `\"URL\"' field of the newly created\nhash.\n\n-field *FIELD*\nStore this element, object, or children of this element in the parent object's field named\nby *FIELD*.\n\n-push-field *FIELD*\nSimilar to -field, except that *FIELD* is an array and the contents are pushed onto that\narray.\n\n-value *VALUE*\nUse *VALUE* as a literal value to store in *FIELD*, otherwise ignoring this element and it's\nchildren. Only valid with -field or -push-field. `\"%{*ATTRIBUTE*}\"' notation can be used to\nsubstitute the value of an attribute into the literal value.\n"
                    },
                    {
                        "name": "-as-string",
                        "content": "Convert the contents of this element to a string (as in \"XML::Grove::AsString\") and store in\n*FIELD*. Only valid with -field or -push-field.\n"
                    },
                    {
                        "name": "-grove",
                        "content": "Copy this element to *FIELD* without further processing. The element can then be processed\nlater as the Perl objects are manipulated. Only valid with -field or -push-field. If\nToObjects is used with PerlSAX, this will use XML::Grove::Builder to build the grove\nelement.\n"
                    },
                    {
                        "name": "-grove-contents",
                        "content": "Used with -make, -grove-contents creates an object but then takes all of the content of that\nelement and stores it in Contents.\n\nIf an action item is a string, that string is treated as a fragment of Perl code. The following\nsimple substitutions are performed on the fragment to provide easy access to the information\nbeing converted:\n\n@ELEM@\nThe object that caused this action to be called. If ToObjects is used with PerlSAX this will\nbe a hash with the element name and attributes, with XML::Grove this will be the element\nobject, with Data::Grove it will be the matching object, and with XML::DOM it will be an\nXML::DOM::Element.\n"
                    }
                ]
            },
            "EXAMPLE": {
                "content": "The example pattern-action list below will convert the following XML representing a Database\nschema:\n\n<schema>\n<table>\n<name>MyTable</name>\n<summary>A short summary</summary>\n<description>A long description that may\ncontain a subset of HTML</description>\n<column>\n<name>MyColumn1</name>\n<summary>A short summary</summary>\n<description>A long description</description>\n<unique/>\n<non-null/>\n<default>42</default>\n</column>\n</table>\n</schema>\n\ninto Perl objects looking like:\n\n[\n{ Name => \"MyTable\",\nSummary => \"A short summary\",\nDescription => $groveobject,\nColumns => [\n{ Name => \"MyColumn1\",\nSummary => \"A short summary\",\nDescription => $groveobject,\nUnique => 1,\nNonNull => 1,\nDefault => 42\n}\n]\n}\n]\n\nHere is a Perl script and pattern-action list that will perform the conversion using the simple\nname matching pattern module XML::PatAct::MatchName. The script accepts a Schema XML file as an\nargument ($ARGV[0]) to the script. This script creates a grove as one of it's objects, so it\nrequires the XML::Grove module.\n\nuse XML::Parser::PerlSAX;\nuse XML::PatAct::MatchName;\nuse XML::PatAct::ToObjects;\n\nmy $patterns = [\n'schema'      => [ qw{ -holder                                  } ],\n'table'       => [ qw{ -make Schema::Table                      } ],\n'name'        => [ qw{ -field Name -as-string                   } ],\n'summary'     => [ qw{ -field Summary -as-string                } ],\n'description' => [ qw{ -field Description -grove                } ],\n'column'      => [ qw{ -make Schema::Column -push-field Columns } ],\n'unique'      => [ qw{ -field Unique -value 1                   } ],\n'non-null'    => [ qw{ -field NonNull -value 1                  } ],\n'default'     => [ qw{ -field Default -as-string                } ],\n];\n\nmy $matcher = XML::PatAct::MatchName->new( Patterns => $patterns );\nmy $handler = XML::PatAct::ToObjects->new( Patterns => $patterns,\nMatcher => $matcher);\n\nmy $parser = XML::Parser::PerlSAX->new( Handler => $handler );\nmy $schema = $parser->parse(Source => { SystemId => $ARGV[0] } );\n",
                "subsections": []
            },
            "TODO": {
                "content": "*   It'd be nice if patterns could be applied even in -as-string and -grove.\n\n*   Implement Perl code actions.\n\n*   -as-xml to write XML into the field.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Ken MacLeod, ken@bitsko.slc.ut.us\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "",
                "subsections": [
                    {
                        "name": "perl",
                        "content": "``Using PatAct Modules'' and ``Creating PatAct Modules'' in libxml-perl.\n"
                    }
                ]
            }
        }
    }
}