Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Parse::ANSIColor::TinyUser Contributed Perl DocumentaParse::ANSIColor::Tiny(3)

NAME
       Parse::ANSIColor::Tiny -	Determine attributes of	ANSI-Colored string

VERSION
       version 0.601

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 '',
	   '<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';

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.  The array
       refs returned from "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).  Other escape sequences are
       removed by default but you can disable this by passing "remove_escapes
       => 0" to	the constructor.

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

METHODS
   new
       Constructor.

       Takes a hash or hash ref	of arguments:

       o   "auto_reverse" - Automatically invert colors	when "reverse" is
	   present; Disabled by	default.

       o   "background"	- Color	to assume as background; Black by default.
	   Currently used by "process_reverse".

       o   "foreground"	- Color	to assume as foreground; White by default.
	   Currently used by "process_reverse".

       o   "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).

   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").

   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.

       o   Duplicates will be removed

       o   a foreground	color will overwrite any previous foreground color
	   (and	the previous ones will be removed)

       o   same	for background colors

       o   "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 "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.

   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.

SEE ALSO
       o   Term::ANSIColor - For marking up text that will be printed to the
	   terminal

       o   Image::TextMode (and	Image::TextMode::Format::ANSI) - Successor to
	   "Image::ANSI"; Specifically designed	for parsing ANSI art

       o   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).

       o   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.

       o   MetaCPAN

	   A modern, open-source CPAN search engine, useful to view POD	in
	   HTML	format.

	   <http://metacpan.org/release/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
       <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>

CONTRIBUTOR
       Dmitry Fedin <dmitry.fedin@gmail.com>

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.

perl v5.32.0			  2017-09-06	     Parse::ANSIColor::Tiny(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | FUNCTIONS | EXPORTS | SEE ALSO | SUPPORT | AUTHOR | CONTRIBUTOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Parse::ANSIColor::Tiny&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help