NAME

OpenInteract2::Config::PackageChanges - Represent entries from a package Changes file

SYNOPSIS

 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 );

DESCRIPTION

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.

METHODS

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.

Parameters, all optional:

• package: Corresponds to the source_package property

• dir: Corresponds to the source_dir property

• file: Corresponds to the source_file property

• content: Corresponds to the source_content property

read_config()

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().

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.

Throws exception if there is an error writing to the file or if $filename already exists and we cannot rename it to a backup.

Properties

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_package: We rely on the package to tell us where its directory is, then use the CHANGES_FILE file in it.

source_dir: Find the file CHANGES_FILE in it.

source_file: Read directly from the file specified

source_content: Use this as the changelog.

Retrieving Changelog Entries

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.

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.

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.

before( $version )

Returns: array of entries that have a version number less than or equal to $version.

Adding Changelog Entries

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

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.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract2::URL

perl -MCPAN -e shell
install OpenInteract2::URL