1Dpkg::Changelog(3) libdpkg-perl Dpkg::Changelog(3)
2
6 Dpkg::Changelog - base class to implement a changelog parser
7
9 Dpkg::Changelog is a class representing a changelog file as an array of
10 changelog entries (Dpkg::Changelog::Entry). By deriving this object
11 and implementing its parse method, you add the ability to fill this
12 object with changelog entries.
13
15 $c = Dpkg::Changelog->new(%options)
16 Creates a new changelog object.
17 $c->load($filename)
19 Parse $filename as a changelog.
20 $c->set_options(%opts)
22 Change the value of some options. "verbose" (defaults to 1) defines
23 whether parse errors are displayed as warnings by default.
24 "reportfile" is a string to use instead of the name of the file
25 parsed, in particular in error messages. "range" defines the range
26 of entries that we want to parse, the parser will stop as soon as
27 it has parsed enough data to satisfy $c->get_range($opts{range}).
28 $c->reset_parse_errors()
30 Can be used to delete all information about errors occurred during
31 previous parse runs.
32 $c->parse_error($file, $line_nr, $error, [$line])
34 Record a new parse error in $file at line $line_nr. The error
35 message is specified with $error and a copy of the line can be
36 recorded in $line.
37 $c->get_parse_errors()
39 Returns all error messages from the last parse run. If called in
40 scalar context returns a human readable string representation. If
41 called in list context returns an array of arrays. Each of these
42 arrays contains
43 1. a string describing the origin of the data (a filename
45 usually). If the reportfile configuration option was given, its
46 value will be used instead.
47 2. the line number where the error occurred
49 3. an error description
51 4. the original line
53 $c->set_unparsed_tail($tail)
55 Add a string representing unparsed lines after the changelog
56 entries. Use undef as $tail to remove the unparsed lines currently
57 set.
58 $c->get_unparsed_tail()
60 Return a string representing the unparsed lines after the changelog
61 entries. Returns undef if there's no such thing.
62 @{$c}
64 Returns all the Dpkg::Changelog::Entry objects contained in this
65 changelog in the order in which they have been parsed.
66 $c->get_range($range)
68 Returns an array (if called in list context) or a reference to an
69 array of Dpkg::Changelog::Entry objects which each represent one
70 entry of the changelog. $range is a hash reference describing the
71 range of entries to return. See section "RANGE SELECTION".
72 $c->abort_early()
74 Returns true if enough data have been parsed to be able to return
75 all entries selected by the range set at creation (or with
76 set_options).
77 $c->save($filename)
79 Save the changelog in the given file.
80 $c->output()
82 "$c"
83 Returns a string representation of the changelog (it's a
84 concatenation of the string representation of the individual
85 changelog entries).
86 $c->output($fh)
88 Output the changelog to the given filehandle.
89 $control = $c->format_range($format, $range)
91 Formats the changelog into Dpkg::Control::Changelog objects
92 representing the entries selected by the optional range specifier
93 (see "RANGE SELECTION" for details). In scalar context returns a
94 Dpkg::Index object containing the selected entries, in list context
95 returns an array of Dpkg::Control::Changelog objects.
96 With format dpkg the returned Dpkg::Control::Changelog object is
98 coalesced from the entries in the changelog that are part of the
99 range requested, with the fields described below, but considering
100 that "selected entry" means the first entry of the selected range.
101 With format rfc822 each returned Dpkg::Control::Changelog objects
103 represents one entry in the changelog that is part of the range
104 requested, with the fields described below, but considering that
105 "selected entry" means for each entry.
106 The different formats return undef if no entries are matched. The
108 following fields are contained in the object(s) returned:
109 Source
111 package name (selected entry)
112 Version
114 packages' version (selected entry)
115 Distribution
117 target distribution (selected entry)
118 Urgency
120 urgency (highest of all entries in range)
121 Maintainer
123 person that created the (selected) entry
124 Date
126 date of the (selected) entry
127 Timestamp
129 date of the (selected) entry as a timestamp in seconds since
130 the epoch
131 Closes
133 bugs closed by the (selected) entry/entries, sorted by bug
134 number
135 Changes
137 content of the (selected) entry/entries
138 $control = $c->dpkg($range)
140 This is a deprecated alias for $c->format_range('dpkg', $range).
141 @controls = $c->rfc822($range)
143 This is a deprecated alias for "scalar c-"format_range('rfc822',
144 $range)>.
145
147 A range selection is described by a hash reference where the allowed
148 keys and values are described below.
149 The following options take a version number as value.
151 since
153 Causes changelog information from all versions strictly later than
154 version to be used.
155 until
157 Causes changelog information from all versions strictly earlier
158 than version to be used.
159 from
161 Similar to "since" but also includes the information for the
162 specified version itself.
163 to Similar to "until" but also includes the information for the
165 specified version itself.
166 The following options don't take version numbers as values:
168 all If set to a true value, all entries of the changelog are returned,
170 this overrides all other options.
171 count
173 Expects a signed integer as value. Returns "value" entries from the
174 top of the changelog if set to a positive integer, and "abs(value)"
175 entries from the tail if set to a negative integer.
176 offset
178 Expects a signed integer as value. Changes the starting point for
179 "count", either counted from the top (positive integer) or from the
180 tail (negative integer). "offset" has no effect if "count" wasn't
181 given as well.
182 Some examples for the above options. Imagine an example changelog with
184 entries for the versions 1.2, 1.3, 2.0, 2.1, 2.2, 3.0 and 3.1.
185 Range Included entries
187 ----- ----------------
188 since => '2.0' 3.1, 3.0, 2.2
189 until => '2.0' 1.3, 1.2
190 from => '2.0' 3.1, 3.0, 2.2, 2.1, 2.0
191 to => '2.0' 2.0, 1.3, 1.2
192 count => 2 3.1, 3.0
193 count => -2 1.3, 1.2
194 count => 3, offset => 2 2.2, 2.1, 2.0
195 count => 2, offset => -3 2.0, 1.3
196 count => -2, offset => 3 3.0, 2.2
197 count => -2, offset => -3 2.2, 2.1
198 Any combination of one option of "since" and "from" and one of "until"
200 and "to" returns the intersection of the two results with only one of
201 the options specified.
202
204 Version 1.01 (dpkg 1.18.8)
205 New method: $c->format_range().
206 Deprecated methods: $c->dpkg(), $c->rfc822().
208 New field Timestamp in output formats.
210 Version 1.00 (dpkg 1.15.6)
212 Mark the module as public.
2131.18.25 2018-06-26 Dpkg::Changelog(3)