.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "Arch::FileHighlighter 3pm"
.TH Arch::FileHighlighter 3pm "2022-06-08" "perl v5.34.0" "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"
Arch::FileHighlighter \- syntax\-highlight file's content using markup
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Arch::FileHighlighter;
\&    my $fh = Arch::FileHighlighter\->new(
\&        [ \*(Aqinternal(pm+c)\*(Aq, \*(Aqnone(txt), \*(Aqenscript\*(Aq, \*(Aqinternal\*(Aq, ]
\&    );
\&
\&    my $html_ref = $fh\->highlight($0);
\&    print $$html_ref;
\&
\&    print ${$fh\->highlight(\*(Aqfile.c\*(Aq, \*(Aq/* some code */\*(Aq)};
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class processes file contents and produces syntax highlighting markup.
This may be used together with css that defines exact text colors and faces.
.PP
The default is to use the builtin \*(L"internal\*(R" processing, that is pretty
poor; only very basic file types and syntax constructions are supported.
It is suggested to configure and use the external \*(L"enscript\*(R" utility.
\&\s-1GNU\s0 enscript understands quite a rich number of file types and produces
a useful syntax highlighting. \*(L"enscript\*(R" filter is used by default if
/usr/bin/enscript is found.
.PP
It is possible to configure different filters (\*(L"none\*(R", \*(L"internal\*(R",
\&\*(L"enscript\*(R") depending on file name extension. In any case the resulting
markup is always unified, i.e. all special characters are HTML-encoded
using \s-1SGML\s0 entities, and the markup that looks like
<spanclass=\*(L"syntax_foo\*(R">bar</span> is used.
.SH "METHODS"
.IX Header "METHODS"
The following methods are available:
.PP
\&\fBnew\fR,
\&\fBinstance\fR,
\&\fBhighlight\fR.
.IP "\fBnew\fR [\fIfilters\fR]" 4
.IX Item "new [filters]"
Create a new instance of Arch::FileHighlighter.
.Sp
\&\fIfilters\fR is arrayref of strings of the form \fIfilter\fR(ext1+ext2+...)",
where \fIfilter\fR is one of \*(L"enscript\*(R", \*(L"internal\*(R" or \*(L"none\*(R". Special
extension \*(L":xml\*(R" is a shortcut for \*(L"html+htm+sgml+xml+wml+rss+glade\*(R".
The filters optionally constrained by file extensions are probed
sequentially and the first passed one is used.
.Sp
Note that if enscript is configured in the sequence, but is not installed,
then its probing may print a warning to stderr. The \*(L"enscript\*(R" filter is
handled a bit specially, it may take parameters \*(L"mono\*(R" (less colors) and
\&\*(L"asis\*(R" instead of the file extensions. If enscript returns html without
any tags, then the filter is handled as failed, unless \*(L"asis\*(R" is given.
.Sp
By default, \fIfilters\fR is [ 'internal' ], or [ 'enscript', 'internal' ]
depending on presense of '/usr/bin/enscript'.
.IP "\fBinstance\fR [\fIfilters\fR]" 4
.IX Item "instance [filters]"
Alternative constructor. Return the last created instance of
Arch::FileHighlighter or create a new one.
.Sp
The purpose of this alternative constructor is to allow the singleton
behaviour as well as certain Aspect Oriented Programming practices.
.IP "\fBhighlight\fR \fIfilename\fR [\fIcontent\fR]" 4
.IX Item "highlight filename [content]"
Process \fIfilename\fR using configured filters (as described in the
constructor) and produce the file content with embeded <span
class="\fIclass\fR">...</span> markup. \fIclass\fR is one of:
.Sp
.Vb 8
\&    syntax_keyword
\&    syntax_builtin
\&    syntax_comment
\&    syntax_special
\&    syntax_funcdef
\&    syntax_vartype
\&    syntax_string
\&    syntax_constant
.Ve
.Sp
If \fIcontent\fR is provided (either string or reference to string), it is
used, otherwise the content of \fIfilename\fR is loaded.
.SH "BUGS"
.IX Header "BUGS"
Awaiting for your reports.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mikhael Goikhman (migo@homemail.com\*(--Perl\-GPL/arch\-perl\*(--devel).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information, see enscript, Arch::Util,
Syntax::Highlight::Perl.