# NAME
Parse::ANSIColor::Tiny - Determine attributes of ANSI-Colored string
# VERSION
version 0.400
# SYNOPSIS
# 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 '',
'
',
(map { '' . h($_->[1]) . '' } @$marked),
'
';
is $html,
'foobar
',
'turned simple ansi into html';
# DESCRIPTION
Parse a string colored with ANSI escape sequences
into a structure suitable for reformatting (into HTML, for example).
The output of terminal commands can be marked up with colors and formatting
that in some instances you'd like to preserve.
This module is essentially the inverse of [Term::ANSIColor](http://search.cpan.org/perldoc?Term::ANSIColor).
The array refs returned from ["parse"](#parse)
can be passed back in to `Term::ANSIColor::colored`.
The strings may not match exactly due to different ways the attributes can be specified,
but the end result should be colored the same.
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](http://search.cpan.org/perldoc?Term::ANSIColor)).
If you do find bugs please submit tickets (with patches, if possible).
# METHODS
## new
Constructor.
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"](#process_reverse).
- `foreground` - Color to assume as foreground; White by default. Currently used by ["process_reverse"](#process_reverse).
## colors
Returns a list of the base color names (in numeric escape sequence order).
## foreground_colors
Returns a list of the foreground colors (in numeric escape sequence order).
This includes the base colors and the `bright_` variants.
## 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.
## 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](http://search.cpan.org/perldoc?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"](#identify))
and reduces the list to only those that would have effect.
- 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](http://search.cpan.org/perldoc?Term::ANSIColor):
Term::ANSIColor::colored( ['red'], 'colored words' );
## process
Performs post-processing on the provided attributes.
This currently includes ["process_reverse"](#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 `reverse`s do not cancel each other,
but rather the second should be ignored.
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.
# FUNCTIONS
## identify_ansicolor
Function wrapped around ["identify"](#identify).
## normalize_ansicolor
Function wrapped around ["normalize"](#normalize).
## parse_ansicolor
Function wrapped around ["parse"](#parse).
# EXPORTS
Everything listed in ["FUNCTIONS"](#FUNCTIONS) is also available for export upon request.
# SEE ALSO
- [Term::ANSIColor](http://search.cpan.org/perldoc?Term::ANSIColor) - For marking up text that will be printed to the terminal
- [Image::TextMode](http://search.cpan.org/perldoc?Image::TextMode) (and [Image::TextMode::Format::ANSI](http://search.cpan.org/perldoc?Image::TextMode::Format::ANSI)) - Successor to [Image::ANSI](http://search.cpan.org/perldoc?Image::ANSI); Specifically designed for parsing ANSI art
- [Term::VT102](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?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.
- Search CPAN
The default CPAN search engine, useful to view POD in HTML format.
[http://search.cpan.org/dist/Parse-ANSIColor-Tiny](http://search.cpan.org/dist/Parse-ANSIColor-Tiny)
- RT: CPAN's Bug Tracker
The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
[http://rt.cpan.org/NoAuth/Bugs.html?Dist=Parse-ANSIColor-Tiny](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Parse-ANSIColor-Tiny)
- CPAN Ratings
The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
[http://cpanratings.perl.org/d/Parse-ANSIColor-Tiny](http://cpanratings.perl.org/d/Parse-ANSIColor-Tiny)
- CPAN Testers
The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
[http://www.cpantesters.org/distro/P/Parse-ANSIColor-Tiny](http://www.cpantesters.org/distro/P/Parse-ANSIColor-Tiny)
- CPAN Testers Matrix
The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
[http://matrix.cpantesters.org/?dist=Parse-ANSIColor-Tiny](http://matrix.cpantesters.org/?dist=Parse-ANSIColor-Tiny)
- CPAN Testers Dependencies
The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
[http://deps.cpantesters.org/?module=Parse::ANSIColor::Tiny](http://deps.cpantesters.org/?module=Parse::ANSIColor::Tiny)
## 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 [http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-ANSIColor-Tiny](http://rt.cpan.org/NoAuth/ReportBug.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](https://github.com/rwstauner/Parse-ANSIColor-Tiny)
git clone https://github.com/rwstauner/Parse-ANSIColor-Tiny.git
# AUTHOR
Randy Stauner
# COPYRIGHT AND LICENSE
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.