NAME

Changes::Change - Changes object class

SYNOPSIS

    use Changes::Change;
    my $this = Changes::Change->new(
        line => 12,
        marker => '-',
        max_width => 68,
        spacer1 => "\t",
        # Defaults to just one space
        spacer2 => undef,
        text => "This is a change note",
        wrapper => sub
        {
            my( $text, $width ) = @_;
            require Text::Wrap;
            local $Text::Wrap::columns = $width;
            my $result = Text::Wrap::wrap( '', '', "$text" );
            return( $result );
        }
    ) || die( Changes::Change->error, "\n" );

VERSION

    v0.1.1

DESCRIPTION

This represents a change line within a release. A change line is usually represented by some indentation spaces, followed by a marker such as a dash, a space and a text:

    - This is a change note

A change text can be written on a very long line or broken into lines of max_width. You can change this value with "max_width" and by default it is 0, which means it will be all on one line.

METHODS

as_string

Returns a scalar object of the change line. This information is cached unless other information has been changed.

Also, if nothing was changed and "raw" is set with a value, that value will be returned instead.

If "wrapper" is defined, the perl code reference set will be called by providing it the text of the change and the adjusted width to use. The actual width is the width of the change text with any leading spaces and characters as specified with "spacer1", "spacer2" and "marker".

If the callback dies, this exception will be caught and displayed as a warning if use warnings is enabled.

If no callback is specified, it will attempt to load Text::Wrap (a perl core module) and Text::Format in this order.

If none of it is possible, the change text will simply not be wrapped.

If an error occurred, it returns an error

The resulting string is terminated by the carriage return sequence defined with "nl"

It returns a scalar object

line

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

marker

Sets or gets the character representing the marker preceding the text of the change. This is usually a dash.

It returns a scalar object

max_width

Sets or gets the change line maximum width. The line width includes any spaces and characters at the beginning of the line, as set with "spacer1", "spacer2" and "marker" and not just the text of the change itself.

It returns a number object

nl

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

It returns a number object

normalise

This returns a "normalised" version of the change text, which means that if the change text is wrapped and has new lines with possibly preceding and trailing spaces, those will be replaced by a single space.

It does not modify the original change text.

It returns a scalar object

prefix

Read-only. This returns what precedes the text of the change, which is an optional leading space, and a marker such as a dash.

It returns a scalar object

raw

Sets or gets the raw version of the line as found in the Changes file. If set and nothing has been changed, this will be returned by "as_string" instead of computing the formatting of the change.

It returns a scalar object

spacer1

Sets or gets the leading space, if any, found before the marker.

It returns a scalar object

spacer2

Sets or gets the space found after the marker and before the text of the change.

It returns a scalar object

text

Sets or gets the text o the change. If the text is broken into multiple lines in the Changes file, it will be collected as on scalar object here.

It returns a scalar object

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

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

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

cpanm Changes

perl -MCPAN -e shell
install Changes