NAME¶

Text::VimColor - syntax color text in HTML or XML using Vim

SYNOPSIS¶

   use Text::VimColor;
   my $syntax = Text::VimColor->new(
      file => $0,
      filetype => 'perl',
   );
   print $syntax->html;
   print $syntax->xml;

DESCRIPTION¶

This module tries to markup text files according to their syntax. It can be used to produce web pages with pretty-printed colourful source code samples. It can produce output in the following formats:

HTML

Valid XHTML 1.0, with the exact colouring 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

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 above in the SYNOPSIS) and then call methods to get the markup out.

METHODS¶

new(options)

Returns a syntax highlighting object. Pass it a hash of options.

The following options are recognised:

vim_let(name => value, ...)

Change the options that are set with the Vim "let" command when Vim is run. See "new()" for details.

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:

   my $syntax = Text::VimColor->new(
      vim_command => '/usr/local/bin/special-vim',
   );
   foreach (@files) {
      print $syntax->syntax_mark_file($_)->html;
   }
    

You can override the filetype set in new() by passing in a "filetype" option, like so:

   $syntax->syntax_mark_file($filename, filetype => 'perl');
    

This option will only affect the syntax colouring for that one call, not for any subsequent ones on the same object.

syntax_mark_string(string, options...)

Does the same as "syntax_mark_file" (see above) but uses a string as input. 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.

html()

Return XHTML markup based on the Vim syntax colouring 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 and XHTML.

The only markup used for the actual text will be "<span>" elements wrapped round 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 the section HIGHLIGHTING TYPES below.

xml()

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 the HIGHLIGHTING TYPES section below.

The "<syntax>" element will declare the namespace for all the elements prodeced, 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.

marked()

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($syntax->marked);
   $VAR1 = [
      [ 'Statement', 'my' ],
      [ '', ' ' ],
      [ 'Identifier', '$syntax' ],
      [ '', ' = ' ],
       ...
   ];
    

The "marked()" 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 the HIGHLIGHTING TYPES section below (or the empty string if none apply), and the second is the actual piece of text.

input_filename()

Returns the filename of the input file, or undef if a filename wasn't specified.

HIGHLIGHTING TYPES¶

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

RELATED MODULES¶

These modules allow Text::VimColor to be used more easily in particular environments:

Apache::VimColor

Kwiki::VimMode

Template-Plugin-VimColor

SEE ALSO¶

text-vimcolor(1)

A simple command line interface to this module's features. It can be used to produce HTML and XML output, and can also generate PDF output using an XSLT/XSL-FO stylesheet and the FOP processor.

http://www.vim.org/

Everything to do with the Vim text editor.

http://ungwe.org/blog/

The author's weblog, which uses this module. It is used to make the code samples look pretty.

BUGS¶

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 bug #11555.
• Things can break if there is already a Vim swapfile, but sometimes it seems to work.
• 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.
• It doesn't work on Windows. I am unlikely to fix this, but if anyone who knows Windows can sort it out let me know.

AUTHOR¶

Geoff Richards <qef@laxan.com>

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

COPYRIGHT¶

Copyright 2002-2006, Geoff Richards.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.