new

  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" and "html_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" and "html_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 stylesheet light.css will be used instead.

html_stylesheet_url

Ignored unless "html_full_page" is enabled and "html_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 a "file://" URL to reference the supplied light.css stylesheet, which is only really useful for testing.

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 prefix "syn:", so an "xmlns: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.

vim_let

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

syntax_mark_file

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

syntax_mark_string

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

ansi

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

html

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

xml

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.

marked

   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.

input_filename

dist_file

  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.

Perldoc

  perldoc Text::VimColor

Websites

•

MetaCPAN

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

<http://metacpan.org/release/Text-VimColor>

Bugs / Feature Requests

Source Code

  git clone https://github.com/rwstauner/Text-VimColor.git