OpenInteract2::Config::PackageChanges - Represent entries from a package Changes file
my $changes = OpenInteract2::Config::PackageChanges->new({ package => $pkg }); my $changes = OpenInteract2::Config::PackageChanges->new({ dir => '/path/to/file/' }); my $changes = OpenInteract2::Config::PackageChanges->new({ file => '/path/to/Changes' }); my $changes = OpenInteract2::Config::PackageChanges->new({ content => $changelog_content }); my $changes = OpenInteract2::Config::PackageChanges->new(); $changes->source_package( $pkg ); $changes->source_dir( $pkg ); $changes->source_file( $pkg ); $changes->source_content( $content ); # Get the latest 10 entries my @entries = $changes->latest( 10 ); foreach my $entry ( @entries ) { print "Version: $entry->{version}\n", "Date: $entry->{date}\n", "$entry->{message}\n\n"; } # Get all entries since a particular version my @entries = $changes->since( '1.07' ); # Get the first 5 entries my @entries = $changes->first( 5 ); # Get the name of the file to use for your changelog use OpenInteract2::Config::PackageChanges qw( CHANGES_FILE ); ... my $full_name = File::Spec->catfile( 'thatdir', 'otherdir', CHANGES_FILE );
A changelog looks something like this:
Changelog for package foo 0.10 Wed Apr 9 08:48:12 EDT 2003 This version introduces the new interface for the frobnicator; it mostly works but needs to be tested a little more. 0.09 Mon Mar 31 09:12:35 EDT 2003 Messing about the the frobnicator internals... 0.08 Fri Mar 14 23:09:11 EDT 2003 Fix bug in frobnicator so it does not blow up whenever a value greater than 500 passed in...
The parser assumes this format. The date can be formatted any way you like, but we assume that something looking like a version at the beginning of a line marks a new entry.
The only required piece of information for an entry is a version -- some people may not add the date, or if they are going through a lot of changes quickly may not add a message for each version.
BTW: Yes, it is not really a configuration file. But it mostly fits, and it does not make sense to put this into OpenInteract2::Package and bulk that package up even more.
new( \%params )
Creates a new object. If package, dir, file or content is passed in we read and parse the changelog immediately. Otherwise you have to call read_config() yourself after setting one of the sources of content.
package
dir
file
content
read_config()
Parameters, all optional:
package: Corresponds to the source_package property
source_package
dir: Corresponds to the source_dir property
source_dir
file: Corresponds to the source_file property
source_file
content: Corresponds to the source_content property
source_content
Reads the content from whatever source is set and parses it into changelog entries. You must call this before retrieving any of the changelog entries, either explicitly or by passing a content source to new().
new()
Before calling this you must have set one of the source_package, source_dir, source_file or source_content properties.
Returns: object
write_config( $filename )
Writes out changelog to $filename. Only preserves comments/text found before the first version.
$filename
Throws exception if there is an error writing to the file or if $filename already exists and we cannot rename it to a backup.
These properties only describe from where we get the changelog. If you pass them into new(), you can remove the source_ from the beginning for the sake of brevity.
source_
source_package: We rely on the package to tell us where its directory is, then use the CHANGES_FILE file in it.
CHANGES_FILE
source_dir: Find the file CHANGES_FILE in it.
source_file: Read directly from the file specified
source_content: Use this as the changelog.
The following methods return entries from the changelog. Methods that return multiple entries always return them in reverse order -- the newest entries are first, or earliest in the array. Even when you are returning the earliest changelog entries (like with first() or before()), the latest ones will still be at the front of the returned list.
first()
before()
Each entry is hashref with three members:
version: Version of the entry.
date: Date of the entry. This is not tranformed from how the user entered it in the changelog, and it may even be blank.
message: Message of the entry. This may be blank as well. On reading the message we remove all leading whitespace from every line. Blank lines are preserved.
entries()
Returns an array of all entries.
first( $number )
Returns: array of entries of size $number at the beginning of the changelog.
$number
latest( $number )
Returns: array of entries of size $number at the end of the changelog.
since( $version )
Returns: array of entries that have a version number greater than or equal to $version.
$version
before( $version )
Returns: array of entries that have a version number less than or equal to $version.
add_entry( $version, $date, $message )
Adds entry with changelog information to the internal list. This always puts the entry at the head of the list, assuming it is a new version.
Copyright (c) 2003-2004 Chris Winters. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Chris Winters <chris@cwinters.com>
To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenInteract2::URL
CPAN shell
perl -MCPAN -e shell install OpenInteract2::URL
For more information on module installation, please visit the detailed CPAN module installation guide.