Parse::...r::Tiny(3)

📦 version 0.700, in opensuse-leap 16.0

okay bestie, welcome to the Parse::ANSIColor::Tiny(3) page — yes, the manual name is doing a little truncated-header moment, but the real one is right here. 💖

🎀 NAME 🎀

Parse::ANSIColor::Tiny — Determine attributes of ANSI-Colored string. That’s the whole name section, bestie: it tells you exactly what this little icon does. 🦋

✨ VERSION ✨

version 0.700 — yes, that’s the version, no cap. 💅

🌸 SYNOPSIS 🌸

Picture this: you got output from some command, and it’s all colorful. Here’s the vibe in code:

# output from some command
my $output = "foo\e[31mbar\e[00m";

my $ansi = Parse::ANSIColor::Tiny->new();
my $marked = $ansi->parse($output);

is_deeply
  $marked,
  [
    [ [], 'foo' ],
    [ ['red'], 'bar' ],
  ],
  'parse colored string';

# don't forget to html-encode the string!
my $html = join '',
  '<div>',
  (map { '<span class="' . join(' ', @{ $_->[0] }) . '">' . h($_->[1]) . '</span>' } @$marked),
  '</div>';

is $html,
  '<div><span class="">foo</span><span class="red">bar</span></div>',
  'turned simple ansi into html';

So yeah: new() builds the parser, parse() hands you back the marked-up chunks, and the HTML bit is your reminder to h()-encode the string before stuffing it into markup. Don’t skip the html-encode step, bestie! 😭

💖 DESCRIPTION 💖

Okay so the whole point: this module takes a string colored with ANSI escape sequences and parses it into a structure that’s suitable for reformatting — into HTML, for example. Terminal commands can spit out output marked up with colors and formatting, and in some instances you’d like to preserve that. That’s the moment this module serves. ✨

The tea: it’s essentially the inverse of Term::ANSIColor. The array refs that come back from parse can be passed right back in to Term::ANSIColor::colored. The strings may not match exactly, because there are different ways the attributes can be specified, but the end result should be colored the same. iykyk.

This is a ::Tiny module... it attempts to be correct for most cases with a small amount of code. It may not be 100% correct, especially in complex cases. It only handles the m escape sequence ("\033[0m") which produces colors and simple attributes (bold, underline) (like what can be produced with Term::ANSIColor). Other escape sequences are removed by default, but you can disable this by passing remove_escapes => 0 to the constructor. Important caveat, bestie!

If you do find bugs please submit tickets (with patches, if possible). 🫶

🧚 METHODS 🧚

new

Constructor. It takes a hash or hash ref of arguments: 💅

  • auto_reverse — Automatically invert colors when reverse is present; Disabled by default.
  • background — Color to assume as background; Black by default. Currently used by process_reverse.
  • foreground — Color to assume as foreground; White by default. Currently used by process_reverse.
  • remove_escapes — Remove other terminal escape sequences (not related to color). Passes strings through remove_escape_sequences before parsing.

colors

Returns a list of the base color names (in numeric escape sequence order). That’s it, that’s the method. 🌈

foreground_colors

Returns a list of the foreground colors (in numeric escape sequence order).

This includes the base colors, their bright_ variants, and the names from the 256 palette (prefixes of ansi, rgb, and grey). so many colors, so little time.

background_colors

Returns a list of the background colors (in numeric escape sequence order).

This includes the on_ and on_bright_ variants of the base colors and the on_ names for the 256 palette.

identify

my @names = $parser->identify('1;31');
  # or $parser->identify('1', '31');
# returns ('bold', 'red')

Identifies attributes by their number; Returns a list of names.

This is similar to uncolor() in Term::ANSIColor.

Unknown codes will be ignored (remove from the output):

$parser->identify('33', '52');
# returns ('yellow') # drops the '52'

normalize

my @norm = $parser->normalize(@attributes);

Takes a list of named attributes (like those returned from identify) and reduces the list to only those that would have effect. Here are the rules:

  • Duplicates will be removed
  • a foreground color will overwrite any previous foreground color (and the previous ones will be removed)
  • same for background colors
  • clear will remove all previous attributes
my @norm = $parser->normalize(qw(red bold green));
# returns ('bold', 'green');

parse

my $marked = $parser->parse($output);

Parse the provided string and return an array ref of array refs describing the formatting:

# [
#   [ [], 'plain words' ],
#   [ ['red'], 'colored words' ],
# [

These array refs are consistent with the arguments to colored() in Term::ANSIColor:

Term::ANSIColor::colored( ['red'], 'colored words' );

process

Performs post-processing on the provided attributes.

This currently includes process_reverse if auto_reverse is enabled. 💫

process_reverse

my @attr = $parser->process_reverse( $parser->normalize( '31;42;7' ) );

Translates a normalized set of attributes into something easier to process. This is called internally when auto_reverse is configured.

If reverse is included in the attributes it should invert the foreground and background colors.

This method makes the attributes more straight forward and likely easier for other things to process:

my @norm = $parser->normalize( '1;31;42;7' );
# returns qw( bold red on_green reverse );

my @attr = $parser->process_reverse( @norm );
# returns qw( bold on_red green );

This extra step is necessary to maintain state and properly handle reverse/reverse_off since two reverses do not cancel each other, but rather the second should be ignored. Important!

If no foreground or background color is currently active then the colors specified as foreground and background will be included (and reversed).

my @attr = $parser->process_reverse( qw( bold reverse ) );
# returns qw( bold on_white black );

my @attr = $parser->process_reverse( qw( bold reverse red ) );
# returns qw( bold on_red   black );

This is consistent with the way it is drawn in the terminal. Explicitly specifying both colors should make it easy for anything downstream to process and display as intended.

remove_escape_sequences

my $clean = $parser->remove_escape_sequences( $string );

Strip other terminal escape sequences (those not relating to color) from the string to avoid unexpected characters in the output. This method is called from parse if remove_escapes is enabled.

🔥 FUNCTIONS 🔥

  • identify_ansicolor — Function wrapped around identify.
  • normalize_ansicolor — Function wrapped around normalize.
  • parse_ansicolor — Function wrapped around parse.

💅 EXPORTS 💅

Everything listed in FUNCTIONS is also available for export upon request. periodt.

🦋 SEE ALSO 🦋

  • Term::ANSIColor — For marking up text that will be printed to the terminal
  • Image::TextMode (and Image::TextMode::Format::ANSI) — Successor to Image::ANSI; Specifically designed for parsing ANSI art
  • Term::VT102 — Handles more than colors and is likely more robust but may be overkill in simple situations (and was difficult to install in the past).
  • HTML::FromANSI::Tiny — Uses this module to translate ANSI colored text to simple HTML

🌈 SUPPORT 🌈

Perldoc

You can find documentation for this module with the perldoc command.

perldoc Parse::ANSIColor::Tiny

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-parse-ansicolor-tiny at rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Parse-ANSIColor-Tiny. You will be automatically notified of any progress on the request by the system. 🫶

Source Code

https://github.com/rwstauner/Parse-ANSIColor-Tiny
git clone https://github.com/rwstauner/Parse-ANSIColor-Tiny.git

👑 AUTHOR 👑

Randy Stauner <rwstauner@cpan.org>

💜 CONTRIBUTORS 💜

  • Dmitry Fedin <dmitry.fedin@gmail.com>
  • Randy Stauner <randy@r4s6.net>

This software is copyright (c) 2011 by Randy Stauner.

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

okay bestie, that’s the whole page 💖 this footer was perl v5.42.0, dated 2022-10-23, from the Parse::...r::Tiny(3) footer — signing off with a little sparkle ✨💅

📦 where this page comes from