/ 
OpenInteract-1.99_01
River stage zero No dependents
/ OpenInteract2::Config::PackageChanges

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 doesn't 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're going through a lot of changes quickly may not add a message for each version.

BTW: Yes, it's not really a configuration file. But it mostly fits, and it doesn't 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

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 brevity's sake.

source_package: We rely on the package to tell us whereits 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're 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.

BUGS

None known.

TO DO

Nothing known.

COPYRIGHT

Copyright (c) 2003 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>