1Parse::DebControl(3)  User Contributed Perl Documentation Parse::DebControl(3)
2
3
4

NAME

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

SYNOPSIS

9               use Parse::DebControl
10
11               $parser = new Parse::DebControl;
12
13               $data = $parser->parse_mem($control_data, $options);
14               $data = $parser->parse_file('./debian/control', $options);
15               $data = $parser->parse_web($url, $options);
16
17               $writer = new Parse::DebControl;
18
19               $string = $writer->write_mem($singlestanza);
20               $string = $writer->write_mem([$stanza1, $stanza2]);
21
22               $writer->write_file($filename, $singlestanza, $options);
23               $writer->write_file($filename, [$stanza1, $stanza2], $options);
24
25               $writer->write_file($handle, $singlestanza, $options);
26               $writer->write_file($handle, [$stanza1, $stanza2], $options);
27
28               $parser->DEBUG();
29

DESCRIPTION

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
36               For basic format information see:
37               http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax
38
39               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
44   Class Methods
45       •   "new()"
46
47       •   "new($debug)"
48
49           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
53       •   "parse_file($control_filename,$options)"
54
55           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
59           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
66           The options hashref can take parameters as follows. Setting the
67           string to true enables the option.
68
69                   useTieIxHash - Instead of an array of regular hashrefs, uses Tie::IxHash-
70                           based hashrefs
71
72                   discardCase  - Remove all case items from keys (not values)
73
74                   stripComments - Remove all commented lines in standard #comment format.
75                           Literal #'s are represented by ##. For instance
76
77                           Hello there #this is a comment
78                           Hello there, I like ##CCCCCC as a grey.
79
80                           The first is a comment, the second is a literal "#".
81
82                   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
86                   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
92       •   "parse_mem($control_data, $options)"
93
94           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
98       •   "parse_web($url, $options)"
99
100           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
104       •   "write_file($filename, $data, $options)"
105
106       •   "write_file($handle, $data)"
107
108       •   "write_file($filename, [$data1, $data2, $data3], $options)"
109
110       •   "write_file($handle, [$data, $data2, $data3])"
111
112           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
119           The $options hashref can contain one of the following two items:
120
121                   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
126           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
130           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
136           This function returns the number of bytes written to the file,
137           undef otherwise.
138
139       •   "write_mem($data)"
140
141       •   "write_mem([$data1,$data2,$data3])";
142
143           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
147       •   "DEBUG()"
148
149           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

CHANGES

155       Version 2.005 - January 13th, 2004
156
157       •   More generic test suite fix for earlier versions of Test::More
158
159       •   Updated copyright statement
160
161       Version 2.004 - January 12th, 2004
162
163       •   More documentation formatting and typo fixes
164
165       •   CHANGES file now generated automatically
166
167       •   Fixes for potential test suite failure in Pod::Coverage run
168
169       •   Adds the "addNewline" option to write_file to solve the streaming
170           stanza problem.
171
172       •   Adds tests for the addNewline option
173
174       Version 2.003 - January 6th, 2004
175
176       •   Added optional Test::Pod test
177
178       •   Skips potential Win32 test failure in the module where it wants to
179           write to /tmp.
180
181       •   Added optional Pod::Coverage test
182
183       Version 2.002 - October 7th, 2003
184
185       •   No code changes. Fixes to test suite
186
187       Version 2.001 - September 11th, 2003
188
189       •   Cleaned up more POD errors
190
191       •   Added tests for file writing
192
193       •   Fixed bug where write_file ignored the gzip parameter
194
195       Version 2.0 - September 5th, 2003
196
197       •   Version increase.
198
199       •   Added gzip support (with the tryGzip option), so that compresses
200           control files can be parsed on the fly
201
202       •   Added gzip support for writing of control files
203
204       •   Added parse_web to snag files right off the web. Useful for things
205           such as apt's Sources.gz and Packages.gz
206
207       Version 1.10b - September 2nd, 2003
208
209       •   Documentation fix for ## vs # in stripComments
210
211       Version 1.10 - September 2nd, 2003
212
213       •   Documentation fixes, as pointed out by pudge
214
215       •   Adds a feature to stripComments where ## will get interpolated as a
216           literal pound sign, as suggested by pudge.
217
218       Version 1.9 - July 24th, 2003
219
220       •   Fix for warning for edge case (uninitialized value in chomp)
221
222       •   Tests for CRLF
223
224       Version 1.8 - July 11th, 2003
225
226       •   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
230       Version 1.7 - June 25th, 2003
231
232       •   POD documentation error noticed again by Frank Lichtenheld
233
234       •   Also by Frank, applied a patch to add a "verbMultiLine" option so
235           that we can hand multiline fields back unparsed.
236
237       •   Slightly expanded test suite to cover new features
238
239       Version 1.6.1 - June 9th, 2003
240
241       •   POD cleanups noticed by Frank Lichtenheld. Thank you, Frank.
242
243       Version 1.6 - June 2nd, 2003
244
245       •   Cleaned up some warnings when you pass in empty hashrefs or
246           arrayrefs
247
248       •   Added stripComments setting
249
250       •   Cleaned up POD errors
251
252       Version 1.5 - May 8th, 2003
253
254       •   Added a line to quash errors with undef hashkeys and writing
255
256       •   Fixed the Makefile.PL to straighten up DebControl.pm being in the
257           wrong dir
258
259       Version 1.4 - April 30th, 2003
260
261       •   Removed exports as they were unnecessary. Many thanks to pudge, who
262           pointed this out.
263
264       Version 1.3 - April 28th, 2003
265
266       •   Fixed a bug where writing blank stanzas would throw a warning.  Fix
267           found and supplied by Nate Oostendorp.
268
269       Version 1.2b - April 25th, 2003
270
271       Fixed:
272
273       •   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
276       Version 1.2 - April 24th, 2003
277
278       Fixed:
279
280       •   A bug in IxHash support where multiple stanzas might be out of
281           order
282
283       Version 1.1 - April 23rd, 2003
284
285       Added:
286
287       •   Writing support
288
289       •   Tie::IxHash support
290
291       •   Case insensitive reading support
292
293       Version 1.0 - April 23rd, 2003
294
295       •   This is the initial public release for CPAN, so everything is new.
296

BUGS

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
302       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

TODO

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.
315
316
317
318perl v5.32.1                      2021-01-27              Parse::DebControl(3)
Impressum