1Text::VimColor(3) User Contributed Perl Documentation Text::VimColor(3)
2
6 Text::VimColor - Syntax highlight text using Vim
7
9 version 0.28
10
12 use Text::VimColor;
13 my $syntax = Text::VimColor->new(
14 file => $0,
15 filetype => 'perl',
16 );
17 print $syntax->html;
19 print $syntax->xml;
20 print $syntax->ansi;
21
23 This module tries to markup text files according to their syntax. It
24 can be used to produce web pages with pretty-printed colorful source
25 code samples. It can produce output in the following formats:
26 HTML
28 Valid XHTML 1.0, with the exact coloring and style left to a CSS
29 stylesheet
30 XML Pieces of text are marked with XML elements in a simple vocabulary,
32 which can be converted to other formats, for example, using XSLT
33 Perl array
35 A simple Perl data structure, so that Perl code can be used to turn
36 it into whatever is needed
37 ANSI Escape Sequences
39 A string marked with Term::ANSIColor suitable for printing to a
40 terminal.
41 This module works by running the Vim text editor and getting it to
43 apply its excellent syntax highlighting (aka 'font-locking') to an
44 input file, and mark pieces of text according to whether it thinks they
45 are comments, keywords, strings, etc. The Perl code then reads back
46 this markup and converts it to the desired output format.
47 This is an object-oriented module. To use it, create an object with
49 the "new" function (as shown in "SYNOPSIS") and then call methods to
50 get the markup out.
51
53 new
54 my $tvc = Text::VimColor->new(%options)
55 Returns a syntax highlighting object. Pass it a hash of options.
57 The following options are recognized:
59 file
61 The file to syntax highlight. Can be either a filename or an open
62 file handle.
63 Note that using a filename might allow Vim to guess the file type
65 from its name if none is specified explicitly.
66 If the file isn't specified while creating the object, it can be
68 given later in a call to the "syntax_mark_file" method (see below),
69 allowing a single "Text::VimColor" object to be used with multiple
70 input files.
71 string
73 Use this to pass a string to be used as the input. This is an
74 alternative to the "file" option. A reference to a string will
75 also work.
76 The "syntax_mark_string" method is another way to use a string as
78 input.
79 If you provide a character (unencoded) string (recommended) it will
81 be passed to vim encoded in UTF-8 and your result will be character
82 string.
83 filetype
85 Specify the type of file Vim should expect, in case Vim's automatic
86 detection by filename or contents doesn't get it right. This is
87 particularly important when providing the file as a string or file
88 handle, since Vim won't be able to use the file extension to guess
89 the file type.
90 The file types recognized by Vim are short strings like 'perl' or
92 'lisp'. They are the names of files in the 'syntax' directory in
93 the Vim distribution.
94 This option, whether or not it is passed to "new", can be
96 overridden when calling "syntax_mark_file" and
97 "syntax_mark_string", so you can use the same object to process
98 multiple files of different types.
99 all_syntax_groups
101 By default, this option is disabled. That means that the
102 highlighting will only use the following syntax groups:
103 Comment
105 Constant
106 Identifier
107 Statement
108 PreProc
109 Type
110 Special
111 Underlined
112 Ignore
113 Error
114 Todo
115 This mirrors vim's default behavior of linking more specific syntax
117 groups to the main groups above. However, most syntax files support
118 more specific groups, so if you want to benefit from finer-grained
119 syntax highlighting you can turn on this option. The additional
120 syntax groups are:
121 Group Linked to by default
123 ---------------------------------------
124 String Constant
125 Character Constant
126 Number Constant
127 Boolean Constant
128 Float Constant
129 Function Identifier
130 Conditional Statement
131 Repeat Statement
132 Label Statement
133 Operator Statement
134 Keyword Statement
135 Exception Statement
136 Include PreProc
137 Define PreProc
138 Macro PreProc
139 PreCondit PreProc
140 StorageClass Type
141 Structure Type
142 Typedef Type
143 Tag Special
144 SpecialChar Special
145 Delimiter Special
146 SpecialComment Special
147 Debug Special
148 html_full_page
150 By default the "html" output method returns a fragment of HTML, not
151 a full file. To make useful output this must be wrapped in a
152 "<pre>" element and a stylesheet must be included from somewhere.
153 Setting the "html_full_page" option will instead make the "html"
154 method return a complete stand-alone XHTML file.
155 Note that while this is useful for testing, most of the time you'll
157 want to put the syntax highlighted source code in a page with some
158 other content, in which case the default output of the "html"
159 method is more appropriate.
160 html_inline_stylesheet
162 Turned on by default, but has no effect unless "html_full_page" is
163 also enabled.
164 This causes the CSS stylesheet defining the colors to be used to
166 render the markup to be be included in the HTML output, in a
167 "<style>" element. Turn it off to instead use a "<link>" to
168 reference an external stylesheet (recommended if putting more than
169 one page on the web).
170 html_stylesheet
172 Ignored unless "html_full_page" and "html_inline_stylesheet" are
173 both enabled.
174 This can be set to a stylesheet to include inline in the HTML
176 output (the actual CSS, not the filename of it).
177 html_stylesheet_file
179 Ignored unless "html_full_page" and "html_inline_stylesheet" are
180 both enabled.
181 This can be the filename of a stylesheet to copy into the HTML
183 output, or a file handle to read one from. If neither this nor
184 "html_stylesheet" are given, the supplied stylesheet light.css will
185 be used instead.
186 html_stylesheet_url
188 Ignored unless "html_full_page" is enabled and
189 "html_inline_stylesheet" is disabled.
190 This can be used to supply the URL (relative or absolute) or the
192 stylesheet to be referenced from the HTML "<link>" element in the
193 header. If this isn't given it will default to using a "file://"
194 URL to reference the supplied light.css stylesheet, which is only
195 really useful for testing.
196 xml_root_element
198 By default this is true. If set to a false value, XML output will
199 not be wrapped in a root element called "<syn:syntax>", but will be
200 otherwise the same. This could allow XML output for several files
201 to be concatenated, but to make it valid XML a root element must be
202 added. Disabling this option will also remove the binding of the
203 namespace prefix "syn:", so an "xmlns:syn" attribute would have to
204 be added elsewhere.
205 vim_command
207 The name of the executable which will be run to invoke Vim. The
208 default is "vim".
209 vim_options
211 A reference to an array of options to pass to Vim. The default
212 options are:
213 [qw( -RXZ -i NONE -u NONE -N -n ), "+set nomodeline"]
215 You can overwrite the default options by setting this. To merely
217 append additional options to the defaults use "extra_vim_options".
218 extra_vim_options
220 A reference to an array of additional options to pass to Vim.
221 These are appended to the default "vim_options".
222 vim_let
224 A reference to a hash of options to set in Vim before the syntax
225 file is loaded. Each of these is set using the "let" command to
226 the value specified. No escaping is done on the values, they are
227 executed exactly as specified.
228 Values in this hash override some default options. Use a value of
230 "undef" to prevent a default option from being set at all. The
231 defaults are as follows:
232 (
234 perl_include_pod => 1, # Recognize POD inside Perl code
235 'b:is_bash' => 1, # Allow Bash syntax in shell scripts
236 )
237 These settings can be modified later with the "vim_let()" method.
239 vim_let
241 $tvc->vim_let( %variables );
242 $tvc->vim_let( perl_no_extended_vars => 1 );
243 Change the options that are set with the Vim "let" command when Vim is
245 run. See "new" for details.
246 syntax_mark_file
248 $tvc->syntax_mark_file( $file, %options )
249 Mark up the specified file. Subsequent calls to the output methods
251 will then return the markup. It is not necessary to call this if a
252 "file" or "string" option was passed to "new".
253 Returns the object it was called on, so an output method can be called
255 on it directly:
256 foreach (@files) {
258 print $tvc->syntax_mark_file($_)->html;
259 }
260 You can override the file type set in new() by passing in a "filetype"
262 option, like so:
263 $tvc->syntax_mark_file($filename, filetype => 'perl');
265 This option will only affect the syntax coloring for that one call, not
267 for any subsequent ones on the same object.
268 syntax_mark_string
270 $tvc->syntax_mark_string($string, %options)
271 Does the same as "syntax_mark_file" (see above) but uses a string as
273 input. The string can also be a reference to a string.
274 Returns the object it was called on. Supports the "filetype" option
276 just as "syntax_mark_file" does.
277 ansi
279 Return the string marked with ANSI escape sequences (using
280 Term::ANSIColor) based on the Vim syntax coloring of the input file.
281 This is the default format for the included text-vimcolor script which
283 makes it like a colored version of cat(1).
284 You can alter the color scheme using the "TEXT_VIMCOLOR_ANSI"
286 environment variable in the format of "SynGroup=color;". For example:
287 TEXT_VIMCOLOR_ANSI='Comment=green;Statement = magenta; '
289 html
291 Return XHTML markup based on the Vim syntax coloring of the input file.
292 Unless the "html_full_page" option is set, this will only return a
294 fragment of HTML, which can then be incorporated into a full page. The
295 fragment will be valid as either HTML or XHTML.
296 The only markup used for the actual text will be "<span>" elements
298 wrapped around appropriate pieces of text. Each one will have a
299 "class" attribute set to a name which can be tied to a foreground and
300 background color in a stylesheet. The class names used will have the
301 prefix "syn", for example "synComment". For the full list see
302 "HIGHLIGHTING TYPES".
303 xml
305 Returns markup in a simple XML vocabulary. Unless the
306 "xml_root_element" option is turned off (it's on by default) this will
307 produce a complete XML document, with all the markup inside a
308 "<syntax>" element.
309 This XML output can be transformed into other formats, either using
311 programs which read it with an XML parser, or using XSLT. See the
312 text-vimcolor(1) program for an example of how XSLT can be used with
313 XSL-FO to turn this into PDF.
314 The markup will consist of mixed content with elements wrapping pieces
316 of text which Vim recognized as being of a particular type. The names
317 of the elements used are the ones listed in "HIGHLIGHTING TYPES".
318 below.
319 The "<syntax>" element will declare the namespace for all the elements
321 produced, which will be "http://ns.laxan.com/text-vimcolor/1". It will
322 also have an attribute called "filename", which will be set to the
323 value returned by the "input_filename" method, if that returns
324 something other than undef.
325 The XML namespace is also available as $Text::VimColor::NAMESPACE_ID.
327 marked
329 This output function returns the marked-up text in the format which the
330 module stores it in internally. The data looks like this:
331 use Data::Dumper;
333 print Dumper($tvc->marked);
334 # produces
336 $VAR1 = [
337 [ 'Statement', 'my' ],
338 [ '', ' ' ],
339 [ 'Identifier', '$syntax' ],
340 [ '', ' = ' ],
341 ...
342 ];
343 This method returns a reference to an array. Each item in the array is
345 itself a reference to an array of two items: the first is one of the
346 names listed in "HIGHLIGHTING TYPES" (or an empty string if none
347 apply), and the second is the actual piece of text.
348 input_filename
350 Returns the filename of the input file, or undef if a filename wasn't
351 specified.
352 dist_file
354 my $full_path = Text::VimColor->dist_file($file);
355 my $xsl = $tvc->dist_file('light.xsl');
356 Returns the path to the specified file that is part of the
358 "Text-VimColor" dist (for example, mark.vim or light.css).
359 Can be called as an instance method or a class method.
361 This is a thin wrapper around "dist_file" in File::ShareDir and is
363 mostly for internal use.
364
366 The following list gives the names of highlighting types which will be
367 set for pieces of text. For HTML output, these will appear as CSS
368 class names, except that they will all have the prefix "syn" added.
369 For XML output, these will be the names of elements which will all be
370 in the namespace "http://ns.laxan.com/text-vimcolor/1".
371 Here is the complete list:
373 · Comment
375 · Constant
377 · Identifier
379 · Statement
381 · PreProc
383 · Type
385 · Special
387 · Underlined
389 · Error
391 · Todo
393
395 These modules allow "Text::VimColor" to be used more easily in
396 particular environments:
397 · Apache::VimColor
399 · Kwiki::VimMode
401 · Template-Plugin-VimColor
403
405 text-vimcolor(1)
406 A simple command line interface to this module's features. It can
407 be used to produce HTML and XML output, print to the screen (like a
408 colored cat(1)), and can also generate PDF output using an
409 XSLT/XSL-FO stylesheet and the FOP processor.
410 http://www.vim.org/
412 Everything to do with the Vim text editor.
413
415 Quite a few, actually:
416 · Apparently this module doesn't always work if run from within a
418 'gvim' window, although I've been unable to reproduce this so far.
419 CPAN RT #11555.
420 · There should be a way of getting a DOM object back instead of an
422 XML string.
423 · It should be possible to choose between HTML and XHTML, and perhaps
425 there should be some control over the DOCTYPE declaration when a
426 complete file is produced.
427 · With Vim versions earlier than 6.2 there is a 2 second delay each
429 time Vim is run.
430 · This requires vim version 6 (it has since 2003). There may be
432 workarounds to support version 5 (technically 5.4+). Upgrading vim
433 is a much better idea, but if you need support for older versions
434 please file a ticket (with patches if possible).
435
437 · option for 'set number'
438 · make global vars available through methods
440 · list available syntaxes? (see IkiWiki::Plugin::syntax::Vim)
442
444 Perldoc
445 You can find documentation for this module with the perldoc command.
446 perldoc Text::VimColor
448 Websites
450 The following websites have more information about this module, and may
451 be of help to you. As always, in addition to those websites please use
452 your favorite search engine to discover more resources.
453 · MetaCPAN
455 A modern, open-source CPAN search engine, useful to view POD in
457 HTML format.
458 <http://metacpan.org/release/Text-VimColor>
460 Bugs / Feature Requests
462 Please report any bugs or feature requests by email to
463 "bug-text-vimcolor at rt.cpan.org", or through the web interface at
464 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-VimColor>. You
465 will be automatically notified of any progress on the request by the
466 system.
467 Source Code
469 <https://github.com/rwstauner/Text-VimColor>
470 git clone https://github.com/rwstauner/Text-VimColor.git
472
474 The Vim script mark.vim is a crufted version of 2html.vim by Bram
475 Moolenaar <Bram@vim.org> and David Ne\v{c}as (Yeti)
476 <yeti@physics.muni.cz>.
477
479 · Geoff Richards <qef@laxan.com>
480 · Randy Stauner <rwstauner@cpan.org>
482
484 · Geoff Richards <geoffr@cpan.org>
485 · Hinrik Örn Sigurðsson <hinrik.sig@gmail.com>
487 · mattn <mattn.jp@gmail.com>
489 · Vyacheslav Matyukhin <mmcleric@yandex-team.ru>
491
493 This software is copyright (c) 2002-2006 by Geoff Richards.
494 This software is copyright (c) 2011 by Randy Stauner.
496 This is free software; you can redistribute it and/or modify it under
498 the same terms as the Perl 5 programming language system itself.
499perl v5.28.0 2017-08-07 Text::VimColor(3)