1Parse::DebControl(3) User Contributed Perl Documentation Parse::DebControl(3)
2
6 Parse::DebControl - Easy OO parsing of debian control-like files
7
9 use Parse::DebControl
10 $parser = new Parse::DebControl;
12 $data = $parser->parse_mem($control_data, $options);
14 $data = $parser->parse_file('./debian/control', $options);
15 $data = $parser->parse_web($url, $options);
16 $writer = new Parse::DebControl;
18 $string = $writer->write_mem($singlestanza);
20 $string = $writer->write_mem([$stanza1, $stanza2]);
21 $writer->write_file($filename, $singlestanza, $options);
23 $writer->write_file($filename, [$stanza1, $stanza2], $options);
24 $writer->write_file($handle, $singlestanza, $options);
26 $writer->write_file($handle, [$stanza1, $stanza2], $options);
27 $parser->DEBUG();
29
31 Parse::DebControl is an easy OO way to parse debian control files and
32 other colon separated key-value pairs. It's specifically designed
33 to handle the format used in Debian control files, template files, and
34 the cache files used by dpkg.
35 For basic format information see:
37 http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax
38 This module does not actually do any intelligence with the file content
40 (because there are a lot of files in this format), but merely handles
41 the format. It can handle simple control files, or files hundreds of lines
42 long efficiently and easily.
43 Class Methods
45 • "new()"
46 • "new($debug)"
48 Returns a new Parse::DebControl object. If a true parameter $debug
50 is passed in, it turns on debugging, similar to a call to "DEBUG()"
51 (see below);
52 • "parse_file($control_filename,$options)"
54 Takes a filename as a scalar and an optional hashref of options
56 (see below). Will parse as much as it can, warning (if "DEBUG"ing
57 is turned on) on parsing errors.
58 Returns an array of hashrefs, containing the data in the control
60 file, split up by stanza. Stanzas are deliniated by newlines, and
61 multi-line fields are expressed as such post-parsing. Single
62 periods are treated as special extra newline deliniators, per
63 convention. Whitespace is also stripped off of lines as to make it
64 less-easy to make mistakes with hand-written conf files).
65 The options hashref can take parameters as follows. Setting the
67 string to true enables the option.
68 useTieIxHash - Instead of an array of regular hashrefs, uses Tie::IxHash-
70 based hashrefs
71 discardCase - Remove all case items from keys (not values)
73 stripComments - Remove all commented lines in standard #comment format.
75 Literal #'s are represented by ##. For instance
76 Hello there #this is a comment
78 Hello there, I like ##CCCCCC as a grey.
79 The first is a comment, the second is a literal "#".
81 verbMultiLine - Keep the description AS IS, and no not collapse leading
83 spaces or dots as newlines. This also keeps whitespace from being
84 stripped off the end of lines.
85 tryGzip - Attempt to expand the data chunk with gzip first. If the text is
87 already expanded (ie: plain text), parsing will continue normally.
88 This could optionally be turned on for all items in the future, but
89 it is off by default so we don't have to scrub over all the text for
90 performance reasons.
91 • "parse_mem($control_data, $options)"
93 Similar to "parse_file", except takes data as a scalar. Returns the
95 same array of hashrefs as "parse_file". The options hashref is the
96 same as "parse_file" as well; see above.
97 • "parse_web($url, $options)"
99 Similar to the other parse_* functions, this pulls down a control
101 file from the web and attempts to parse it. For options and return
102 values, see "parse_file", above
103 • "write_file($filename, $data, $options)"
105 • "write_file($handle, $data)"
107 • "write_file($filename, [$data1, $data2, $data3], $options)"
109 • "write_file($handle, [$data, $data2, $data3])"
111 This function takes a filename or a handle and writes the data out.
113 The data can be given as a single hashref or as an arrayref of
114 hashrefs. It will then write it out in a format that it can parse.
115 The order is dependant on your hash sorting order. If you care, use
116 Tie::IxHash. Remember for reading back in, the module doesn't
117 care.
118 The $options hashref can contain one of the following two items:
120 addNewline - At the end of the last stanza, add an additional newline.
122 appendFile - (default) Write to the end of the file
123 clobberFile - Overwrite the file given.
124 gzip - Compress the data with gzip before writing
125 Since you determine the mode of your filehandle, passing it along
127 with an options hashref obviously won't do anything; rather, it is
128 ignored.
129 The addNewline option solves a situation where if you are writing
131 stanzas to a file in a loop (such as logging with this module),
132 then the data will be streamed together, and won't parse back in
133 correctly. It is possible that this is the behavior that you want
134 (if you wanted to write one key at a time), so it is optional.
135 This function returns the number of bytes written to the file,
137 undef otherwise.
138 • "write_mem($data)"
140 • "write_mem([$data1,$data2,$data3])";
142 This function works similarly to the "write_file" method, except it
144 returns the control structure as a scalar, instead of writing it to
145 a file. There is no %options for this file (yet);
146 • "DEBUG()"
148 Turns on debugging. Calling it with no paramater or a true
150 parameter turns on verbose "warn()"ings. Calling it with a false
151 parameter turns it off. It is useful for nailing down any format
152 or internal problems.
153
155 Version 2.005 - January 13th, 2004
156 • More generic test suite fix for earlier versions of Test::More
158 • Updated copyright statement
160 Version 2.004 - January 12th, 2004
162 • More documentation formatting and typo fixes
164 • CHANGES file now generated automatically
166 • Fixes for potential test suite failure in Pod::Coverage run
168 • Adds the "addNewline" option to write_file to solve the streaming
170 stanza problem.
171 • Adds tests for the addNewline option
173 Version 2.003 - January 6th, 2004
175 • Added optional Test::Pod test
177 • Skips potential Win32 test failure in the module where it wants to
179 write to /tmp.
180 • Added optional Pod::Coverage test
182 Version 2.002 - October 7th, 2003
184 • No code changes. Fixes to test suite
186 Version 2.001 - September 11th, 2003
188 • Cleaned up more POD errors
190 • Added tests for file writing
192 • Fixed bug where write_file ignored the gzip parameter
194 Version 2.0 - September 5th, 2003
196 • Version increase.
198 • Added gzip support (with the tryGzip option), so that compresses
200 control files can be parsed on the fly
201 • Added gzip support for writing of control files
203 • Added parse_web to snag files right off the web. Useful for things
205 such as apt's Sources.gz and Packages.gz
206 Version 1.10b - September 2nd, 2003
208 • Documentation fix for ## vs # in stripComments
210 Version 1.10 - September 2nd, 2003
212 • Documentation fixes, as pointed out by pudge
214 • Adds a feature to stripComments where ## will get interpolated as a
216 literal pound sign, as suggested by pudge.
217 Version 1.9 - July 24th, 2003
219 • Fix for warning for edge case (uninitialized value in chomp)
221 • Tests for CRLF
223 Version 1.8 - July 11th, 2003
225 • By default, we now strip off whitespace unless verbMultiLine is in
227 place. This makes sense for things like conf files where trailing
228 whitespace has no meaning. Thanks to pudge for reporting this.
229 Version 1.7 - June 25th, 2003
231 • POD documentation error noticed again by Frank Lichtenheld
233 • Also by Frank, applied a patch to add a "verbMultiLine" option so
235 that we can hand multiline fields back unparsed.
236 • Slightly expanded test suite to cover new features
238 Version 1.6.1 - June 9th, 2003
240 • POD cleanups noticed by Frank Lichtenheld. Thank you, Frank.
242 Version 1.6 - June 2nd, 2003
244 • Cleaned up some warnings when you pass in empty hashrefs or
246 arrayrefs
247 • Added stripComments setting
249 • Cleaned up POD errors
251 Version 1.5 - May 8th, 2003
253 • Added a line to quash errors with undef hashkeys and writing
255 • Fixed the Makefile.PL to straighten up DebControl.pm being in the
257 wrong dir
258 Version 1.4 - April 30th, 2003
260 • Removed exports as they were unnecessary. Many thanks to pudge, who
262 pointed this out.
263 Version 1.3 - April 28th, 2003
265 • Fixed a bug where writing blank stanzas would throw a warning. Fix
267 found and supplied by Nate Oostendorp.
268 Version 1.2b - April 25th, 2003
270 Fixed:
272 • A bug in the test suite where IxHash was not disabled in 40write.t.
274 Thanks to Jeroen Latour from cpan-testers for the report.
275 Version 1.2 - April 24th, 2003
277 Fixed:
279 • A bug in IxHash support where multiple stanzas might be out of
281 order
282 Version 1.1 - April 23rd, 2003
284 Added:
286 • Writing support
288 • Tie::IxHash support
290 • Case insensitive reading support
292 Version 1.0 - April 23rd, 2003
294 • This is the initial public release for CPAN, so everything is new.
296
298 The module will let you parse otherwise illegal key-value pairs and
299 pairs with spaces. Badly formed stanzas will do things like overwrite
300 duplicate keys, etc. This is your problem.
301 As of 1.10, the module uses advanced regexp's to figure out about
303 comments. If the tests fail, then stripComments won't work on your
304 earlier perl version (should be fine on 5.6.0+)
305
307 Change the name over to the Debian:: namespace, probably as
308 Debian::ControlFormat. This will happen as soon as the project that
309 uses this module reaches stability, and we can do some minor tweaks.
310
312 Parse::DebControl is copyright 2003,2004 Jay Bonci <jaybonci@cpan.org>.
313 This program is free software; you can redistribute it and/or modify it
314 under the same terms as Perl itself.
315perl v5.36.0 2022-07-22 Parse::DebControl(3)