Parse::DebControl - Easy OO parsing of debian control-like files
use Parse::DebControl
$parser = new Parse::DebControl;
$data = $parser->parse_mem($control_data, $options);
$data = $parser->parse_file('./debian/control', $options);
$data = $parser->parse_web($url, $options);
$writer = new Parse::DebControl;
$string = $writer->write_mem($singlestanza);
$string = $writer->write_mem([$stanza1, $stanza2]);
$writer->write_file($filename, $singlestanza, $options);
$writer->write_file($filename, [$stanza1, $stanza2], $options);
$writer->write_file($handle, $singlestanza, $options);
$writer->write_file($handle, [$stanza1, $stanza2], $options);
$parser->DEBUG();
Parse::DebControl is an easy OO way to parse debian control files and other colon separated key-value pairs. It's specifically designed to handle the format used in Debian control files, template files, and the cache files used by dpkg. For basic format information see: http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax This module does not actually do any intelligence with the file content (because there are a lot of files in this format), but merely handles the format. It can handle simple control files, or files hundreds of lines long efficiently and easily.
new()
new($debug)
DEBUG() (see below);
parse_file($control_filename,$options)
Takes a filename as a scalar and an optional hashref of options (see below).
Will parse as much as it can, warning (if DEBUGing is turned on) on
parsing errors.
Returns an array of hashrefs, containing the data in the control file, split up by stanza. Stanzas are deliniated by newlines, and multi-line fields are expressed as such post-parsing. Single periods are treated as special extra newline deliniators, per convention. Whitespace is also stripped off of lines as to make it less-easy to make mistakes with hand-written conf files).
The options hashref can take parameters as follows. Setting the string to true enables the option.
useTieIxHash - Instead of an array of regular hashrefs, uses Tie::IxHash- based hashrefs discardCase - Remove all case items from keys (not values) stripComments - Remove all commented lines in standard #comment format. Literal #'s are represented by ##. For instance Hello there #this is a comment Hello there, I like ##CCCCCC as a grey. The first is a comment, the second is a literal "#". verbMultiLine - Keep the description AS IS, and no not collapse leading spaces or dots as newlines. This also keeps whitespace from being stripped off the end of lines. tryGzip - Attempt to expand the data chunk with gzip first. If the text is already expanded (ie: plain text), parsing will continue normally. This could optionally be turned on for all items in the future, but it is off by default so we don't have to scrub over all the text for performance reasons.
parse_mem($control_data, $options)
parse_file, except takes data as a scalar. Returns the same
array of hashrefs as parse_file. The options hashref is the same as
parse_file as well; see above.
parse_web($url, $options)
parse_file,
above
write_file($filename, $data, $options)
write_file($handle, $data)
write_file($filename, [$data1, $data2, $data3], $options)
write_file($handle, [$data, $data2, $data3])
This function takes a filename or a handle and writes the data out. The data can be given as a single hashref or as an arrayref of hashrefs. It will then write it out in a format that it can parse. The order is dependant on your hash sorting order. If you care, use Tie::IxHash. Remember for reading back in, the module doesn't care.
The $options hashref can contain one of the following two items:
addNewline - At the end of the last stanza, add an additional newline. appendFile - (default) Write to the end of the file clobberFile - Overwrite the file given. gzip - Compress the data with gzip before writing
Since you determine the mode of your filehandle, passing it along with an options hashref obviously won't do anything; rather, it is ignored.
The addNewline option solves a situation where if you are writing stanzas to a file in a loop (such as logging with this module), then the data will be streamed together, and won't parse back in correctly. It is possible that this is the behavior that you want (if you wanted to write one key at a time), so it is optional.
This function returns the number of bytes written to the file, undef otherwise.
write_mem($data)
write_mem([$data1,$data2,$data3]);
write_file method, except it returns
the control structure as a scalar, instead of writing it to a file. There
is no %options for this file (yet);
DEBUG()
warn()ings. Calling it with a false parameter turns it off.
It is useful for nailing down any format or internal problems.
Version 2.005 - January 13th, 2004
Version 2.004 - January 12th, 2004
Version 2.003 - January 6th, 2004
Version 2.002 - October 7th, 2003
Version 2.001 - September 11th, 2003
Version 2.0 - September 5th, 2003
Version 1.10b - September 2nd, 2003
Version 1.10 - September 2nd, 2003
Version 1.9 - July 24th, 2003
Version 1.8 - July 11th, 2003
Version 1.7 - June 25th, 2003
Version 1.6.1 - June 9th, 2003
Version 1.6 - June 2nd, 2003
Version 1.5 - May 8th, 2003
Version 1.4 - April 30th, 2003
Version 1.3 - April 28th, 2003
Version 1.2b - April 25th, 2003
Fixed:
Version 1.2 - April 24th, 2003
Fixed:
Version 1.1 - April 23rd, 2003
Added:
Version 1.0 - April 23rd, 2003
The module will let you parse otherwise illegal key-value pairs and pairs with spaces. Badly formed stanzas will do things like overwrite duplicate keys, etc. This is your problem.
As of 1.10, the module uses advanced regexp's to figure out about comments. If the tests fail, then stripComments won't work on your earlier perl version (should be fine on 5.6.0+)
Change the name over to the Debian:: namespace, probably as Debian::ControlFormat. This will happen as soon as the project that uses this module reaches stability, and we can do some minor tweaks.
Parse::DebControl is copyright 2003,2004 Jay Bonci <jaybonci@cpan.org>. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.