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 class and
11 implementing its parse method, you add the ability to fill this object
12 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 $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 Returns the number of changelog entries that have been parsed with
31 success.
32 This method needs to be implemented by one of the specialized
34 changelog format subclasses.
35 $count = $c->load($filename)
37 Parse $filename contents for a changelog.
38 Returns the number of changelog entries that have been parsed with
40 success.
41 $c->reset_parse_errors()
43 Can be used to delete all information about errors occurred during
44 previous parse runs.
45 $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 $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 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 2. the line number where the error occurred
62 3. an error description
64 4. the original line
66 $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 $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 @{$c}
77 Returns all the Dpkg::Changelog::Entry objects contained in this
78 changelog in the order in which they have been parsed.
79 $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 $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 $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 $c->output($fh)
98 Output the changelog to the given filehandle.
99 $c->save($filename)
101 Save the changelog in the given file.
102 $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 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 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 The different formats return undef if no entries are matched. The
121 following fields are contained in the object(s) returned:
122 Source
124 package name (selected entry)
125 Version
127 packages' version (selected entry)
128 Distribution
130 target distribution (selected entry)
131 Urgency
133 urgency (highest of all entries in range)
134 Maintainer
136 person that created the (selected) entry
137 Date
139 date of the (selected) entry
140 Timestamp
142 date of the (selected) entry as a timestamp in seconds since
143 the epoch
144 Closes
146 bugs closed by the (selected) entry/entries, sorted by bug
147 number
148 Changes
150 content of the (selected) entry/entries
151
153 A range selection is described by a hash reference where the allowed
154 keys and values are described below.
155 The following options take a version number as value.
157 since
159 Causes changelog information from all versions strictly later than
160 version to be used.
161 until
163 Causes changelog information from all versions strictly earlier
164 than version to be used.
165 from
167 Similar to "since" but also includes the information for the
168 specified version itself.
169 to Similar to "until" but also includes the information for the
171 specified version itself.
172 The following options don't take version numbers as values:
174 all If set to a true value, all entries of the changelog are returned,
176 this overrides all other options.
177 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 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 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 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 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
210 Version 2.00 (dpkg 1.20.0)
211 Remove methods: $c->dpkg(), $c->rfc822().
212 Version 1.01 (dpkg 1.18.8)
214 New method: $c->format_range().
215 Deprecated methods: $c->dpkg(), $c->rfc822().
217 New field Timestamp in output formats.
219 Version 1.00 (dpkg 1.15.6)
221 Mark the module as public.
2221.20.9 2021-07-21 Dpkg::Changelog(3perl)