.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FromANSI::Tiny 3"
.TH HTML::FromANSI::Tiny 3 2024-03-08 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
HTML::FromANSI::Tiny \- Easily convert colored command line output to HTML
.SH VERSION
.IX Header "VERSION"
version 0.107
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  use HTML::FromANSI::Tiny;
\&  my $h = HTML::FromANSI::Tiny\->new(
\&    auto_reverse => 1, background => \*(Aqwhite\*(Aq, foreground => \*(Aqblack\*(Aq,
\&  );
\&
\&  # output from some command
\&  my $output = "\ee[31mfoo\e033[1;32mbar\e033[0m";
\&
\&  # include the default styles if you don\*(Aqt want to define your own:
\&  print $h\->style_tag(); # or just $h\->css() to insert into your own stylesheet
\&
\&  print $h\->html($output);
\&  # prints \*(Aq<span class="red">foo</span><span class="bold green">bar</span>\*(Aq
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Convert the output from a terminal command that is decorated
with ANSI escape sequences into customizable HTML
(with a small amount of code).
.PP
This module complements Parse::ANSIColor::Tiny
by providing a simple HTML markup around its output.
.PP
Parse::ANSIColor::Tiny returns a data structure that's easy
to reformat into any desired output.
Reformatting to HTML seemed simple and common enough
to warrant this module as well.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
Constructor.
.PP
Takes a hash or hash ref of options:
.IP \(bu 4
\&\f(CW\*(C`ansi_parser\*(C'\fR \- Instance of Parse::ANSIColor::Tiny; One will be created automatically, but you can provide one if you want to configure it.
.IP \(bu 4
\&\f(CW\*(C`class_prefix\*(C'\fR \- String to prefix class names; Blank by default for brevity. See "html".
.IP \(bu 4
\&\f(CW\*(C`html_encode\*(C'\fR \- Code ref that should encode HTML entities; See "html_encode".
.IP \(bu 4
\&\f(CW\*(C`inline_style\*(C'\fR \- Boolean to toggle using inline \f(CW\*(C`style=""\*(C'\fR attributes instead of \f(CW\*(C`class=""\*(C'\fR attributes.
.IP \(bu 4
\&\f(CW\*(C`no_plain_tags\*(C'\fR \- Boolean for omitting the \f(CW\*(C`tag\*(C'\fR when the text has no style attributes; Defaults to false for consistency.
.IP \(bu 4
\&\f(CW\*(C`selector_prefix\*(C'\fR \- String to prefix each css selector; Blank by default. See "css".
.IP \(bu 4
\&\f(CW\*(C`styles\*(C'\fR \- Tree of hashrefs for customizing style output (for \f(CW\*(C`<style>\*(C'\fR tags or \f(CW\*(C`inline_style\*(C'\fR). See "CUSTOM STYLES".
.IP \(bu 4
\&\f(CW\*(C`tag\*(C'\fR \- Alternate tag in which to wrap the HTML; Defaults to \f(CW\*(C`span\*(C'\fR.
.PP
For convenience and consistency options to "new" in Parse::ANSIColor::Tiny
can be specified directly including
\&\f(CW\*(C`auto_reverse\*(C'\fR, \f(CW\*(C`background\*(C'\fR, \f(CW\*(C`foreground\*(C'\fR,
and \f(CW\*(C`remove_escapes\*(C'\fR.
.SS ansi_parser
.IX Subsection "ansi_parser"
Returns the Parse::ANSIColor::Tiny instance in use.
Creates one if necessary.
.SS attr_to_class
.IX Subsection "attr_to_class"
Takes an ANSI attribute name such as 'red' or 'bold'
and returns the corresponding class name.
.PP
This allows subclasses to override the class names used.
This can be useful for utilizing pre-existing CSS definitions
(such as mapping \f(CW\*(Aqred\*(Aq\fR to \f(CW\*(Aqtext\-danger\*(Aq\fR).
.PP
The default returns the string provided.
.PP
.Vb 1
\&  $hfat\->attr_to_class(\*(Aqred\*(Aq); # default returns \*(Aqred\*(Aq
.Ve
.SS css
.IX Subsection "css"
.Vb 1
\&  my $css = $hfat\->css();
.Ve
.PP
Returns basic CSS code for inclusion into a \f(CW\*(C`<style>\*(C'\fR tag.
You can use this if you don't want to style everything yourself
or if you want something to start with.
.PP
It produces code like this:
.PP
.Vb 2
\&  .bold { font\-weight: bold; }
\&  .red { color: #f33; }
.Ve
.PP
It will include the \f(CW\*(C`class_prefix\*(C'\fR and/or \f(CW\*(C`selector_prefix\*(C'\fR
if you've set either:
.PP
.Vb 2
\&    # with {class_prefix => \*(Aqterm\-\*(Aq}
\&  .term\-bold { font\-weight: bold; }
\&
\&    # with {selector_prefix => \*(Aq#output \*(Aq}
\&  #output .bold { font\-weight: bold; }
\&
\&    # with {selector_prefix => \*(Aq#output \*(Aq, class_prefix => \*(Aqterm\-\*(Aq}
\&  #output .term\-bold { font\-weight: bold; }
.Ve
.PP
Returns a list of styles or a concatenated string depending on context.
.PP
I tried to choose default colors that are close to traditional
terminal colors but also fairly legible on black or white.
.PP
Overwrite style to taste.
.PP
\&\fBNote\fR: There is no default style for \f(CW\*(C`reverse\*(C'\fR
as CSS does not provide a simple mechanism for this.
I suggest you use \f(CW\*(C`auto_reverse\*(C'\fR
and set \f(CW\*(C`background\*(C'\fR and \f(CW\*(C`foreground\*(C'\fR to appropriate colors
if you expect to process \f(CW\*(C`reverse\*(C'\fR sequences.
See "process_reverse" in Parse::ANSIColor::Tiny for more information.
.SS html
.IX Subsection "html"
.Vb 2
\&  my $html = $hfat\->html($text);
\&  my @html_tags = $hfat\->html($text);
.Ve
.PP
Wraps the provided \f(CW$text\fR in HTML
using \f(CW\*(C`tag\*(C'\fR for the HTML tag name
and prefixing each attribute with \f(CW\*(C`class_prefix\*(C'\fR.
For example:
.PP
.Vb 2
\&  # defaults:
\&  qq[<span class="red bold">foo</span>]
\&
\&  # {tag => \*(Aqbar\*(Aq, class_prefix => \*(Aqbaz\-\*(Aq}
\&  qq[<bar class="baz\-red baz\-bold">foo</bar>]
.Ve
.PP
\&\f(CW$text\fR may be a string marked with ANSI escape sequences
or the array ref output of Parse::ANSIColor::Tiny
if you already have that.
.PP
In list context returns a list of HTML tags.
.PP
In scalar context returns a single string of concatenated HTML.
.SS html_encode
.IX Subsection "html_encode"
.Vb 1
\&  my $html = $hfat\->html_encode($text);
.Ve
.PP
Encodes the text with HTML character entities.
so it can be inserted into HTML tags.
.PP
This is used internally by "html" to encode
the contents of each tag.
.PP
By default the \f(CW\*(C`encode_entities\*(C'\fR function of HTML::Entities is used.
.PP
You may provide an alternate subroutine (code ref) to the constructor
as the \f(CW\*(C`html_encode\*(C'\fR parameter in which case that sub will be used instead.
This allows you to set different options
or use the HTML entity encoder provided by your framework:
.PP
.Vb 1
\&  my $hfat = HTML::FromANSI::Tiny\->new(html_encode => sub { $app\->h(shift) });
.Ve
.PP
The code ref provided should take the first argument as the text to process
and return the encoded result.
.SS style_tag
.IX Subsection "style_tag"
Returns the output of "css" wrapped in a \f(CW\*(C`<style>\*(C'\fR tag.
.PP
Returns a list or a concatenated string depending on context.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS html_from_ansi
.IX Subsection "html_from_ansi"
Function wrapped around "html".
.SH EXPORTS
.IX Header "EXPORTS"
Everything listed in "FUNCTIONS" is also available for export upon request.
.SH "CUSTOM STYLES"
.IX Header "CUSTOM STYLES"
To override the styles output in the "style_tag" or "css" methods
(or the attributes when \f(CW\*(C`inline_style\*(C'\fR is used)
pass to the constructor a tree of hashrefs as the \f(CW\*(C`styles\*(C'\fR attribute:
.PP
.Vb 12
\&  styles => {
\&    underline => {
\&      \*(Aqtext\-decoration\*(Aq  => \*(Aqunderline\*(Aq,
\&      \*(Aqtext\-shadow\*(Aq      => \*(Aq0 2px 2px black\*(Aq,
\&    },
\&    red => {
\&      \*(Aqcolor\*(Aq            => \*(Aq#f00\*(Aq
\&    },
\&    on_bright_green => {
\&      \*(Aqbackground\-color\*(Aq => \*(Aq#060\*(Aq,
\&    }
\&  }
.Ve
.PP
Any styles that are not overridden will get the defaults.
.SH "COMPARISON TO HTML::FromANSI"
.IX Header "COMPARISON TO HTML::FromANSI"
HTML::FromANSI is a bit antiquated (as of v2.03 released in 2007).
It uses \f(CW\*(C`font\*(C'\fR tags and the \f(CW\*(C`style\*(C'\fR attribute
and isn't very customizable.
.PP
It uses Term::VT102 which is probably more robust than
Parse::ANSIColor::Tiny but may be overkill for simple situations.
I've also had trouble installing it in the past.
.PP
For many simple situations this module combined with Parse::ANSIColor::Tiny
is likely sufficient and is considerably smaller.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
Parse::ANSIColor::Tiny
.IP \(bu 4
HTML::FromANSI
.SH SUPPORT
.IX Header "SUPPORT"
.SS Perldoc
.IX Subsection "Perldoc"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&  perldoc HTML::FromANSI::Tiny
.Ve
.SS Websites
.IX Subsection "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.
.IP \(bu 4
MetaCPAN
.Sp
A modern, open-source CPAN search engine, useful to view POD in HTML format.
.Sp
<https://metacpan.org/release/HTML\-FromANSI\-Tiny>
.SS "Bugs / Feature Requests"
.IX Subsection "Bugs / Feature Requests"
Please report any bugs or feature requests by email to \f(CW\*(C`bug\-html\-fromansi\-tiny at rt.cpan.org\*(C'\fR, or through
the web interface at <https://rt.cpan.org/Public/Bug/Report.html?Queue=HTML\-FromANSI\-Tiny>. You will be automatically notified of any
progress on the request by the system.
.SS "Source Code"
.IX Subsection "Source Code"
<https://github.com/rwstauner/HTML\-FromANSI\-Tiny>
.PP
.Vb 1
\&  git clone https://github.com/rwstauner/HTML\-FromANSI\-Tiny.git
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Randy Stauner <rwstauner@cpan.org>
.SH CONTRIBUTOR
.IX Header "CONTRIBUTOR"
Stephen Thirlwall <sdt@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011 by Randy Stauner.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.