{
    "content": [
        {
            "type": "text",
            "text": "# Parse::DebControl (perldoc)\n\n## NAME\n\nParse::DebControl - Easy OO parsing of debian control-like files\n\n## SYNOPSIS\n\nuse Parse::DebControl\n$parser = new Parse::DebControl;\n$data = $parser->parsemem($controldata, $options);\n$data = $parser->parsefile('./debian/control', $options);\n$data = $parser->parseweb($url, $options);\n$writer = new Parse::DebControl;\n$string = $writer->writemem($singlestanza);\n$string = $writer->writemem([$stanza1, $stanza2]);\n$writer->writefile($filename, $singlestanza, $options);\n$writer->writefile($filename, [$stanza1, $stanza2], $options);\n$writer->writefile($handle, $singlestanza, $options);\n$writer->writefile($handle, [$stanza1, $stanza2], $options);\n$parser->DEBUG();\n\n## DESCRIPTION\n\nParse::DebControl is an easy OO way to parse debian control files and\nother colon separated key-value pairs. It's specifically designed\nto handle the format used in Debian control files, template files, and\nthe cache files used by dpkg.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **CHANGES**\n- **BUGS**\n- **TODO**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Parse::DebControl",
        "section": "",
        "mode": "perldoc",
        "summary": "Parse::DebControl - Easy OO parsing of debian control-like files",
        "synopsis": "use Parse::DebControl\n$parser = new Parse::DebControl;\n$data = $parser->parsemem($controldata, $options);\n$data = $parser->parsefile('./debian/control', $options);\n$data = $parser->parseweb($url, $options);\n$writer = new Parse::DebControl;\n$string = $writer->writemem($singlestanza);\n$string = $writer->writemem([$stanza1, $stanza2]);\n$writer->writefile($filename, $singlestanza, $options);\n$writer->writefile($filename, [$stanza1, $stanza2], $options);\n$writer->writefile($handle, $singlestanza, $options);\n$writer->writefile($handle, [$stanza1, $stanza2], $options);\n$parser->DEBUG();",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 21,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 13,
                "subsections": [
                    {
                        "name": "Class Methods",
                        "lines": 114
                    }
                ]
            },
            {
                "name": "CHANGES",
                "lines": 136,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "TODO",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Parse::DebControl - Easy OO parsing of debian control-like files\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use Parse::DebControl\n\n$parser = new Parse::DebControl;\n\n$data = $parser->parsemem($controldata, $options);\n$data = $parser->parsefile('./debian/control', $options);\n$data = $parser->parseweb($url, $options);\n\n$writer = new Parse::DebControl;\n\n$string = $writer->writemem($singlestanza);\n$string = $writer->writemem([$stanza1, $stanza2]);\n\n$writer->writefile($filename, $singlestanza, $options);\n$writer->writefile($filename, [$stanza1, $stanza2], $options);\n\n$writer->writefile($handle, $singlestanza, $options);\n$writer->writefile($handle, [$stanza1, $stanza2], $options);\n\n$parser->DEBUG();\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "Parse::DebControl is an easy OO way to parse debian control files and\nother colon separated key-value pairs. It's specifically designed\nto handle the format used in Debian control files, template files, and\nthe cache files used by dpkg.\n\nFor basic format information see:\nhttp://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax\n\nThis module does not actually do any intelligence with the file content\n(because there are a lot of files in this format), but merely handles\nthe format. It can handle simple control files, or files hundreds of lines\nlong efficiently and easily.\n",
                "subsections": [
                    {
                        "name": "Class Methods",
                        "content": "*   \"new()\"\n\n*   \"new(*$debug*)\"\n\nReturns a new Parse::DebControl object. If a true parameter *$debug* is passed in, it turns\non debugging, similar to a call to \"DEBUG()\" (see below);\n\n*   \"parsefile($controlfilename,*$options*)\"\n\nTakes a filename as a scalar and an optional hashref of options (see below). Will parse as\nmuch as it can, warning (if \"DEBUG\"ing is turned on) on parsing errors.\n\nReturns an array of hashrefs, containing the data in the control file, split up by stanza.\nStanzas are deliniated by newlines, and multi-line fields are expressed as such\npost-parsing. Single periods are treated as special extra newline deliniators, per\nconvention. Whitespace is also stripped off of lines as to make it less-easy to make\nmistakes with hand-written conf files).\n\nThe options hashref can take parameters as follows. Setting the string to true enables the\noption.\n\nuseTieIxHash - Instead of an array of regular hashrefs, uses Tie::IxHash-\nbased hashrefs\n\ndiscardCase  - Remove all case items from keys (not values)\n\nstripComments - Remove all commented lines in standard #comment format.\nLiteral #'s are represented by ##. For instance\n\nHello there #this is a comment\nHello there, I like ##CCCCCC as a grey.\n\nThe first is a comment, the second is a literal \"#\".\n\nverbMultiLine - Keep the description AS IS, and no not collapse leading\nspaces or dots as newlines. This also keeps whitespace from being\nstripped off the end of lines.\n\ntryGzip - Attempt to expand the data chunk with gzip first. If the text is\nalready expanded (ie: plain text), parsing will continue normally.\nThis could optionally be turned on for all items in the future, but\nit is off by default so we don't have to scrub over all the text for\nperformance reasons.\n\nsingleBlock - Only parse the first block of data and return it. This is\nuseful when you have possible \"junk\" data after the metadata.\n\nstrict - Tries to parse obeying the strict rules for real debian control files.\nThis will force comment stripping for debian/control (must start line) and for\nother files will check if a field may span multiple lines.\n\nallowUnknownFields - In strict mode, allow unknown fields.\n\ntype - If the strict option is chosen, then this parameter defines what format\nwe have. Available formats is:\n- debian/control\n- DEBIAN/control\n- .dsc\n- .changes\n\n*   \"parsemem($controldata, *$options*)\"\n\nSimilar to \"parsefile\", except takes data as a scalar. Returns the same array of hashrefs\nas \"parsefile\". The options hashref is the same as \"parsefile\" as well; see above.\n\n*   \"parseweb($url, *$options*)\"\n\nSimilar to the other parse* functions, this pulls down a control file from the web and\nattempts to parse it. For options and return values, see \"parsefile\", above\n\n*   \"writefile($filename, $data, *$options*)\"\n\n*   \"writefile($handle, $data)\"\n\n*   \"writefile($filename, [$data1, $data2, $data3], *$options*)\"\n\n*   \"writefile($handle, [$data, $data2, $data3])\"\n\nThis function takes a filename or a handle and writes the data out. The data can be given as\na single hashref or as an arrayref of hashrefs. It will then write it out in a format that\nit can parse. The order is dependent on your hash sorting order. If you care, use\nTie::IxHash. Remember for reading back in, the module doesn't care.\n\nThe *$options* hashref can contain one of the following two items:\n\naddNewline - At the end of the last stanza, add an additional newline.\nappendFile  - (default) Write to the end of the file\nclobberFile - Overwrite the file given.\ngzip - Compress the data with gzip before writing\n\nSince you determine the mode of your filehandle, passing it along with an options hashref\nobviously won't do anything; rather, it is ignored.\n\nThe *addNewline* option solves a situation where if you are writing stanzas to a file in a\nloop (such as logging with this module), then the data will be streamed together, and won't\nparse back in correctly. It is possible that this is the behavior that you want (if you\nwanted to write one key at a time), so it is optional.\n\nThis function returns the number of bytes written to the file, undef otherwise.\n\n*   \"writemem($data)\"\n\n*   \"writemem([$data1,$data2,$data3])\";\n\nThis function works similarly to the \"writefile\" method, except it returns the control\nstructure as a scalar, instead of writing it to a file. There is no *%options* for this file\n(yet);\n\n*   \"DEBUG()\"\n\nTurns on debugging. Calling it with no parameter or a true parameter turns on verbose\n\"warn()\"ings. Calling it with a false parameter turns it off. It is useful for nailing down\nany format or internal problems.\n"
                    }
                ]
            },
            "CHANGES": {
                "content": "Version 2.005 - January 13th, 2004\n\n*   More generic test suite fix for earlier versions of Test::More\n\n*   Updated copyright statement\n\nVersion 2.004 - January 12th, 2004\n\n*   More documentation formatting and typo fixes\n\n*   CHANGES file now generated automatically\n\n*   Fixes for potential test suite failure in Pod::Coverage run\n\n*   Adds the \"addNewline\" option to writefile to solve the streaming stanza problem.\n\n*   Adds tests for the addNewline option\n\nVersion 2.003 - January 6th, 2004\n\n*   Added optional Test::Pod test\n\n*   Skips potential Win32 test failure in the module where it wants to write to /tmp.\n\n*   Added optional Pod::Coverage test\n\nVersion 2.002 - October 7th, 2003\n\n*   No code changes. Fixes to test suite\n\nVersion 2.001 - September 11th, 2003\n\n*   Cleaned up more POD errors\n\n*   Added tests for file writing\n\n*   Fixed bug where writefile ignored the gzip parameter\n\nVersion 2.0 - September 5th, 2003\n\n*   Version increase.\n\n*   Added gzip support (with the tryGzip option), so that compresses control files can be parsed\non the fly\n\n*   Added gzip support for writing of control files\n\n*   Added parseweb to snag files right off the web. Useful for things such as apt's Sources.gz\nand Packages.gz\n\nVersion 1.10b - September 2nd, 2003\n\n*   Documentation fix for ## vs # in stripComments\n\nVersion 1.10 - September 2nd, 2003\n\n*   Documentation fixes, as pointed out by pudge\n\n*   Adds a feature to stripComments where ## will get interpolated as a literal pound sign, as\nsuggested by pudge.\n\nVersion 1.9 - July 24th, 2003\n\n*   Fix for warning for edge case (uninitialized value in chomp)\n\n*   Tests for CRLF\n\nVersion 1.8 - July 11th, 2003\n\n*   By default, we now strip off whitespace unless verbMultiLine is in place. This makes sense\nfor things like conf files where trailing whitespace has no meaning. Thanks to pudge for\nreporting this.\n\nVersion 1.7 - June 25th, 2003\n\n*   POD documentation error noticed again by Frank Lichtenheld\n\n*   Also by Frank, applied a patch to add a \"verbMultiLine\" option so that we can hand multiline\nfields back unparsed.\n\n*   Slightly expanded test suite to cover new features\n\nVersion 1.6.1 - June 9th, 2003\n\n*   POD cleanups noticed by Frank Lichtenheld. Thank you, Frank.\n\nVersion 1.6 - June 2nd, 2003\n\n*   Cleaned up some warnings when you pass in empty hashrefs or arrayrefs\n\n*   Added stripComments setting\n\n*   Cleaned up POD errors\n\nVersion 1.5 - May 8th, 2003\n\n*   Added a line to quash errors with undef hashkeys and writing\n\n*   Fixed the Makefile.PL to straighten up DebControl.pm being in the wrong dir\n\nVersion 1.4 - April 30th, 2003\n\n*   Removed exports as they were unnecessary. Many thanks to pudge, who pointed this out.\n\nVersion 1.3 - April 28th, 2003\n\n*   Fixed a bug where writing blank stanzas would throw a warning. Fix found and supplied by\nNate Oostendorp.\n\nVersion 1.2b - April 25th, 2003\n\nFixed:\n\n*   A bug in the test suite where IxHash was not disabled in 40write.t. Thanks to Jeroen Latour\nfrom cpan-testers for the report.\n\nVersion 1.2 - April 24th, 2003\n\nFixed:\n\n*   A bug in IxHash support where multiple stanzas might be out of order\n\nVersion 1.1 - April 23rd, 2003\n\nAdded:\n\n*   Writing support\n\n*   Tie::IxHash support\n\n*   Case insensitive reading support\n\nVersion 1.0 - April 23rd, 2003\n\n*   This is the initial public release for CPAN, so everything is new.\n",
                "subsections": []
            },
            "BUGS": {
                "content": "The module will let you parse otherwise illegal key-value pairs and pairs with spaces. Badly\nformed stanzas will do things like overwrite duplicate keys, etc. This is your problem.\n\nAs of 1.10, the module uses advanced regexp's to figure out about comments. If the tests fail,\nthen stripComments won't work on your earlier perl version (should be fine on 5.6.0+)\n",
                "subsections": []
            },
            "TODO": {
                "content": "Change the name over to the Debian:: namespace, probably as Debian::ControlFormat. This will\nhappen as soon as the project that uses this module reaches stability, and we can do some minor\ntweaks.\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Parse::DebControl is copyright 2003,2004 Jay Bonci <jaybonci@cpan.org>. This program is free\nsoftware; you can redistribute it and/or modify it under the same terms as Perl itself.\n",
                "subsections": []
            }
        }
    }
}