1Parse::DebControl(3) User Contributed Perl Documentation Parse::DebControl(3)
2
3
4
6 Parse::DebControl - Easy OO parsing of debian control-like files
7
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
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
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
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
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.28.0 2004-01-13 Parse::DebControl(3)