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

NAME

Changes - Changes file management

SYMOPSIS

use Changes;
my $c = Changes->load( '/some/where/Changes',
{
file => '/some/where/else/CHANGES',
max_width => 78,
type => 'cpan',
debug => 4,
}) || die( Changes->error );
say "Found ", $c->releases->length, " releases.";
my $rel = $c->add_release(
    version => 'v0.1.1',
    # Accepts relative time
    datetime => '+1D',
    note => 'CPAN update',
) || die( $c->error );
$rel->changes->push( $c->new_change(
    text => 'Minor corrections in unit tests',
) ) || die( $rel->error );
# Writing to /some/where/else/CHANGES even though we read from /some/where/Changes
$c->write || die( $c->error );

VERSION

v0.1.0

DESCRIPTION

This module is designed to read and update Changes files that are provided as part of change management in software distribution.

It is not limited to CPAN, and is versatile and flexible giving you a lot of control.

Its distinctive value compared to other modules that handle Changes file is that it does not attempt to reformat release and change information if they have not been modified. This ensure not just speed, but also that existing formatting of Changes file remain unchanged. You can force reformatting of any release section by calling "reset" in Changes::Release

This module does not "die" in perlfunc upon error, but instead returns an error object, so you need to check for the return value when you call any methods in this package distribution.

CONSTRUCTOR

new

Provided with an optional hash or hash reference of properties-values pairs, and this will instantiate a new Changes object and return it.

Supported properties are the same as the methods listed below.

If an error occurs, this will return an error

load

Provided with a file path, and an optional hash or hash reference of parameters, and this will parse the Changes file and return a new object. Thus, this method can be called either using an existing object, or as a class function:

my $c2 = $c->load( '/some/where/Changes' ) ||
    die( $c->error );
# or
my $c = Changes->load( '/some/where/Changes' ) ||
    die( Changes->error );

load_data

Provided with some string and an optional hash or hash reference of parameters and this will parse the Changes file data and return a new object. Thus, this method can be called either using an existing object, or as a class function:

my $c2 = $c->load_data( $changes_data ) ||
    die( $c->error );
# or
my $c = Change->load_data( $changes_data ) ||
    die( Changes->error );

METHODS

as_string

Returns a string object representing the entire Changes file. It does so by getting the value set with preamble, and by calling each element stored in "elements". Those elements can be Changes::Release and Changes::Group and possibly Changes::Change object. Each one of those element's as_string method will be called to contribute to the overall result.

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.

elements

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

epilogue

Sets or gets the text of the epilogue. An epilogue is a chunk of text, possibly multi line, that appears at the bottom of the Changes file after the last release information, separated by a blank line.

file

my $file = $c->file;
$c->file( '/some/where/Changes' );

Sets or gets the file path of the Changes file. This returns a file object

max_width

Sets or gets the maximum line width for a change inside a release. The line width includes an spaces at the beginning of the line and not just the text of the change itself.

For example:

v0.1.0 2022-11-17T08:12:42+0900
    - Some very long line of change going here, which can be wrapped here at 78 characters

wrapped at 78 characters would become:

v0.1.0 2022-11-17T08:12:42+0900
    - Some very long line of change going here, which can be wrapped here at 
      78 characters

new_change

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

If an error occurred, it returns an error object

new_group

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

If an error occurred, it returns an error object

new_line

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

If an error occurred, it returns an error object

new_release

Returns a new Changes::Release 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

parse

Provided with an array reference of lines to parse and this will parse each line and create all necessary release, group and change objects.

It returns the current object it was called with upon success, and returns an error upon error.

preamble

Sets or gets the text of the preamble. A preamble is a chunk of text, possibly multi line, that appears at the top of the Changes file before any release information.

releases

Read only. This returns an array object containing all the release objects within the Changes file.

type

Sets or get the type of Changes file format this is.

wrapper

Sets or gets a code reference as a callback mechanism to return a properly wrapped change text. This allows flexibility beyond the default use of Text::Wrap and Text::Format by Changes::Change

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Changes::Release, 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.