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.

