/ 
Term-Choose-1.770
River stage one • 7 direct dependents • 8 total dependents
/ Term::Choose::LineFold

NAME

Term::Choose::LineFold - print_columns, cut_to_printwidth and line_fold

VERSION

Version 1.770

DESCRIPTION

Width in this context refers to the number of occupied columns of a character string on a terminal with a monospaced font.

By default ambiguous width characters are treated as half width. If the environment variable TC_AMBIGUOUS_WIDTH_IS_WIDE is set to a true value, ambiguous width characters are treated as full width.

EXPORT

Nothing by default.

use Term::Choose::LineFold qw( print_columns );

FUNCTIONS

Get the number of occupied columns of a character string on a terminal.

The string passed to this function is a decoded string, free of control characters, non-characters, and surrogates.

$print_width = print_columns( $string );

cut_to_printwidth

Cut a string to a specified width.

The string passed to this function is a decoded string, free of control characters, non-characters, and surrogates.

$cut_string = cut_to_printwidth( $string, $width );

When used in a list context, the function returns both the cut string and the remaining portion of the original string. If there is no remaining portion, it returns an empty string instead.

( $cut_string, $remainder ) = cut_to_printwidth( $string, $width );

If the width of the cut string is less than $width, a space character is appended.

$cut_string = cut_to_printwidth(  "A🙂🙂🙂🙂", 6 );

say "|$cut_string|"; # |A🙂🙂 |

line_fold

Fold a string.

This function accepts a decoded string. Control characters (excluding vertical spaces), non-characters, and surrogates are removed before the string is folded. Changes are applied to a copy; the passed string is unchanged.

$folded_string = line_fold( $string );

$folded_string = line_fold( $string, { width => 120, color => 1 } );

Options

width

If not set, defaults to the terminal width.

width is 1 or greater.

init_tab

Sets the initial tab inserted at the beginning of paragraphs. If a positive integer is provided, the initial tab will be int_tab spaces. If a non-numeric value is provided, it will be used as the initial tab directly. By default, no initial tab is inserted. If the initial tab is longer than half the available width, it will be cut to half the available width

subseq_tab

Sets the subsequent tab inserted at the beginning of all broken lines (excluding paragraph beginnings). If a positive integer is provided, the subsequent tab will be subseq_tab spaces. If a non-numeric value is provided, it will be used as the subsequent tab directly. By default, no subsequent tab is inserted. If the subsequent tab is longer than half the available width, it will be cut to half the available width

color

Enables support for ANSI SGR escape sequences. If enabled, all zero-width no-break spaces (0xfeff) are removed.

color is 0 or 1.

AUTHOR

Matthäus Kiem <cuer2s@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2025 Matthäus Kiem.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For details, see the full text of the licenses in the file LICENSE.