{
    "content": [
        {
            "type": "text",
            "text": "# Log::Log4perl::Config::DOMConfigurator (perldoc)\n\n## NAME\n\nLog::Log4perl::Config::DOMConfigurator - reads xml config files\n\n## SYNOPSIS\n\n--------------------------\n--using the log4j DTD--\n--------------------------\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4j:configuration SYSTEM \"log4j.dtd\">\n<log4j:configuration xmlns:log4j=\"http://jakarta.apache.org/log4j/\">\n<appender name=\"FileAppndr1\" class=\"org.apache.log4j.FileAppender\">\n<layout class=\"Log::Log4perl::Layout::PatternLayout\">\n<param name=\"ConversionPattern\"\nvalue=\"%d %4r [%t] %-5p %c %t - %m%n\"/>\n</layout>\n<param name=\"File\" value=\"t/tmp/DOMtest\"/>\n<param name=\"Append\" value=\"false\"/>\n</appender>\n<category name=\"a.b.c.d\" additivity=\"false\">\n<level value=\"warn\"/>  <!-- note lowercase! -->\n<appender-ref ref=\"FileAppndr1\"/>\n</category>\n<root>\n<priority value=\"warn\"/>\n<appender-ref ref=\"FileAppndr1\"/>\n</root>\n</log4j:configuration>\n--------------------------\n--using the log4perl DTD--\n--------------------------\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4perl:configuration SYSTEM \"log4perl.dtd\">\n<log4perl:configuration xmlns:log4perl=\"http://log4perl.sourceforge.net/\"\nthreshold=\"debug\" oneMessagePerAppender=\"true\">\n<log4perl:appender name=\"jabbender\" class=\"Log::Dispatch::Jabber\">\n<param-nested name=\"login\">\n<param name=\"hostname\" value=\"a.jabber.server\"/>\n<param name=\"password\" value=\"12345\"/>\n<param name=\"port\"     value=\"5222\"/>\n<param name=\"resource\" value=\"logger\"/>\n<param name=\"username\" value=\"bobjones\"/>\n</param-nested>\n<param name=\"to\" value=\"bob@a.jabber.server\"/>\n<param-text name=\"to\">\nmary@another.jabber.server\n</param-text>\n<log4perl:layout class=\"org.apache.log4j.PatternLayout\">\n<param name=\"ConversionPattern\" value = \"%K xx %G %U\"/>\n<cspec name=\"K\">\nsub { return sprintf \"%1x\", $$}\n</cspec>\n<cspec name=\"G\">\nsub {return 'thisistheGcspec'}\n</cspec>\n</log4perl:layout>\n</log4perl:appender>\n<log4perl:appender name=\"DBAppndr2\" class=\"Log::Log4perl::Appender::DBI\">\n<param name=\"warpmessage\" value=\"0\"/>\n<param name=\"datasource\" value=\"DBI:CSV:fdir=t/tmp\"/>\n<param name=\"bufferSize\" value=\"2\"/>\n<param name=\"password\" value=\"sub { $ENV{PWD} }\"/>\n<param name=\"username\" value=\"bobjones\"/>\n<param-text name=\"sql\">\nINSERT INTO log4perltest\n(loglevel, message, shortcaller, thingid,\ncategory, pkg, runtime1, runtime2)\nVALUES\n(?,?,?,?,?,?,?,?)\n</param-text>\n<param-nested name=\"params\">\n<param name=\"1\" value=\"%p\"/>\n<param name=\"3\" value=\"%5.5l\"/>\n<param name=\"5\" value=\"%c\"/>\n<param name=\"6\" value=\"%C\"/>\n</param-nested>\n<layout class=\"Log::Log4perl::Layout::NoopLayout\"/>\n</log4perl:appender>\n<category name=\"animal.dog\">\n<priority value=\"info\"/>\n<appender-ref ref=\"jabbender\"/>\n<appender-ref ref=\"DBAppndr2\"/>\n</category>\n<category name=\"plant\">\n<priority value=\"debug\"/>\n<appender-ref ref=\"DBAppndr2\"/>\n</category>\n<PatternLayout>\n<cspec name=\"U\"><![CDATA[\nsub {\nreturn \"UID $< GID $(\";\n}\n]]></cspec>\n</PatternLayout>\n</log4perl:configuration>\n\n## DESCRIPTION\n\nThis module implements an XML config, complementing the properties-style config described\nelsewhere.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **WHY**\n- **HOW**\n- **WHY NAMESPACES**\n- **VARIABLE SUBSTITUTION**\n- **REQUIRES**\n- **CAVEATS**\n- **CHANGES**\n- **SEE ALSO**\n- **LICENSE**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Log::Log4perl::Config::DOMConfigurator",
        "section": "",
        "mode": "perldoc",
        "summary": "Log::Log4perl::Config::DOMConfigurator - reads xml config files",
        "synopsis": "--------------------------\n--using the log4j DTD--\n--------------------------\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4j:configuration SYSTEM \"log4j.dtd\">\n<log4j:configuration xmlns:log4j=\"http://jakarta.apache.org/log4j/\">\n<appender name=\"FileAppndr1\" class=\"org.apache.log4j.FileAppender\">\n<layout class=\"Log::Log4perl::Layout::PatternLayout\">\n<param name=\"ConversionPattern\"\nvalue=\"%d %4r [%t] %-5p %c %t - %m%n\"/>\n</layout>\n<param name=\"File\" value=\"t/tmp/DOMtest\"/>\n<param name=\"Append\" value=\"false\"/>\n</appender>\n<category name=\"a.b.c.d\" additivity=\"false\">\n<level value=\"warn\"/>  <!-- note lowercase! -->\n<appender-ref ref=\"FileAppndr1\"/>\n</category>\n<root>\n<priority value=\"warn\"/>\n<appender-ref ref=\"FileAppndr1\"/>\n</root>\n</log4j:configuration>\n--------------------------\n--using the log4perl DTD--\n--------------------------\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4perl:configuration SYSTEM \"log4perl.dtd\">\n<log4perl:configuration xmlns:log4perl=\"http://log4perl.sourceforge.net/\"\nthreshold=\"debug\" oneMessagePerAppender=\"true\">\n<log4perl:appender name=\"jabbender\" class=\"Log::Dispatch::Jabber\">\n<param-nested name=\"login\">\n<param name=\"hostname\" value=\"a.jabber.server\"/>\n<param name=\"password\" value=\"12345\"/>\n<param name=\"port\"     value=\"5222\"/>\n<param name=\"resource\" value=\"logger\"/>\n<param name=\"username\" value=\"bobjones\"/>\n</param-nested>\n<param name=\"to\" value=\"bob@a.jabber.server\"/>\n<param-text name=\"to\">\nmary@another.jabber.server\n</param-text>\n<log4perl:layout class=\"org.apache.log4j.PatternLayout\">\n<param name=\"ConversionPattern\" value = \"%K xx %G %U\"/>\n<cspec name=\"K\">\nsub { return sprintf \"%1x\", $$}\n</cspec>\n<cspec name=\"G\">\nsub {return 'thisistheGcspec'}\n</cspec>\n</log4perl:layout>\n</log4perl:appender>\n<log4perl:appender name=\"DBAppndr2\" class=\"Log::Log4perl::Appender::DBI\">\n<param name=\"warpmessage\" value=\"0\"/>\n<param name=\"datasource\" value=\"DBI:CSV:fdir=t/tmp\"/>\n<param name=\"bufferSize\" value=\"2\"/>\n<param name=\"password\" value=\"sub { $ENV{PWD} }\"/>\n<param name=\"username\" value=\"bobjones\"/>\n<param-text name=\"sql\">\nINSERT INTO log4perltest\n(loglevel, message, shortcaller, thingid,\ncategory, pkg, runtime1, runtime2)\nVALUES\n(?,?,?,?,?,?,?,?)\n</param-text>\n<param-nested name=\"params\">\n<param name=\"1\" value=\"%p\"/>\n<param name=\"3\" value=\"%5.5l\"/>\n<param name=\"5\" value=\"%c\"/>\n<param name=\"6\" value=\"%C\"/>\n</param-nested>\n<layout class=\"Log::Log4perl::Layout::NoopLayout\"/>\n</log4perl:appender>\n<category name=\"animal.dog\">\n<priority value=\"info\"/>\n<appender-ref ref=\"jabbender\"/>\n<appender-ref ref=\"DBAppndr2\"/>\n</category>\n<category name=\"plant\">\n<priority value=\"debug\"/>\n<appender-ref ref=\"DBAppndr2\"/>\n</category>\n<PatternLayout>\n<cspec name=\"U\"><![CDATA[\nsub {\nreturn \"UID $< GID $(\";\n}\n]]></cspec>\n</PatternLayout>\n</log4perl:configuration>",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 115,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "WHY",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "HOW",
                "lines": 111,
                "subsections": []
            },
            {
                "name": "WHY NAMESPACES",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "VARIABLE SUBSTITUTION",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "REQUIRES",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "CAVEATS",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "CHANGES",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 13,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 17,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Log::Log4perl::Config::DOMConfigurator - reads xml config files\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "--------------------------\n--using the log4j DTD--\n--------------------------\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4j:configuration SYSTEM \"log4j.dtd\">\n\n<log4j:configuration xmlns:log4j=\"http://jakarta.apache.org/log4j/\">\n\n<appender name=\"FileAppndr1\" class=\"org.apache.log4j.FileAppender\">\n<layout class=\"Log::Log4perl::Layout::PatternLayout\">\n<param name=\"ConversionPattern\"\nvalue=\"%d %4r [%t] %-5p %c %t - %m%n\"/>\n</layout>\n<param name=\"File\" value=\"t/tmp/DOMtest\"/>\n<param name=\"Append\" value=\"false\"/>\n</appender>\n\n<category name=\"a.b.c.d\" additivity=\"false\">\n<level value=\"warn\"/>  <!-- note lowercase! -->\n<appender-ref ref=\"FileAppndr1\"/>\n</category>\n\n<root>\n<priority value=\"warn\"/>\n<appender-ref ref=\"FileAppndr1\"/>\n</root>\n\n</log4j:configuration>\n\n\n\n--------------------------\n--using the log4perl DTD--\n--------------------------\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4perl:configuration SYSTEM \"log4perl.dtd\">\n\n<log4perl:configuration xmlns:log4perl=\"http://log4perl.sourceforge.net/\"\nthreshold=\"debug\" oneMessagePerAppender=\"true\">\n\n<log4perl:appender name=\"jabbender\" class=\"Log::Dispatch::Jabber\">\n\n<param-nested name=\"login\">\n<param name=\"hostname\" value=\"a.jabber.server\"/>\n<param name=\"password\" value=\"12345\"/>\n<param name=\"port\"     value=\"5222\"/>\n<param name=\"resource\" value=\"logger\"/>\n<param name=\"username\" value=\"bobjones\"/>\n</param-nested>\n\n<param name=\"to\" value=\"bob@a.jabber.server\"/>\n\n<param-text name=\"to\">\nmary@another.jabber.server\n</param-text>\n\n<log4perl:layout class=\"org.apache.log4j.PatternLayout\">\n<param name=\"ConversionPattern\" value = \"%K xx %G %U\"/>\n<cspec name=\"K\">\nsub { return sprintf \"%1x\", $$}\n</cspec>\n<cspec name=\"G\">\nsub {return 'thisistheGcspec'}\n</cspec>\n</log4perl:layout>\n</log4perl:appender>\n\n<log4perl:appender name=\"DBAppndr2\" class=\"Log::Log4perl::Appender::DBI\">\n<param name=\"warpmessage\" value=\"0\"/>\n<param name=\"datasource\" value=\"DBI:CSV:fdir=t/tmp\"/>\n<param name=\"bufferSize\" value=\"2\"/>\n<param name=\"password\" value=\"sub { $ENV{PWD} }\"/>\n<param name=\"username\" value=\"bobjones\"/>\n\n<param-text name=\"sql\">\nINSERT INTO log4perltest\n(loglevel, message, shortcaller, thingid,\ncategory, pkg, runtime1, runtime2)\nVALUES\n(?,?,?,?,?,?,?,?)\n</param-text>\n\n<param-nested name=\"params\">\n<param name=\"1\" value=\"%p\"/>\n<param name=\"3\" value=\"%5.5l\"/>\n<param name=\"5\" value=\"%c\"/>\n<param name=\"6\" value=\"%C\"/>\n</param-nested>\n\n<layout class=\"Log::Log4perl::Layout::NoopLayout\"/>\n</log4perl:appender>\n\n<category name=\"animal.dog\">\n<priority value=\"info\"/>\n<appender-ref ref=\"jabbender\"/>\n<appender-ref ref=\"DBAppndr2\"/>\n</category>\n\n<category name=\"plant\">\n<priority value=\"debug\"/>\n<appender-ref ref=\"DBAppndr2\"/>\n</category>\n\n<PatternLayout>\n<cspec name=\"U\"><![CDATA[\nsub {\nreturn \"UID $< GID $(\";\n}\n]]></cspec>\n</PatternLayout>\n\n</log4perl:configuration>\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module implements an XML config, complementing the properties-style config described\nelsewhere.\n",
                "subsections": []
            },
            "WHY": {
                "content": "\"Why would I want my config in XML?\" you ask. Well, there are a couple reasons you might want\nto. Maybe you have a personal preference for XML. Maybe you manage your config with other tools\nthat have an affinity for XML, like XML-aware editors or automated config generators. Or maybe\n(and this is the big one) you don't like having to run your application just to check the syntax\nof your config file.\n\nBy using an XML config and referencing a DTD, you can use a namespace-aware validating parser to\nsee if your XML config at least follows the rules set in the DTD.\n",
                "subsections": []
            },
            "HOW": {
                "content": "To reference a DTD, drop this in after the <?xml...> declaration in your config file:\n\n<!DOCTYPE log4perl:configuration SYSTEM \"log4perl.dtd\">\n\nThat tells the parser to validate your config against the DTD in \"log4perl.dtd\", which is\navailable in the xml/ directory of the log4perl distribution. Note that you'll also need to grab\nthe log4j-1.2.dtd from there as well, since the it's included by log4perl.dtd.\n\nNamespace-aware validating parsers are not the norm in Perl. But the Xerces project\n(http://xml.apache.org/xerces-c/index.html --lots of binaries available, even rpm's) does\nprovide just such a parser that you can use like this:\n\nStdInParse -ns -v < my-log4perl-config.xml\n\nThis module itself does not use a validating parser, the obvious one XML::DOM::ValParser doesn't\nseem to handle namespaces.\n\nWHY TWO DTDs\nThe log4j DTD is from the log4j project, they designed it to handle their needs. log4perl has\nadded some extensions to the original log4j functionality which needed some extensions to the\nlog4j DTD. If you aren't using these features then you can validate your config against the\nlog4j dtd and know that you're using unadulterated log4j config tags.\n\nThe features added by the log4perl dtd are:\n\n1 oneMessagePerAppender global setting\nlog4perl.oneMessagePerAppender=1\n\n2 globally defined user conversion specifiers\nlog4perl.PatternLayout.cspec.G=sub { return \"UID $< GID $(\"; }\n\n3 appender-local custom conversion specifiers\nlog4j.appender.appndr1.layout.cspec.K = sub {return sprintf \"%1x\", $$ }\n\n4 nested options\nlog4j.appender.jabbender          = Log::Dispatch::Jabber\n#(note how these are nested under 'login')\nlog4j.appender.jabbender.login.hostname = a.jabber.server\nlog4j.appender.jabbender.login.port     = 5222\nlog4j.appender.jabbender.login.username = bobjones\n\n5 the log4perl-specific filters, see Log::Log4perl::Filter, lots of examples in\nt/044XML-Filter.t, here's a short one:\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE log4perl:configuration SYSTEM \"log4perl.dtd\">\n\n<log4perl:configuration xmlns:log4perl=\"http://log4perl.sourceforge.net/\">\n\n<appender name=\"A1\" class=\"Log::Log4perl::Appender::TestBuffer\">\n<layout class=\"Log::Log4perl::Layout::SimpleLayout\"/>\n<filter class=\"Log::Log4perl::Filter::Boolean\">\n<param name=\"logic\" value=\"!Match3 &amp;&amp; (Match1 || Match2)\"/>\n</filter>\n</appender>\n\n<appender name=\"A2\" class=\"Log::Log4perl::Appender::TestBuffer\">\n<layout class=\"Log::Log4perl::Layout::SimpleLayout\"/>\n<filter-ref id=\"Match1\"/>\n</appender>\n\n<log4perl:filter name=\"Match1\" value=\"sub { /let this through/ }\" />\n\n<log4perl:filter name=\"Match2\">\nsub {\n/and that, too/\n}\n</log4perl:filter>\n\n<log4perl:filter name=\"Match3\" class=\"Log::Log4perl::Filter::StringMatch\">\n<param name=\"StringToMatch\" value=\"suppress\"/>\n<param name=\"AcceptOnMatch\" value=\"true\"/>\n</log4perl:filter>\n\n<log4perl:filter name=\"MyBoolean\" class=\"Log::Log4perl::Filter::Boolean\">\n<param name=\"logic\" value=\"!Match3 &amp;&amp; (Match1 || Match2)\"/>\n</log4perl:filter>\n\n\n<root>\n<priority value=\"info\"/>\n<appender-ref ref=\"A1\"/>\n</root>\n\n</log4perl:configuration>\n\nSo we needed to extend the log4j dtd to cover these additions. Now I could have just taken a\n'steal this code' approach and mixed parts of the log4j dtd into a log4perl dtd, but that would\nbe cut-n-paste programming. So I've used namespaces and\n\n*   replaced three elements:\n\n<log4perl:configuration>\nhandles #1) and accepts <PatternLayout>\n\n<log4perl:appender>\naccepts <param-nested> and <param-text>\n\n<log4perl:layout>\naccepts custom cspecs for #3)\n\n*   added a <param-nested> element (complementing the <param> element) to handle #4)\n\n*   added a root <PatternLayout> element to handle #2)\n\n*   added <param-text> which lets you put things like perl code into escaped CDATA between the\ntags, so you don't have to worry about escaping characters and quotes\n\n*   added <cspec>\n\nSee the examples up in the \"SYNOPSIS\" for how all that gets used.\n",
                "subsections": []
            },
            "WHY NAMESPACES": {
                "content": "I liked the idea of using the log4j DTD *in situ*, so I used namespaces to extend it. If you\nreally don't like having to type <log4perl:appender> instead of just <appender>, you can make\nyour own DTD combining the two DTDs and getting rid of the namespace prefixes. Then you can\nvalidate against that, and log4perl should accept it just fine.\n",
                "subsections": []
            },
            "VARIABLE SUBSTITUTION": {
                "content": "This supports variable substitution like \"${foobar}\" in text and in attribute values except for\nappender-ref. If an environment variable is defined for that name, its value is substituted. So\nyou can do stuff like\n\n<param name=\"${hostname}\" value=\"${hostnameval}.foo.com\"/>\n<param-text name=\"to\">${currentsysadmin}@foo.com</param-text>\n",
                "subsections": []
            },
            "REQUIRES": {
                "content": "To use this module you need XML::DOM installed.\n\nTo use the log4perl.dtd, you'll have to reference it in your XML config, and you'll also need to\nnote that log4perl.dtd references the log4j dtd as \"log4j-1.2.dtd\", so your validator needs to\nbe able to find that file as well. If you don't like having to schlep two files around, feel\nfree to dump the contents of \"log4j-1.2.dtd\" into your \"log4perl.dtd\" file.\n",
                "subsections": []
            },
            "CAVEATS": {
                "content": "You can't mix a multiple param-nesteds with the same name, I'm going to leave that for now,\nthere's presently no need for a list of structs in the config.\n",
                "subsections": []
            },
            "CHANGES": {
                "content": "0.03 2/26/2003 Added support for log4perl extensions to the log4j dtd\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "t/038XML-DOM1.t, t/039XML-DOM2.t for examples\n\nxml/log4perl.dtd, xml/log4j-1.2.dtd\n\nLog::Log4perl::Config\n\nLog::Log4perl::Config::PropertyConfigurator\n\nLog::Log4perl::Config::LDAPConfigurator (coming soon!)\n\nThe code is brazenly modeled on log4j's DOMConfigurator class, (by Christopher Taylor, Ceki\nGülcü, and Anders Kristensen) and any perceived similarity is not coincidental.\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess <cpan@goess.org>.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Please contribute patches to the project on Github:\n\nhttp://github.com/mschilli/log4perl\n\nSend bug reports or requests for enhancements to the authors via our\n\nMAILING LIST (questions, bug reports, suggestions/patches): log4perl-devel@lists.sourceforge.net\n\nAuthors (please contact them via the list above, not directly): Mike Schilli\n<m@perlmeister.com>, Kevin Goess <cpan@goess.org>\n\nContributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp,\nHutton Davidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon,\nCarl Franks, Dennis Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David Hull,\nRobert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, Brett Rann, Peter Rabbitson, Erik\nSelberg, Aaron Straup Cope, Lars Thegler, David Viner, Mac Yang.\n",
                "subsections": []
            }
        }
    }
}