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