NAME

Text::ANSI::Printf - printf function to print string including ANSI sequence

VERSION

Version 2.06

SYNOPSIS

use Text::ANSI::Printf;
Text::ANSI::Printf::printf FORMAT, LIST
Text::ANSI::Printf::sprintf FORMAT, LIST

use Text::ANSI::Printf qw(ansi_printf ansi_sprintf);
ansi_printf FORMAT, LIST
ansi_sprintf FORMAT, LIST

$ ansiprintf format args ...

DESCRIPTION

Text::ANSI::Printf is a almost-printf-compatible library with a capability of handling:

- ANSI terminal sequences
- Multi-byte wide characters
- Combining characters
- Backspaces

You can give any string including these data as an argument for printf and sprintf functions. Each field width is calculated based on its visible appearance.

For example,

printf "| %-5s | %-5s | %-5s |\n", "Red", "Green", "Blue";

this code produces the output like:

| Red   | Green | Blue  |

However, if the arguments are colored by ANSI sequence,

printf("| %-5s | %-5s | %-5s |\n",
       "\e[31mRed\e[m", "\e[32mGreen\e[m", "\e[34mBlue\e[m");

this code produces undesirable result:

| Red | Green | Blue |

This is still better because it is readable, but if the result is shorter than the original string, for example, "%.3s", the result will be disastrous.

ansi_printf can be used to properly format colored text.

use Text::ANSI::Printf 'ansi_printf';
ansi_printf("| %-5s | %-5s | %-5s |\n",
       "\e[31mRed\e[m", "\e[32mGreen\e[m", "\e[34mBlue\e[m");

It does not matter if the result is shorter than the original text. Next code produces [R] [G] [B] in proper color.

ansi_printf("[%.1s] [%.1s] [%.1s]\n",
       "\e[31mRed\e[m", "\e[32mGreen\e[m", "\e[34mBlue\e[m");

ARGUMENT REORDERING

The original printf function has the ability to specify the arguments to be targeted by the position specifier, but by default this module assumes that the arguments will appear in the given order, so you will not get the expected result. If you wish to use it, set the package variable $REORDER to 1.

$Text::ANSI::Printf::REORDER = 1;

By doing so, the order in which arguments appear can be changed and the same argument can be processed even if it appears more than once.

If you want to enable this feature only in specific cases, create a wrapper function and declare $Text::ANSI::Printf::REORDER as local in it.

This behavior is experimental and may change in the future.

FUNCTIONS

• printf FORMAT, LIST

• sprintf FORMAT, LIST

• ansi_printf FORMAT, LIST

• ansi_sprintf FORMAT, LIST

  Use just like Perl's printf and sprintf functions except that printf does not take FILEHANDLE.

IMPLEMENTATION NOTES

This module uses Text::Conceal and Text::ANSI::Fold::Util internally.

CLI TOOLS

This package contains the ansiprintf(1) command as a wrapper for this module. By using this command from the command line interface, you can check the functionality of Text::ANSI::Printf. See ansiprintf(1) or `perldoc ansiprintf`.

SEE ALSO

App::ansiprintf

Term::ANSIColor::Concise, https://github.com/tecolicom/Term-ANSIColor-Concise

Text::Conceal, https://github.com/tecolicom/Text-Conceal

Text::ANSI::Fold::Util, https://github.com/tecolicom/Text-ANSI-Fold-Util

Text::ANSI::Printf, https://github.com/tecolicom/Text-ANSI-Printf

App::ansicolumn, https://github.com/tecolicom/App-ansicolumn

App::ansiecho, https://github.com/tecolicom/App-ansiecho

https://en.wikipedia.org/wiki/ANSI_escape_code

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2020-2023 Kazumasa Utashiro.

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