1Text::VimColor(3)     User Contributed Perl Documentation    Text::VimColor(3)
2
3
4

NAME

6       Text::VimColor - Syntax highlight text using Vim
7

VERSION

9       version 0.29
10

SYNOPSIS

12          use Text::VimColor;
13          my $syntax = Text::VimColor->new(
14             file => $0,
15             filetype => 'perl',
16          );
17
18          print $syntax->html;
19          print $syntax->xml;
20          print $syntax->ansi;
21

DESCRIPTION

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
27       HTML
28           Valid XHTML 1.0, with the exact coloring and style left to a CSS
29           stylesheet
30
31       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
34       Perl array
35           A simple Perl data structure, so that Perl code can be used to turn
36           it into whatever is needed
37
38       ANSI Escape Sequences
39           A string marked with Term::ANSIColor suitable for printing to a
40           terminal.
41
42       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
48       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

METHODS

53   new
54         my $tvc = Text::VimColor->new(%options)
55
56       Returns a syntax highlighting object.  Pass it a hash of options.
57
58       The following options are recognized:
59
60       file
61           The file to syntax highlight.  Can be either a filename or an open
62           file handle.
63
64           Note that using a filename might allow Vim to guess the file type
65           from its name if none is specified explicitly.
66
67           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
72       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
77           The "syntax_mark_string" method is another way to use a string as
78           input.
79
80           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
84       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
91           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
95           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
100       all_syntax_groups
101           By default, this option is disabled. That means that the
102           highlighting will only use the following syntax groups:
103
104             Comment
105             Constant
106             Identifier
107             Statement
108             PreProc
109             Type
110             Special
111             Underlined
112             Ignore
113             Error
114             Todo
115
116           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
122             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
149       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
156           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
161       html_inline_stylesheet
162           Turned on by default, but has no effect unless "html_full_page" is
163           also enabled.
164
165           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
171       html_stylesheet
172           Ignored unless "html_full_page" and "html_inline_stylesheet" are
173           both enabled.
174
175           This can be set to a stylesheet to include inline in the HTML
176           output (the actual CSS, not the filename of it).
177
178       html_stylesheet_file
179           Ignored unless "html_full_page" and "html_inline_stylesheet" are
180           both enabled.
181
182           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
187       html_stylesheet_url
188           Ignored unless "html_full_page" is enabled and
189           "html_inline_stylesheet" is disabled.
190
191           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
197       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
201           New in version 0.29 .
202
203       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
212       vim_command
213           The name of the executable which will be run to invoke Vim.  The
214           default is "vim".
215
216       vim_options
217           A reference to an array of options to pass to Vim.  The default
218           options are:
219
220             [qw( -RXZ -i NONE -u NONE -N -n ), "+set nomodeline"]
221
222           You can overwrite the default options by setting this.  To merely
223           append additional options to the defaults use "extra_vim_options".
224
225       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
229       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
235           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
239              (
240                 perl_include_pod => 1,     # Recognize POD inside Perl code
241                 'b:is_bash' => 1,          # Allow Bash syntax in shell scripts
242              )
243
244           These settings can be modified later with the "vim_let()" method.
245
246   vim_let
247         $tvc->vim_let( %variables );
248         $tvc->vim_let( perl_no_extended_vars => 1 );
249
250       Change the options that are set with the Vim "let" command when Vim is
251       run.  See "new" for details.
252
253   syntax_mark_file
254         $tvc->syntax_mark_file( $file, %options )
255
256       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
260       Returns the object it was called on, so an output method can be called
261       on it directly:
262
263         foreach (@files) {
264           print $tvc->syntax_mark_file($_)->html;
265         }
266
267       You can override the file type set in new() by passing in a "filetype"
268       option, like so:
269
270         $tvc->syntax_mark_file($filename, filetype => 'perl');
271
272       This option will only affect the syntax coloring for that one call, not
273       for any subsequent ones on the same object.
274
275   syntax_mark_string
276         $tvc->syntax_mark_string($string, %options)
277
278       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
281       Returns the object it was called on.  Supports the "filetype" option
282       just as "syntax_mark_file" does.
283
284   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
288       This is the default format for the included text-vimcolor script which
289       makes it like a colored version of cat(1).
290
291       You can alter the color scheme using the "TEXT_VIMCOLOR_ANSI"
292       environment variable in the format of "SynGroup=color;".  For example:
293
294          TEXT_VIMCOLOR_ANSI='Comment=green;Statement = magenta; '
295
296   html
297       Return XHTML markup based on the Vim syntax coloring of the input file.
298
299       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
303       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
310   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
316       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
321       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
326       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
332       The XML namespace is also available as $Text::VimColor::NAMESPACE_ID.
333
334   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
338          use Data::Dumper;
339          print Dumper($tvc->marked);
340
341          # produces
342          $VAR1 = [
343             [ 'Statement', 'my' ],
344             [ '', ' ' ],
345             [ 'Identifier', '$syntax' ],
346             [ '', ' = ' ],
347              ...
348          ];
349
350       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
355   input_filename
356       Returns the filename of the input file, or undef if a filename wasn't
357       specified.
358
359   dist_file
360         my $full_path = Text::VimColor->dist_file($file);
361         my $xsl = $tvc->dist_file('light.xsl');
362
363       Returns the path to the specified file that is part of the
364       "Text-VimColor" dist (for example, mark.vim or light.css).
365
366       Can be called as an instance method or a class method.
367
368       This is a thin wrapper around "dist_file" in File::ShareDir and is
369       mostly for internal use.
370

HIGHLIGHTING TYPES

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
378       Here is the complete list:
379
380       •   Comment
381
382       •   Constant
383
384       •   Identifier
385
386       •   Statement
387
388       •   PreProc
389
390       •   Type
391
392       •   Special
393
394       •   Underlined
395
396       •   Error
397
398       •   Todo
399
401       These modules allow "Text::VimColor" to be used more easily in
402       particular environments:
403
404       •   Apache::VimColor
405
406       •   Kwiki::VimMode
407
408       •   Template-Plugin-VimColor
409

SEE ALSO

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
417       http://www.vim.org/
418           Everything to do with the Vim text editor.
419

BUGS

421       Quite a few, actually:
422
423       •   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
427       •   There should be a way of getting a DOM object back instead of an
428           XML string.
429
430       •   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
434       •   With Vim versions earlier than 6.2 there is a 2 second delay each
435           time Vim is run.
436
437       •   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

TODO

443       •   option for 'set number'
444
445       •   make global vars available through methods
446
447       •   list available syntaxes? (see IkiWiki::Plugin::syntax::Vim)
448

SUPPORT

450   Perldoc
451       You can find documentation for this module with the perldoc command.
452
453         perldoc Text::VimColor
454
455   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
460       •   MetaCPAN
461
462           A modern, open-source CPAN search engine, useful to view POD in
463           HTML format.
464
465           <https://metacpan.org/release/Text-VimColor>
466
467   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
474   Source Code
475       <https://github.com/rwstauner/Text-VimColor>
476
477         git clone https://github.com/rwstauner/Text-VimColor.git
478

ACKNOWLEDGEMENTS

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

AUTHORS

485       •   Geoff Richards <qef@laxan.com>
486
487       •   Randy Stauner <rwstauner@cpan.org>
488

CONTRIBUTORS

490       •   Geoff Richards <geoffr@cpan.org>
491
492       •   Hinrik Örn Sigurðsson <hinrik.sig@gmail.com>
493
494       •   mattn <mattn.jp@gmail.com>
495
496       •   Randy Stauner <randy@r4s6.net>
497
498       •   Shlomi Fish <shlomif@shlomifish.org>
499
500       •   Vyacheslav Matyukhin <mmcleric@yandex-team.ru>
501
503       This software is copyright (c) 2002-2006 by Geoff Richards.
504
505       This software is copyright (c) 2011 by Randy Stauner.
506
507       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.
509
510
511
512perl v5.34.0                      2022-01-21                 Text::VimColor(3)
Impressum