1Text::VimColor(3) User Contributed Perl Documentation Text::VimColor(3)
2
6 Text::VimColor - Syntax highlight text using Vim
7
9 version 0.29
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 xhtml5
198 If true (by default it is false), then output XHTML5 instead of
199 XHTML 1.x when "html_full_page" is specified.
200 New in version 0.29 .
202 xml_root_element
204 By default this is true. If set to a false value, XML output will
205 not be wrapped in a root element called "<syn:syntax>", but will be
206 otherwise the same. This could allow XML output for several files
207 to be concatenated, but to make it valid XML a root element must be
208 added. Disabling this option will also remove the binding of the
209 namespace prefix "syn:", so an "xmlns:syn" attribute would have to
210 be added elsewhere.
211 vim_command
213 The name of the executable which will be run to invoke Vim. The
214 default is "vim".
215 vim_options
217 A reference to an array of options to pass to Vim. The default
218 options are:
219 [qw( -RXZ -i NONE -u NONE -N -n ), "+set nomodeline"]
221 You can overwrite the default options by setting this. To merely
223 append additional options to the defaults use "extra_vim_options".
224 extra_vim_options
226 A reference to an array of additional options to pass to Vim.
227 These are appended to the default "vim_options".
228 vim_let
230 A reference to a hash of options to set in Vim before the syntax
231 file is loaded. Each of these is set using the "let" command to
232 the value specified. No escaping is done on the values, they are
233 executed exactly as specified.
234 Values in this hash override some default options. Use a value of
236 "undef" to prevent a default option from being set at all. The
237 defaults are as follows:
238 (
240 perl_include_pod => 1, # Recognize POD inside Perl code
241 'b:is_bash' => 1, # Allow Bash syntax in shell scripts
242 )
243 These settings can be modified later with the vim_let() method.
245 vim_let
247 $tvc->vim_let( %variables );
248 $tvc->vim_let( perl_no_extended_vars => 1 );
249 Change the options that are set with the Vim "let" command when Vim is
251 run. See "new" for details.
252 syntax_mark_file
254 $tvc->syntax_mark_file( $file, %options )
255 Mark up the specified file. Subsequent calls to the output methods
257 will then return the markup. It is not necessary to call this if a
258 "file" or "string" option was passed to "new".
259 Returns the object it was called on, so an output method can be called
261 on it directly:
262 foreach (@files) {
264 print $tvc->syntax_mark_file($_)->html;
265 }
266 You can override the file type set in new() by passing in a "filetype"
268 option, like so:
269 $tvc->syntax_mark_file($filename, filetype => 'perl');
271 This option will only affect the syntax coloring for that one call, not
273 for any subsequent ones on the same object.
274 syntax_mark_string
276 $tvc->syntax_mark_string($string, %options)
277 Does the same as "syntax_mark_file" (see above) but uses a string as
279 input. The string can also be a reference to a string.
280 Returns the object it was called on. Supports the "filetype" option
282 just as "syntax_mark_file" does.
283 ansi
285 Return the string marked with ANSI escape sequences (using
286 Term::ANSIColor) based on the Vim syntax coloring of the input file.
287 This is the default format for the included text-vimcolor script which
289 makes it like a colored version of cat(1).
290 You can alter the color scheme using the "TEXT_VIMCOLOR_ANSI"
292 environment variable in the format of "SynGroup=color;". For example:
293 TEXT_VIMCOLOR_ANSI='Comment=green;Statement = magenta; '
295 html
297 Return XHTML markup based on the Vim syntax coloring of the input file.
298 Unless the "html_full_page" option is set, this will only return a
300 fragment of HTML, which can then be incorporated into a full page. The
301 fragment will be valid as either HTML or XHTML.
302 The only markup used for the actual text will be "<span>" elements
304 wrapped around appropriate pieces of text. Each one will have a
305 "class" attribute set to a name which can be tied to a foreground and
306 background color in a stylesheet. The class names used will have the
307 prefix "syn", for example "synComment". For the full list see
308 "HIGHLIGHTING TYPES".
309 xml
311 Returns markup in a simple XML vocabulary. Unless the
312 "xml_root_element" option is turned off (it's on by default) this will
313 produce a complete XML document, with all the markup inside a
314 "<syntax>" element.
315 This XML output can be transformed into other formats, either using
317 programs which read it with an XML parser, or using XSLT. See the
318 text-vimcolor(1) program for an example of how XSLT can be used with
319 XSL-FO to turn this into PDF.
320 The markup will consist of mixed content with elements wrapping pieces
322 of text which Vim recognized as being of a particular type. The names
323 of the elements used are the ones listed in "HIGHLIGHTING TYPES".
324 below.
325 The "<syntax>" element will declare the namespace for all the elements
327 produced, which will be "http://ns.laxan.com/text-vimcolor/1". It will
328 also have an attribute called "filename", which will be set to the
329 value returned by the "input_filename" method, if that returns
330 something other than undef.
331 The XML namespace is also available as $Text::VimColor::NAMESPACE_ID.
333 marked
335 This output function returns the marked-up text in the format which the
336 module stores it in internally. The data looks like this:
337 use Data::Dumper;
339 print Dumper($tvc->marked);
340 # produces
342 $VAR1 = [
343 [ 'Statement', 'my' ],
344 [ '', ' ' ],
345 [ 'Identifier', '$syntax' ],
346 [ '', ' = ' ],
347 ...
348 ];
349 This method returns a reference to an array. Each item in the array is
351 itself a reference to an array of two items: the first is one of the
352 names listed in "HIGHLIGHTING TYPES" (or an empty string if none
353 apply), and the second is the actual piece of text.
354 input_filename
356 Returns the filename of the input file, or undef if a filename wasn't
357 specified.
358 dist_file
360 my $full_path = Text::VimColor->dist_file($file);
361 my $xsl = $tvc->dist_file('light.xsl');
362 Returns the path to the specified file that is part of the
364 "Text-VimColor" dist (for example, mark.vim or light.css).
365 Can be called as an instance method or a class method.
367 This is a thin wrapper around "dist_file" in File::ShareDir and is
369 mostly for internal use.
370
372 The following list gives the names of highlighting types which will be
373 set for pieces of text. For HTML output, these will appear as CSS
374 class names, except that they will all have the prefix "syn" added.
375 For XML output, these will be the names of elements which will all be
376 in the namespace "http://ns.laxan.com/text-vimcolor/1".
377 Here is the complete list:
379 • Comment
381 • Constant
383 • Identifier
385 • Statement
387 • PreProc
389 • Type
391 • Special
393 • Underlined
395 • Error
397 • Todo
399
401 These modules allow "Text::VimColor" to be used more easily in
402 particular environments:
403 • Apache::VimColor
405 • Kwiki::VimMode
407 • Template-Plugin-VimColor
409
411 text-vimcolor(1)
412 A simple command line interface to this module's features. It can
413 be used to produce HTML and XML output, print to the screen (like a
414 colored cat(1)), and can also generate PDF output using an
415 XSLT/XSL-FO stylesheet and the FOP processor.
416 http://www.vim.org/
418 Everything to do with the Vim text editor.
419
421 Quite a few, actually:
422 • Apparently this module doesn't always work if run from within a
424 'gvim' window, although I've been unable to reproduce this so far.
425 CPAN RT #11555.
426 • There should be a way of getting a DOM object back instead of an
428 XML string.
429 • It should be possible to choose between HTML and XHTML, and perhaps
431 there should be some control over the DOCTYPE declaration when a
432 complete file is produced.
433 • With Vim versions earlier than 6.2 there is a 2 second delay each
435 time Vim is run.
436 • This requires vim version 6 (it has since 2003). There may be
438 workarounds to support version 5 (technically 5.4+). Upgrading vim
439 is a much better idea, but if you need support for older versions
440 please file a ticket (with patches if possible).
441
443 • option for 'set number'
444 • make global vars available through methods
446 • list available syntaxes? (see IkiWiki::Plugin::syntax::Vim)
448
450 Perldoc
451 You can find documentation for this module with the perldoc command.
452 perldoc Text::VimColor
454 Websites
456 The following websites have more information about this module, and may
457 be of help to you. As always, in addition to those websites please use
458 your favorite search engine to discover more resources.
459 • MetaCPAN
461 A modern, open-source CPAN search engine, useful to view POD in
463 HTML format.
464 <https://metacpan.org/release/Text-VimColor>
466 Bugs / Feature Requests
468 Please report any bugs or feature requests by email to
469 "bug-text-vimcolor at rt.cpan.org", or through the web interface at
470 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-VimColor>. You
471 will be automatically notified of any progress on the request by the
472 system.
473 Source Code
475 <https://github.com/rwstauner/Text-VimColor>
476 git clone https://github.com/rwstauner/Text-VimColor.git
478
480 The Vim script mark.vim is a crufted version of 2html.vim by Bram
481 Moolenaar <Bram@vim.org> and David Ne\v{c}as (Yeti)
482 <yeti@physics.muni.cz>.
483
485 • Geoff Richards <qef@laxan.com>
486 • Randy Stauner <rwstauner@cpan.org>
488
490 • Geoff Richards <geoffr@cpan.org>
491 • Hinrik Örn Sigurðsson <hinrik.sig@gmail.com>
493 • mattn <mattn.jp@gmail.com>
495 • Randy Stauner <randy@r4s6.net>
497 • Shlomi Fish <shlomif@shlomifish.org>
499 • Vyacheslav Matyukhin <mmcleric@yandex-team.ru>
501
503 This software is copyright (c) 2002-2006 by Geoff Richards.
504 This software is copyright (c) 2011 by Randy Stauner.
506 This is free software; you can redistribute it and/or modify it under
508 the same terms as the Perl 5 programming language system itself.
509perl v5.38.0 2023-07-21 Text::VimColor(3)