The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Changes-v0.3.5
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" );
    my $change = $rel->add_change( $change_object );
    # or
    my $change = $rel->add_change( text => 'Some comments' );
    my $group = $rel->add_group( $group_object );
    # or
    my $group = $rel->add_group( name => 'Some group' );
    my $change = $rel->delete_change( $change_object );
    my $group = $rel->delete_group( $group_object );
    say $rel->as_string;

VERSION

    v0.2.2

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

add_change

Provided with a Changes::Change object, or an hash or hash reference of options passed to the constructor of Changes::Change, and this will add the change object to the list of elements for this release object.

It returns the Changes::Change object, or an error if an error occurred.

add_group

Provided with a Changes::Group object, or an hash or hash reference of options passed to the constructor of Changes::Group, and this will add the change object to the list of elements.

It returns the Changes::Group object, or an error if an error occurred.

as_string

Returns a string object representing the release. It does so by calling as_string on each element stored in "elements". Those elements can be Changes::Group and Changes::Change objects.

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.

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 formats.

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

Note that if you use a relative datetime format such as -2D for 2 days ago, the datetime format will be set to a unix timestamp, and in that case you need to also specify the format option with the desired datetime format.

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.

This code is called with a DateTime object, and 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.

defaults

Sets or gets an hash of default values for the Changes::Change object when it is instantiated by the new_change method.

Default is undef, which means no default value is set.

    my $ch = Changes->new(
        file => '/some/where/Changes',
        defaults => {
            # For Changes::Change
            spacer1 => "\t",
            spacer2 => ' ',
            marker => '-',
            max_width => 72,
            wrapper => $code_reference,
            # For Changes::Group
            group_spacer => "\t",
            group_type => 'bracket', # [Some group]
        }
    );

delete_change

This takes a list of change to remove and returns an array object of those changes thus removed.

A change provided can only be a Changes::Change object.

If an error occurred, this will return an error

delete_group

This takes a list of group to remove and returns an array object of those groups thus removed.

A group provided can either be a Changes::Group object, or a group name as a string.

If an error occurred, this will return an error

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"

If you specify the special value default, it will use default value set in the global variable $DEFAULT_DATETIME_FORMAT, which is %FT%T%z (for example: 2022-12-08T20:13:09+0900)

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

new_change

Instantiates and returns a new Changes::Change, passing its constructor any argument provided.

    my $change = $rel->new_change( text => 'Some change' ) ||
        die( $rel->error );

new_group

Instantiates and returns a new Changes::Group, passing its constructor any argument provided.

    my $change = $rel->new_group( name => 'Some group' ) ||
        die( $rel->error );

new_line

Returns a new Changes::NewLine object, passing it any parameters provided.

If an error occurred, it returns an error object

new_version

Returns a new Changes::Version object, passing it any parameters provided.

If an error occurred, it returns an error object

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

remove_change

This is an alias for "delete_change"

remove_group

This is an alias for "delete_group"

set_default_format

Sets the default DateTime format pattern used by DateTime::Format::Strptime. This default value used is $DEFAULT_DATETIME_FORMAT, which, by default is: %FT%T%z, i.e. something that would look like 2022-12-06T20:13:09+0900

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.

This defaults to a single space if it is not set.

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, Changes::Version, Changes::NewLine

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.