Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text::VimColor(3)     User Contributed Perl Documentation    Text::VimColor(3)

NAME
       Text::VimColor -	Syntax highlight text using Vim

VERSION
       version 0.26

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

	  print	$syntax->html;
	  print	$syntax->xml;
	  print	$syntax->ansi;

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

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

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

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

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

   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.

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:

       o   Comment

       o   Constant

       o   Identifier

       o   Statement

       o   PreProc

       o   Type

       o   Special

       o   Underlined

       o   Error

       o   Todo

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

       o   Apache::VimColor

       o   Kwiki::VimMode

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

       http://www.vim.org/
	   Everything to do with the Vim text editor.

BUGS
       Quite a few, actually:

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

       o   There should	be a way of getting a DOM object back instead of an
	   XML string.

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

       o   With	Vim versions earlier than 6.2 there is a 2 second delay	each
	   time	Vim is run.

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

TODO
       o   option for 'set number'

       o   make	global vars available through methods

       o   list	available syntaxes? (see IkiWiki::Plugin::syntax::Vim)

SUPPORT
   Perldoc
       You can find documentation for this module with the perldoc command.

	 perldoc Text::VimColor

   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.

       o   MetaCPAN

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

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

   Bugs	/ Feature Requests
       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.

   Source Code
       <https://github.com/rwstauner/Text-VimColor>

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

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

AUTHORS
       o   Geoff Richards <qef@laxan.com>

       o   Randy Stauner <rwstauner@cpan.org>

CONTRIBUTORS
       o   Geoff Richards <geoffr@cpan.org>

       o   Hinrik Arn SigurA<degree>sson <hinrik.sig@gmail.com>

       o   Vyacheslav Matyukhin	<mmcleric@yandex-team.ru>

       o   mattn <mattn.jp@gmail.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2002-2006	by Geoff Richards.

       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.

perl v5.32.0			  2015-03-21		     Text::VimColor(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | HIGHLIGHTING TYPES | RELATED MODULES | SEE ALSO | BUGS | TODO | SUPPORT | ACKNOWLEDGEMENTS | AUTHORS | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::VimColor&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help