Term::...neFold(3pm)

📦
version 1.782 · 4 versions
, in ubuntu stonking

💖 Term::Choose::LineFold — the manual, but make it make sense 💖

okay bestie, sit down, hydrate, because this is Term::Choose::LineFold, a lil Perl module from the User Contributed Perl Documentation section of the manual. she's a Perl module (that's the 3pm energy, iykyk) and she's here to help you figure out how much space your strings are eating on a terminal. let's get into it 💅

✨ VERSION ✨

Version 1.782 — that's the one, that's what we're working with 🎀

🌸 DESCRIPTION 🌸

okay so first things first, we're talking about width, and in this context width means the number of occupied columns of a character string on a terminal that has a monospaced font. one character, one column-ish, basically. periodt.

by default, ambiguous width characters are treated as half width. but — plot twist — if the environment variable TC_AMBIGUOUS_WIDTH_IS_WIDE is set to a true value, then ambiguous width characters get treated as full width. no cap, that's the whole switch.

and now the glow-up news: if the optional Term::Choose::LineFold::XS module happens to be installed, its functions will be used automatically in place of the pure-Perl implementations, which gives you faster performance. she upgraded herself, we love that for her ✨

🎀 EXPORT 🎀

Nothing by default. like, literally nothing, she's shy at first.

but if you want something, you ask for it:

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

and then she's yours 🫶

💅 FUNCTIONS 💅

Get the number of occupied columns of a character string on a terminal. that's it, that's the gig.

the string you pass in must be a decoded string, and it has to be free of control characters, non-characters, and surrogates. don't send her your messy unprocessed trauma strings, she will not fold them.

$print_width = print_columns( $string );

🌟 line_fold

Fold a string. like folding a fitted sheet but for text, and actually possible.

this function accepts a decoded string. here's the part where she does some light housekeeping: control characters (excluding vertical spaces), non-characters, and surrogates are removed before the string gets folded. also super important — changes are applied to a copy; the passed string is unchanged. your original stays pristine, no side effects, main character energy only for the copy 🌈

$folded_string = line_fold( $string );

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

✨ Options ✨

  • width — if you don't set it, it defaults to the terminal width. and heads up, width is 1 or greater. no zero, no negatives, we don't do that here.
  • init_tab — sets the initial tab inserted at the beginning of paragraphs. if you give her a value that consists of the pattern /^[0-9]+$/, the tab becomes that number of spaces. otherwise, whatever value you provided is used directly as the tab. by default, no initial tab is inserted. and one lil caveat: if the initial tab ends up longer than half the available width, it gets cut down to half the available width. she trims, she's polite about it 💅
  • subseq_tab — sets the subsequent tab inserted at the beginning of all broken lines (excluding paragraph beginnings). same deal as above: a /^[0-9]+$/ value means that many spaces, anything else is used directly as the tab. by default, no subsequent tab is inserted. and yep, same rule — if the subsequent tab is longer than half the available width, it gets cut to half the available width.
  • truncate_long_tabs — if enabled (and it is enabled by default), init_tab and subseq_tab are truncated if they exceed half of the terminal width. this is the switch that does the trimming described above. iconic behavior, honestly.
  • color — enables support for ANSI SGR escape sequences. if enabled, all zero-width no-break spaces (0xfeff) are removed. and color is 0 or 1 — binary, no in-between, no "kind of", pick a lane bestie.

👑 AUTHOR 👑

Matthäus Kiem <cuer2s@gmail.com> — give them their flowers 💐

Copyright (C) 2025-2026 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 the full deets, go read the licenses in the file LICENSE. no vibes-based licensing here, read the actual text, fr fr 🫶

aaaand that's the whole page, bestie 🦋 this was Term::Choose::LineFold, perl v5.40.1, dated 2026-05-06 — go forth and fold your lines, you've got this 💖✨🎀

📦 where this page comes from