Text::VimColor - Syntax highlight text using Vim
version 0.29
use Text::VimColor;
my $syntax = Text::VimColor->new(
file => $0,
filetype => 'perl',
);
print $syntax->html;
print $syntax->xml;
print $syntax->ansi;
This module tries to markup text files according to their syntax. It can be used to produce web pages with pretty-printed colorful source code samples. It can produce output in the following formats:
-
HTML
Valid XHTML 1.0, with the exact coloring and style left to a CSS stylesheet
-
XML
Pieces of text are marked with XML elements in a simple vocabulary, which can be converted to other formats, for example, using XSLT
-
Perl array
A simple Perl data structure, so that Perl code can be used to turn it into whatever is needed
-
ANSI Escape Sequences
A string marked with Term::ANSIColor suitable for printing to a terminal.
This module works by running the Vim text editor and getting it to apply its excellent syntax highlighting (aka 'font-locking') to an input file, and mark pieces of text according to whether it thinks they are comments, keywords, strings, etc. The Perl code then reads back this markup and converts it to the desired output format.
This is an object-oriented module. To use it, create an object with the "new" function (as shown in "SYNOPSIS") and then call methods to get the markup out.
my $tvc = Text::VimColor->new(%options)
Returns a syntax highlighting object. Pass it a hash of options.
The following options are recognized:
-
file
The file to syntax highlight. Can be either a filename or an open file handle.
Note that using a filename might allow Vim to guess the file type from its name if none is specified explicitly.
If the file isn't specified while creating the object, it can be given later in a call to the "syntax_mark_file" method (see below), allowing a single
Text::VimColor
object to be used with multiple input files. -
string
Use this to pass a string to be used as the input. This is an alternative to the
file
option. A reference to a string will also work.The "syntax_mark_string" method is another way to use a string as input.
If you provide a character (unencoded) string (recommended) it will be passed to vim encoded in UTF-8 and your result will be character string.
-
filetype
Specify the type of file Vim should expect, in case Vim's automatic detection by filename or contents doesn't get it right. This is particularly important when providing the file as a string or file handle, since Vim won't be able to use the file extension to guess the file type.
The file types recognized by Vim are short strings like 'perl' or 'lisp'. They are the names of files in the 'syntax' directory in the Vim distribution.
This option, whether or not it is passed to "new", can be overridden when calling "syntax_mark_file" and "syntax_mark_string", so you can use the same object to process multiple files of different types.
-
all_syntax_groups
By default, this option is disabled. That means that the highlighting will only use the following syntax groups:
Comment Constant Identifier Statement PreProc Type Special Underlined Ignore Error Todo
This mirrors vim's default behavior of linking more specific syntax groups to the main groups above. However, most syntax files support more specific groups, so if you want to benefit from finer-grained syntax highlighting you can turn on this option. The additional syntax groups are:
Group Linked to by default --------------------------------------- String Constant Character Constant Number Constant Boolean Constant Float Constant Function Identifier Conditional Statement Repeat Statement Label Statement Operator Statement Keyword Statement Exception Statement Include PreProc Define PreProc Macro PreProc PreCondit PreProc StorageClass Type Structure Type Typedef Type Tag Special SpecialChar Special Delimiter Special SpecialComment Special Debug Special
-
html_full_page
By default the "html" output method returns a fragment of HTML, not a full file. To make useful output this must be wrapped in a
<pre>
element and a stylesheet must be included from somewhere. Setting the "html_full_page" option will instead make the "html" method return a complete stand-alone XHTML file.Note that while this is useful for testing, most of the time you'll want to put the syntax highlighted source code in a page with some other content, in which case the default output of the "html" method is more appropriate.
-
html_inline_stylesheet
Turned on by default, but has no effect unless "html_full_page" is also enabled.
This causes the CSS stylesheet defining the colors to be used to render the markup to be be included in the HTML output, in a
<style>
element. Turn it off to instead use a<link>
to reference an external stylesheet (recommended if putting more than one page on the web). -
html_stylesheet
Ignored unless
html_full_page
andhtml_inline_stylesheet
are both enabled.This can be set to a stylesheet to include inline in the HTML output (the actual CSS, not the filename of it).
-
html_stylesheet_file
Ignored unless
html_full_page
andhtml_inline_stylesheet
are both enabled.This can be the filename of a stylesheet to copy into the HTML output, or a file handle to read one from. If neither this nor
html_stylesheet
are given, the supplied stylesheetlight.css
will be used instead. -
html_stylesheet_url
Ignored unless
html_full_page
is enabled andhtml_inline_stylesheet
is disabled.This can be used to supply the URL (relative or absolute) or the stylesheet to be referenced from the HTML
<link>
element in the header. If this isn't given it will default to using afile://
URL to reference the suppliedlight.css
stylesheet, which is only really useful for testing. -
xhtml5
If true (by default it is false), then output XHTML5 instead of XHTML 1.x when
html_full_page
is specified.New in version 0.29 .
-
xml_root_element
By default this is true. If set to a false value, XML output will not be wrapped in a root element called
<syn:syntax>
, but will be otherwise the same. This could allow XML output for several files to be concatenated, but to make it valid XML a root element must be added. Disabling this option will also remove the binding of the namespace prefixsyn:
, so anxmlns:syn
attribute would have to be added elsewhere. -
vim_command
The name of the executable which will be run to invoke Vim. The default is
vim
. -
vim_options
A reference to an array of options to pass to Vim. The default options are:
[qw( -RXZ -i NONE -u NONE -N -n ), "+set nomodeline"]
You can overwrite the default options by setting this. To merely append additional options to the defaults use
extra_vim_options
. -
extra_vim_options
A reference to an array of additional options to pass to Vim. These are appended to the default
vim_options
. -
vim_let
A reference to a hash of options to set in Vim before the syntax file is loaded. Each of these is set using the
let
command to the value specified. No escaping is done on the values, they are executed exactly as specified.Values in this hash override some default options. Use a value of
undef
to prevent a default option from being set at all. The defaults are as follows:( perl_include_pod => 1, # Recognize POD inside Perl code 'b:is_bash' => 1, # Allow Bash syntax in shell scripts )
These settings can be modified later with the
vim_let()
method.
$tvc->vim_let( %variables );
$tvc->vim_let( perl_no_extended_vars => 1 );
Change the options that are set with the Vim let
command when Vim
is run. See "new" for details.
$tvc->syntax_mark_file( $file, %options )
Mark up the specified file. Subsequent calls to the output methods will then
return the markup. It is not necessary to call this if a file
or string
option was passed to "new".
Returns the object it was called on, so an output method can be called on it directly:
foreach (@files) {
print $tvc->syntax_mark_file($_)->html;
}
You can override the file type set in new() by passing in a filetype
option, like so:
$tvc->syntax_mark_file($filename, filetype => 'perl');
This option will only affect the syntax coloring for that one call, not for any subsequent ones on the same object.
$tvc->syntax_mark_string($string, %options)
Does the same as syntax_mark_file
(see above) but uses a string as input.
The string can also be a reference to a string.
Returns the object it was called on. Supports the filetype
option
just as syntax_mark_file
does.
Return the string marked with ANSI escape sequences (using Term::ANSIColor) based on the Vim syntax coloring of the input file.
This is the default format for the included text-vimcolor script
which makes it like a colored version of cat(1)
.
You can alter the color scheme using the TEXT_VIMCOLOR_ANSI
environment variable in the format of "SynGroup=color;"
.
For example:
TEXT_VIMCOLOR_ANSI='Comment=green;Statement = magenta; '
Return XHTML markup based on the Vim syntax coloring of the input file.
Unless the html_full_page
option is set, this will only return a fragment
of HTML, which can then be incorporated into a full page. The fragment
will be valid as either HTML or XHTML.
The only markup used for the actual text will be <span>
elements
wrapped around appropriate pieces of text. Each one will have a class
attribute set to a name which can be tied to a foreground and background
color in a stylesheet. The class names used will have the prefix syn
,
for example synComment
.
For the full list see "HIGHLIGHTING TYPES".
Returns markup in a simple XML vocabulary. Unless the xml_root_element
option is turned off (it's on by default) this will produce a complete XML
document, with all the markup inside a <syntax>
element.
This XML output can be transformed into other formats, either using programs which read it with an XML parser, or using XSLT. See the text-vimcolor(1) program for an example of how XSLT can be used with XSL-FO to turn this into PDF.
The markup will consist of mixed content with elements wrapping pieces of text which Vim recognized as being of a particular type. The names of the elements used are the ones listed in "HIGHLIGHTING TYPES". below.
The <syntax>
element will declare the namespace for all the
elements produced, which will be http://ns.laxan.com/text-vimcolor/1
.
It will also have an attribute called filename
, which will be set to the
value returned by the input_filename
method, if that returns something
other than undef.
The XML namespace is also available as $Text::VimColor::NAMESPACE_ID
.
This output function returns the marked-up text in the format which the module stores it in internally. The data looks like this:
use Data::Dumper;
print Dumper($tvc->marked);
# produces
$VAR1 = [
[ 'Statement', 'my' ],
[ '', ' ' ],
[ 'Identifier', '$syntax' ],
[ '', ' = ' ],
...
];
This method returns a reference to an array. Each item in the array is itself a reference to an array of two items: the first is one of the names listed in "HIGHLIGHTING TYPES" (or an empty string if none apply), and the second is the actual piece of text.
Returns the filename of the input file, or undef if a filename wasn't specified.
my $full_path = Text::VimColor->dist_file($file);
my $xsl = $tvc->dist_file('light.xsl');
Returns the path to the specified file that is part of the Text-VimColor
dist
(for example, mark.vim
or light.css
).
Can be called as an instance method or a class method.
This is a thin wrapper around "dist_file" in File::ShareDir and is mostly for internal use.
The following list gives the names of highlighting types which will be
set for pieces of text. For HTML output, these will appear as CSS class
names, except that they will all have the prefix syn
added. For XML
output, these will be the names of elements which will all be in the
namespace http://ns.laxan.com/text-vimcolor/1
.
Here is the complete list:
- Comment
- Constant
- Identifier
- Statement
- PreProc
- Type
- Special
- Underlined
- Error
- Todo
These modules allow Text::VimColor
to be used more easily in particular
environments:
-
A simple command line interface to this module's features. It can be used to produce HTML and XML output, print to the screen (like a colored
cat(1)
), and can also generate PDF output using an XSLT/XSL-FO stylesheet and the FOP processor. -
Everything to do with the Vim text editor.
Quite a few, actually:
- Apparently this module doesn't always work if run from within a 'gvim' window, although I've been unable to reproduce this so far. CPAN RT #11555.
- There should be a way of getting a DOM object back instead of an XML string.
- It should be possible to choose between HTML and XHTML, and perhaps there should be some control over the DOCTYPE declaration when a complete file is produced.
- With Vim versions earlier than 6.2 there is a 2 second delay each time Vim is run.
- This requires vim version 6 (it has since 2003). There may be workarounds to support version 5 (technically 5.4+). Upgrading vim is a much better idea, but if you need support for older versions please file a ticket (with patches if possible).
- option for 'set number'
- make global vars available through methods
- list available syntaxes? (see IkiWiki::Plugin::syntax::Vim)
You can find documentation for this module with the perldoc command.
perldoc Text::VimColor
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.
-
MetaCPAN
A modern, open-source CPAN search engine, useful to view POD in HTML format.
Please report any bugs or feature requests by email to bug-text-vimcolor at rt.cpan.org
, or through
the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-VimColor. You will be automatically notified of any
progress on the request by the system.
https://github.com/rwstauner/Text-VimColor
git clone https://github.com/rwstauner/Text-VimColor.git
The Vim script mark.vim
is a crufted version of 2html.vim
by
Bram Moolenaar Bram@vim.org and
David Ne\v{c}as (Yeti) yeti@physics.muni.cz.
- Geoff Richards qef@laxan.com
- Randy Stauner rwstauner@cpan.org
- Geoff Richards geoffr@cpan.org
- Hinrik Örn Sigurðsson hinrik.sig@gmail.com
- mattn mattn.jp@gmail.com
- Randy Stauner randy@r4s6.net
- Shlomi Fish shlomif@shlomifish.org
- Vyacheslav Matyukhin mmcleric@yandex-team.ru
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.