/ 
Text-ANSI-Fold-2.02
River stage two • 9 direct dependents • 15 total dependents
⭐ Starred 2 GitHub stars
/ README.md

NAME

Text::ANSI::Fold - Text folding library supporting ANSI terminal sequence and Asian wide characters with prohibition character handling.

VERSION

Version 2.02

SYNOPSIS

use Text::ANSI::Fold qw(ansi_fold);
($folded, $remain) = ansi_fold($text, $width, [ option ]);

use Text::ANSI::Fold;
my $f = Text::ANSI::Fold->new(width => 80, boundary => 'word');
$f->configure(ambiguous => 'wide');
($folded, $remain) = $f->fold($text);

use Text::ANSI::Fold;
while (<>) {
    print join "\n",
        Text::ANSI::Fold->new(width => 40, text => $_)->chops;
}

use Text::ANSI::Fold qw(:constants);
my $fold = Text::ANSI::Fold->new(
    width     => 70,
    boundary  => 'word',
    linebreak => LINEBREAK_ALL,
    runin     => 4,
    runout    => 4,
    );

DESCRIPTION

Text::ANSI::Fold provides capability to fold a text into two strings by given width. Text can include ANSI terminal sequences. If the text is divided in the middle of ANSI-effect region, reset sequence is appended to folded text, and recover sequence is prepended to trimmed string.

This module also support Unicode Asian full-width and non-spacing combining characters properly. Japanese text formatting with head-or-end of line prohibition character is also supported. Set the linebreak mode to enable it.

Use exported ansi_fold function to fold original text, with number of visual columns you want to cut off the text.

($folded, $remain, $w) = ansi_fold($text, $width);

It returns a pair of strings; first one is folded text, and second is the rest.

Additional third result is the visual width of folded text. You may want to know how many columns returned string takes for further processing. If the width parameter is negative, it returns string untouched and the visual width of it.

This function returns at least one character in any situation. If you provide Asian wide string and just one column as width, it trims off the first wide character even if it does not fit to given width.

Default parameter can be set by configure class method:

Text::ANSI::Fold->configure(width => 80, padding => 1);

Then you don't have to pass second argument.

($folded, $remain) = ansi_fold($text);

Because second argument is always taken as width, use undef when using default width with additional parameter:

($folded, $remain) = ansi_fold($text, undef, padding => 1);

OBJECT INTERFACE

You can create an object to hold parameters, which is effective during object life time. For example,

my $f = Text::ANSI::Fold->new(
    width => 80,
    boundary => 'word',
    );

makes an object folding on word boundaries with 80 columns width. Then you can use this without parameters.

$f->fold($text);

Use configure method to update parameters:

$f->configure(padding => 1);

Additional parameter can be specified on each call, and they precede saved value.

$f->fold($text, width => 40);

STRING OBJECT INTERFACE

Fold object can hold string inside by text method.

$f->text("text");

And folded string can be taken by retrieve method. It returns empty string if nothing remained.

while ((my $folded = $f->retrieve) ne '') {
    print $folded;
    print "\n" if $folded !~ /\n\z/;
}

Method chops returns chopped string list. Because text method returns the object itself, you can use text and chops like this:

print join "\n", $f->text($text)->chops;

Actually, text can be set by new or configure method through text option. Next program just works.

use Text::ANSI::Fold;
while (<>) {
    print join "\n",
        Text::ANSI::Fold->new(width => 40, text => $_)->chops;
}

When using chops method, width parameter can take array reference, and chops text into given width list.

my $fold = Text::ANSI::Fold->new;
my @list = $fold->text("1223334444")->chops(width => [ 1, 2, 3 ]);
# return ("1", "22", "333") and keep "4444"

If the width value is 0, it returns empty string.

Negative width value takes all the rest of holded string in retrieve and chops method.

OPTIONS

Option parameter can be specified as name-value list for ansi_fold function as well as new and configure method.

ansi_fold($text, $width, boundary => 'word', ...);

Text::ANSI::Fold->configure(boundary => 'word');

my $f = Text::ANSI::Fold->new(boundary => 'word');

$f->configure(boundary => 'word');

EXAMPLE

Next code implements almost perfect fold command for multi byte characters with prohibited character handling.

#!/usr/bin/env perl

use strict;
use warnings;
use open IO => 'utf8', ':std';

use Text::ANSI::Fold qw(:constants);
my $fold = Text::ANSI::Fold->new(
    width     => 70,
    boundary  => 'word',
    linebreak => LINEBREAK_ALL,
    runin     => 4,
    runout    => 4,
    );

$, = "\n";
while (<>) {
    print $fold->text($_)->chops;
}

SEE ALSO

LICENSE

Copyright (C) 2018- Kazumasa Utashiro.

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

AUTHOR