para

use v6;
unit module Term::Choose::LineFold:ver<2.0.6>;

use Term::Choose::Constant;
use Term::Choose::Screen;


my $table;
if %*ENV<TC_AMBIGUOUS_WIDTH_IS_WIDE> {
    require Term::Choose::LineFold::CharWidthAmbiguousWide <&table_char_width>;
    $table = table_char_width();
}
else {
    require Term::Choose::LineFold::CharWidthDefault <&table_char_width>;
    $table = table_char_width();
}


sub char-width( Int $ord_char ) returns Int is export( :DEFAULT, :char-width ) {
    my Int $min = 0;
    my Int $mid;
    my Int $max = $table.end;
    if $ord_char < $table[0][0] || $ord_char > $table[$max][1] {
        return 1;
    }
    while $max >= $min {
        $mid = ( $min + $max ) div 2;
        if $ord_char > $table[$mid][1] {
            $min = $mid + 1;
        }
        elsif $ord_char < $table[$mid][0] {
            $max = $mid - 1;
        }
        else {
            return $table[$mid][2];
        }
    }
    return 1;
}


sub to-printwidth( $str, Int $avail_w, Int $dot=0, %cache? ) is export( :DEFAULT, :to-printwidth ) {
    # no check if char-width returns -1 because no invalid characters (s:g/<:C>//)
    my Int $width = 0;
    my Str @graph;
    for $str.NFC {
        my $w;
        if %cache.EXISTS-KEY( $_ ) {
            $w := %cache.AT-KEY( $_ );
        }
        else {
            $w := %cache.BIND-KEY( $_, char-width( $_ ) );
        }
        if $width + $w > $avail_w {
            if $dot && $avail_w > 5 {
                my \tail = '...';
                my \tail_w = 3;
                while $width > $avail_w - tail_w {
                    $width -= %cache.AT-KEY( @graph.pop.ord );
                }
                return @graph.join( '' ) ~ '.' ~ tail, $width + tail_w + 1 if $width < $avail_w - tail_w;
                return @graph.join( '' )       ~ tail, $width + tail_w;
            }
            return @graph.join( '' ) ~ ' ', $width + 1 if $width < $avail_w;
            return @graph.join( '' )      , $width;
        }
        $width = $width + $w;
        @graph.push: .chr;
    }
    return @graph.join( '' ), $width;
}


sub line-fold(
        $str,
        Positive_Int :$width = get-term-size().[0] + extra-w,
        :$init-tab is copy = '',
        :$subseq-tab is copy = '',
        Int_0_or_1 :$join = 1,
        Int_0_or_1 :$truncate-long-tabs = 1,
        Int_0_to_2 :$color = 0,
        Int_0_to_2 :$binary-filter = 0
    ) is export( :DEFAULT, :line-fold ) {

    if ! $str.defined || ! $str.chars {
        return $str;
    }
    for $init-tab, $subseq-tab {
        if $_.chars {
            if / ^ <[0..9]>+ $ / {
                $_ = ' ' x $_;
            }
            else {
                $_.=subst( / \t /,  ' ', :g ).=subst( / \v+ /,  '  ', :g ).=subst( &rx-invalid-char, '', :g ),
            }
            if $truncate-long-tabs && print-columns( $_ ) > $width div 2 {
                $_ = to-printwidth( $_, $width div 2, False ).[0];
            }
        }
    }
    my $str_copy = $str;
    if $str_copy ~~ Buf {
        $str_copy = $str_copy.gist; # perl
    }
    my Str @colors;
    if $color { # 1 or 2 # elsif 
        $str_copy.=subst( / $(ph-char) /, '', :g );
        $str_copy.=subst( / ( <rx-color> ) /, { @colors.push( $0.Str ) && ph-char }, :g );
    }
    if $binary-filter && $str_copy.substr( 0, 100 ).match: &rx-is-binary {
        if $binary-filter == 2 {
            $str_copy = $str.encode>>.fmt('%02X').Str;
        }
        else {
            $str_copy = 'BNRY';
        }
    }
    $str_copy.=subst( / \t /, ' ', :g );
    $str_copy.=subst( / <rx-invalid-char> && \V /, '' , :g ); #
    my Str @lines;

    for $str_copy.lines -> $row {
        my Str @words;
        if $row ~~ / \S / {
            @words = $row.trim-trailing.split( / <?after \S > <?before \s > / );
        }
        else {
            @words = $row;
        }
        my Str $line = $init-tab;

        for 0 .. @words.end -> $i {
            if print-columns( $line ~ @words[$i] ) <= $width {
                $line ~= @words[$i];
            }
            else {
                my Str $tmp;
                if $i == 0 {
                    $tmp = $init-tab ~ @words[$i];
                }
                else {
                    @lines.push: $line;
                    $tmp = $subseq-tab ~ @words[$i].subst( / ^ \s+ /, '' );
                }
                $line = to-printwidth( $tmp, $width, False ).[0];
                my Str $remainder = $tmp.substr( $line.chars );
                while $remainder.chars {
                    @lines.push( $line );
                    $tmp = $subseq-tab ~ $remainder;
                    $line = to-printwidth( $tmp, $width, False ).[0];
                    $remainder = $tmp.substr( $line.chars );
                }
            }
            if $i == @words.end {
                @lines.push( $line );
            }
        }
    }
    if @colors.elems {
        my Str $last_color;
        for @lines -> $line is rw {
            if ! $join {
                if $last_color {
                    $line = $last_color ~ $line;
                }
                my Int $count = $line.comb( $(ph-char) ).elems;
                if $count {
                    $last_color = @colors[$count - 1];
                }
            }
            $line.=subst( / $(ph-char) /, { @colors.shift }, :g );
            if ! @colors.elems {
                last;
            }
        }
    }
    @lines.push( '' ) if $str_copy.ends-with( "\n" );
    return @lines.join: "\n" if $join;
    return @lines; #
}


sub print-columns( $str, %cache? ) returns Int is export( :DEFAULT, :print-columns ) {
    # no check if char-width returns -1 because invalid characters removed
    my Int $width = 0;
    for $str.Str.NFC {
        if %cache.EXISTS-KEY( $_ ) {
            $width = $width + %cache.AT-KEY( $_ );
        }
        else {
            $width = $width + %cache.BIND-KEY( $_, char-width( $_ ) );
        }
    }
    $width;
}





head

Term::Choose::LineFold - print-columns and line-fold


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


use Term::Choose::LineFold qw( print-columns );


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


$print-width = print-columns( $string );


$print-width = print-columns( $string, %cache );


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


Passing a hash (C<%cache>) to cache the character widths is optional.


$folded-string = line-fold( $string, :120width, :1color );


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.


item

If not set, defaults to the terminal width.


Sets the initial tab inserted at the beginning of paragraphs. If a value consisting of C</^<[0..9]>+$/> is provided,
the tab will be that number of spaces. Otherwise, the provided value is used directly as the tab. 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.


Sets the subsequent tab inserted at the beginning of all broken lines (excluding paragraph beginnings). If a value
consisting of C</^<[0..9]>+$/> is provided, the tab will be that number of spaces. Otherwise, the provided value is
used directly as the tab. 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.


If enabled (default), I<init-tab> and I<subseq-tab> are truncated if they exceed half of the terminal width.


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


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


Term::Choose::LineFold is not installable on Windows.


This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


root

README

React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<AI|file:../mcp/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>
    =item2 L<Hand these documents to an AI assistant|file:../mcp/index.podlite>

=end nested
=begin nested :!nested
=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>

=end nested
=end React


Built with L<Podlite|https://podlite.org> — the markup and publishing tools behind this site.


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


LineFold

NAME

DESCRIPTION

EXPORT

FUNCTIONS

print-columns

line-fold

Options

Ambiguous width characters

Restrictions

AUTHOR

LICENSE AND COPYRIGHT

Term::Choose v2.0.6

Authors

License

Dependencies

Test Dependencies

Provides

Documentation