NAME

Parse::DebControl - Easy OO parsing of debian control-like files

SYNOPSIS

use Parse::DebControl

$parser = new Parse::DebControl;

$data = $parser->parse_mem($control_data, %options);
$data = $parser->parse_file('./debian/control', %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();

DESCRIPTION

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.

Class Methods

• new()

• new($debug)

  Returns a new Parse::DebControl object. If a true parameter $debug is passed in, it turns on debugging, similar to a call to DEBUG() (see below);

• parse_file($control_filename,%options)

  Takes a scalar containing formatted data. Will parse as much as it can, warning (if DEBUGing is turned on) on parsing errors.

  Returns an array of hashes, 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.

  The options hash can take parameters as follows. Setting the string to true enables the option.

  useTieIxHash - Instead of an array of regular hashes, uses Tie::IxHash-
  	based hashes
  discardCase  - Remove all case items from keys (not values)		

• parse_mem($control_data, %options)

  Similar to parse_file, except takes data as a scalar. Returns the same array of hashrefs as parse_file. The options hash is the same as parse_file as well; see 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 hash(ref) or as an arrayref of hash(ref)s. 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 hash can contain one of the following two items:

  appendFile  - (default) Write to the end of the file
  clobberFile - Overwrite the file given.

  Since you determine the mode of your filehandle, passing it an options hash obviously won't do anything; rather, it is ignored.

  This function returns the number of bytes written to the file, undef otherwise.

• write_mem($data)

• write_mem([$data1,$data2,$data3]);

  This function works similarly to the 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()

  Turns on debugging. Calling it with no paramater or a true parameter turns on verbose warn()ings. Calling it with a false parameter turns it off. It is useful for nailing down any format or internal problems.

CHANGES

Version 1.5 - May 8th, 2003

• Added a line to quash errors with undef hashkeys and writing =item * Fixed the Makefile.PL to straighten up DebControl.pm being in the wrong dir

  Version 1.4 - April 30th, 2003

  • Removed exports as they were unnecessary. Many thanks to pudge, who pointed this out.

  Version 1.3 - April 28th, 2003

  • Fixed a bug where writing blank stanzas would throw a warning. Fix found and supplied by Nate Oostendorp.

  Version 1.2b - April 25th, 2003

  Fixed:

  • A bug in the test suite where IxHash was not disabled in 40write.t. Thanks to Jeroen Latour from cpan-testers for the report.

  Version 1.2 - April 24th, 2003

  Fixed:

  • A bug in IxHash support where multiple stanzas might be out of order

  Version 1.1 - April 23rd, 2003

  Added:

  • Writing support

  • Tie::IxHash support

  • Case insensitive reading support

  * Version 1.0 - April 23rd, 2003

  • This is the initial public release for CPAN, so everything is new.

BUGS

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.

TODO

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.

COPYRIGHT

Parse::DebControl is copyright 2003 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.