1Dpkg::Changelog(3perl)           libdpkg-perl           Dpkg::Changelog(3perl)
2
3
4

NAME

6       Dpkg::Changelog - base class to implement a changelog parser
7

DESCRIPTION

9       Dpkg::Changelog is a class representing a changelog file as an array of
10       changelog entries (Dpkg::Changelog::Entry).  By deriving this class and
11       implementing its parse method, you add the ability to fill this object
12       with changelog entries.
13

METHODS

15       $c = Dpkg::Changelog->new(%options)
16           Creates a new changelog object.
17
18       $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
26       $count = $c->parse($fh, $description)
27           Read the filehandle and parse a changelog in it. The data in the
28           object is reset before parsing new data.
29
30           Returns the number of changelog entries that have been parsed with
31           success.
32
33           This method needs to be implemented by one of the specialized
34           changelog format subclasses.
35
36       $count = $c->load($filename)
37           Parse $filename contents for a changelog.
38
39           Returns the number of changelog entries that have been parsed with
40           success.
41
42       $c->reset_parse_errors()
43           Can be used to delete all information about errors occurred during
44           previous parse runs.
45
46       $c->parse_error($file, $line_nr, $error, [$line])
47           Record a new parse error in $file at line $line_nr. The error
48           message is specified with $error and a copy of the line can be
49           recorded in $line.
50
51       $c->get_parse_errors()
52           Returns all error messages from the last parse run.  If called in
53           scalar context returns a human readable string representation. If
54           called in list context returns an array of arrays. Each of these
55           arrays contains
56
57           1.  a string describing the origin of the data (a filename
58               usually). If the reportfile configuration option was given, its
59               value will be used instead.
60
61           2.  the line number where the error occurred
62
63           3.  an error description
64
65           4.  the original line
66
67       $c->set_unparsed_tail($tail)
68           Add a string representing unparsed lines after the changelog
69           entries.  Use undef as $tail to remove the unparsed lines currently
70           set.
71
72       $c->get_unparsed_tail()
73           Return a string representing the unparsed lines after the changelog
74           entries. Returns undef if there's no such thing.
75
76       @{$c}
77           Returns all the Dpkg::Changelog::Entry objects contained in this
78           changelog in the order in which they have been parsed.
79
80       $c->get_range($range)
81           Returns an array (if called in list context) or a reference to an
82           array of Dpkg::Changelog::Entry objects which each represent one
83           entry of the changelog. $range is a hash reference describing the
84           range of entries to return. See section "RANGE SELECTION".
85
86       $c->abort_early()
87           Returns true if enough data have been parsed to be able to return
88           all entries selected by the range set at creation (or with
89           set_options).
90
91       $str = $c->output()
92       "$c"
93           Returns a string representation of the changelog (it's a
94           concatenation of the string representation of the individual
95           changelog entries).
96
97       $c->output($fh)
98           Output the changelog to the given filehandle.
99
100       $c->save($filename)
101           Save the changelog in the given file.
102
103       $control = $c->format_range($format, $range)
104           Formats the changelog into Dpkg::Control::Changelog objects
105           representing the entries selected by the optional range specifier
106           (see "RANGE SELECTION" for details). In scalar context returns a
107           Dpkg::Index object containing the selected entries, in list context
108           returns an array of Dpkg::Control::Changelog objects.
109
110           With format dpkg the returned Dpkg::Control::Changelog object is
111           coalesced from the entries in the changelog that are part of the
112           range requested, with the fields described below, but considering
113           that "selected entry" means the first entry of the selected range.
114
115           With format rfc822 each returned Dpkg::Control::Changelog objects
116           represents one entry in the changelog that is part of the range
117           requested, with the fields described below, but considering that
118           "selected entry" means for each entry.
119
120           The different formats return undef if no entries are matched. The
121           following fields are contained in the object(s) returned:
122
123           Source
124               package name (selected entry)
125
126           Version
127               packages' version (selected entry)
128
129           Distribution
130               target distribution (selected entry)
131
132           Urgency
133               urgency (highest of all entries in range)
134
135           Maintainer
136               person that created the (selected) entry
137
138           Date
139               date of the (selected) entry
140
141           Timestamp
142               date of the (selected) entry as a timestamp in seconds since
143               the epoch
144
145           Closes
146               bugs closed by the (selected) entry/entries, sorted by bug
147               number
148
149           Changes
150               content of the (selected) entry/entries
151

RANGE SELECTION

153       A range selection is described by a hash reference where the allowed
154       keys and values are described below.
155
156       The following options take a version number as value.
157
158       since
159           Causes changelog information from all versions strictly later than
160           version to be used.
161
162       until
163           Causes changelog information from all versions strictly earlier
164           than version to be used.
165
166       from
167           Similar to "since" but also includes the information for the
168           specified version itself.
169
170       to  Similar to "until" but also includes the information for the
171           specified version itself.
172
173       The following options don't take version numbers as values:
174
175       all If set to a true value, all entries of the changelog are returned,
176           this overrides all other options.
177
178       count
179           Expects a signed integer as value. Returns "value" entries from the
180           top of the changelog if set to a positive integer, and "abs(value)"
181           entries from the tail if set to a negative integer.
182
183       offset
184           Expects a signed integer as value. Changes the starting point for
185           "count", either counted from the top (positive integer) or from the
186           tail (negative integer). "offset" has no effect if "count" wasn't
187           given as well.
188
189       Some examples for the above options. Imagine an example changelog with
190       entries for the versions 1.2, 1.3, 2.0, 2.1, 2.2, 3.0 and 3.1.
191
192         Range                        Included entries
193         -----                        ----------------
194         since => '2.0'               3.1, 3.0, 2.2
195         until => '2.0'               1.3, 1.2
196         from  => '2.0'               3.1, 3.0, 2.2, 2.1, 2.0
197         to    => '2.0'               2.0, 1.3, 1.2
198         count =>  2                  3.1, 3.0
199         count => -2                  1.3, 1.2
200         count =>  3, offset => 2     2.2, 2.1, 2.0
201         count =>  2, offset => -3    2.0, 1.3
202         count => -2, offset => 3     3.0, 2.2
203         count => -2, offset => -3    2.2, 2.1
204
205       Any combination of one option of "since" and "from" and one of "until"
206       and "to" returns the intersection of the two results with only one of
207       the options specified.
208

CHANGES

210   Version 2.00 (dpkg 1.20.0)
211       Remove methods: $c->dpkg(), $c->rfc822().
212
213   Version 1.01 (dpkg 1.18.8)
214       New method: $c->format_range().
215
216       Deprecated methods: $c->dpkg(), $c->rfc822().
217
218       New field Timestamp in output formats.
219
220   Version 1.00 (dpkg 1.15.6)
221       Mark the module as public.
222
223
224
2251.21.9                            2022-08-04            Dpkg::Changelog(3perl)
Impressum