/ 
Changes-v0.1.0
River stage one • 1 direct dependent • 1 total dependent
/ Changes::Release

NAME

Changes::Release - Release object class

SYNOPSIS

use Changes::Release;
my $rel = Changes::Release->new(
    # A Changes object
    container => $changes_object,
    datetime => '2022-11-17T08:12:42+0900',
    datetime_formatter => sub
    {
        my $dt = shift( @_ ) || DateTime->now;
        require DateTime::Format::Strptime;
        my $fmt = DateTime::Format::Strptime->new(
            pattern => '%FT%T%z',
            locale => 'en_GB',
        );
        $dt->set_formatter( $fmt );
        $dt->set_time_zone( 'Asia/Tokyo' );
        return( $dt );
    },
    format => '%FT%T%z',
    line => 12,
    note => 'Initial release',
    spacer => "\t",
    time_zone => 'Asia/Tokyo',
    version => 'v0.1.0',
) || die( Changes::Release->error, "\n" );
say $rel->as_string;

VERSION

v0.1.0

DESCRIPTION

This class implements a Changes file release line. Such information usually comprise of a version number, a release datetime and an optional note

Each release section can contain group and changes that are all stored and accessible in "changes"

If an error occurred, it returns an error

The result of this method is cached so that the second time it is called, the cache is used unless there has been any change.

METHODS

changes

Read only. This returns an array object containing all the change objects within this release object.

container

Sets or gets the container object for this release object. A container is the object representing the Changes file: a Changes object.

Note that if you instantiate a release object directly, this value will obviously be undef. This value is set by Changes upon parsing the Changes file.

datetime

Sets or gets the release datetime information. This uses "_parse_datetime" in Module::Generic to parse the string, so please check that documentation for supported format.

However, most format are supported including ISO8601 format and W3CDTF format (e.g. 2022-07-17T12:10:03+09:00)

You can alternatively directly set a DateTime object.

It returns a DateTime object whose date formatter object is set to the same format as provided. This ensures that any stringification of the DateTime object reverts back to the string as found in the Changes file or as provided by the user.

datetime_formatter

Sets or gets a code reference callback to be used when formatting the release datetime. This allows you to use alternative formatter and greater control over the formatting of the release datetime.

It must return a DateTime object. Any other value will be discarded and it will fallback on setting up a DateTime with current date and time using UTC as time zone and $DEFAULT_DATETIME_FORMAT as default datetime format.

The code executed may die if needed and any exception will be caught and a warning will be issued if warnings are enabled for Changes.

elements

Sets or gets an array object of all the elements within this release object. Those elements can be Changes::Group, Changes::Change and Changes::NewLine objects.

format

Sets or gets a DateTime format to be used with DateTime::Format::Strptime. See "STRPTIME PATTERN TOKENS" in DateTime::Format::Strptime for details on possible patterns.

You can also specify an alternative formatter with "datetime_formatter"

It returns a scalar object

groups

Read only. This returns an array object containing all the group objects within this release object.

line

Sets or gets an integer representing the line number where this release line was found in the original Changes file. If this object was instantiated separately, then obviously this value will be undef

nl

Sets or gets the new line character, which defaults to \n

It returns a number object

note

Sets or gets an optional note that is set after the release datetime.

It returns a scalar object

raw

Sets or gets the raw line as found in the Changes file for this release. If nothing is change, and a raw version exists, then it is returned instead of computing the formatting of the line.

It returns a scalar object

spacer

Sets or gets the space that can be found between the version information and the datetime. Normally this would be just one space, but since it can be other space, this is used to capture it and ensure the result is identical to what was parsed.

It returns a scalar object

time_zone

Sets or gets a time zone to use for the release date. A valid time zone can either be an olson time zone string such as Asia/Tokyo, or an DateTime::TimeZone object.

It returns a DateTime::TimeZone object upon success, or an error if an error occurred.

version

Sets or gets the version information for this release. This returns a version object. If you prefer to use a different class, such as Perl::Version, then you can set the global variable $VERSION_CLASS accordingly.

It returns a version object, or an object of whatever class you have set with $VERSION_CLASS

changes

Sets or gets the array object containing all the object representing the changes for that release. Those changes can be Changes::Group, Changes::Change or Changes::Line

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Changes, Changes::Group, Changes::Change

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.