1Text::VimColor(3) User Contributed Perl Documentation Text::VimColor(3)
2
6 Text::VimColor - syntax color text in HTML or XML using Vim
7
9 use Text::VimColor;
10 my $syntax = Text::VimColor->new(
11 file => $0,
12 filetype => 'perl',
13 );
14 print $syntax->html;
16 print $syntax->xml;
17
19 This module tries to markup text files according to their syntax. It
20 can be used to produce web pages with pretty-printed colourful source
21 code samples. It can produce output in the following formats:
22 HTML
24 Valid XHTML 1.0, with the exact colouring and style left to a CSS
25 stylesheet
26 XML Pieces of text are marked with XML elements in a simple vocabulary,
28 which can be converted to other formats, for example, using XSLT
29 Perl array
31 A simple Perl data structure, so that Perl code can be used to turn
32 it into whatever is needed
33 This module works by running the Vim text editor and getting it to
35 apply its excellent syntax highlighting (aka 'font-locking') to an
36 input file, and mark pieces of text according to whether it thinks they
37 are comments, keywords, strings, etc. The Perl code then reads back
38 this markup and converts it to the desired output format.
39 This is an object-oriented module. To use it, create an object with
41 the "new" function (as shown above in the SYNOPSIS) and then call
42 methods to get the markup out.
43
45 new(options)
46 Returns a syntax highlighting object. Pass it a hash of options.
47 The following options are recognised:
49 file
51 The file to syntax highlight. Can be either a filename or an
52 open file handle.
53 Note that using a filename might allow Vim to guess the file
55 type from its name if none is specified explicitly.
56 If the file isn't specified while creating the object, it can
58 be given later in a call to the "syntax_mark_file" method (see
59 below), allowing a single Text::VimColor object to be used with
60 multiple input files.
61 string
63 Use this to pass a string to be used as the input. This is an
64 alternative to the "file" option. A reference to a string will
65 also work.
66 The "syntax_mark_string" method (see below) is another way to
68 use a string as input.
69 filetype
71 Specify the type of file Vim should expect, in case Vim's
72 automatic detection by filename or contents doesn't get it
73 right. This is particularly important when providing the file
74 as a string of file handle, since Vim won't be able to use the
75 file extension to guess the file type.
76 The filetypes recognised by Vim are short strings like 'perl'
78 or 'lisp'. They are the names of files in the 'syntax'
79 directory in the Vim distribution.
80 This option, whether or not it is passed to "new()", can be
82 overridden when calling "syntax_mark_file" and
83 "syntax_mark_string", so you can use the same object to process
84 multiple files of different types.
85 html_full_page
87 By default the "html()" output method returns a fragment of
88 HTML, not a full file. To make useful output this must be
89 wrapped in a "<pre>" element and a stylesheet must be included
90 from somewhere. Setting the "html_full_page" option will
91 instead make the "html()" method return a complete stand-alone
92 XHTML file.
93 Note that while this is useful for testing, most of the time
95 you'll want to put the syntax highlighted source code in a page
96 with some other content, in which case the default output of
97 the "html()" method is more appropriate.
98 html_inline_stylesheet
100 Turned on by default, but has no effect unless "html_full_page"
101 is also enabled.
102 This causes the CSS stylesheet defining the colours to be used
104 to render the markup to be be included in the HTML output, in a
105 "<style>" element. Turn it off to instead use a "<link>" to
106 reference an external stylesheet (recommended if putting more
107 than one page on the web).
108 html_stylesheet
110 Ignored unless "html_full_page" and "html_inline_stylesheet"
111 are both enabled.
112 This can be set to a stylesheet to include inline in the HTML
114 output (the actual CSS, not the filename of it).
115 html_stylesheet_file
117 Ignored unless "html_full_page" and "html_inline_stylesheet"
118 are both enabled.
119 This can be the filename of a stylesheet to copy into the HTML
121 output, or a file handle to read one from. If neither this nor
122 "html_stylesheet" are given, the supplied stylesheet light.css
123 will be used instead.
124 html_stylesheet_url
126 Ignored unless "html_full_page" is enabled and
127 "html_inline_stylesheet" is disabled.
128 This can be used to supply the URL (relative or absolute) or
130 the stylesheet to be referenced from the HTML "<link>" element
131 in the header. If this isn't given it will default to using a
132 "file:" URL to reference the supplied light.css stylesheet,
133 which is only really useful for testing.
134 xml_root_element
136 By default this is true. If set to a false value, XML output
137 will not be wrapped in a root element called <syn:syntax>, but
138 will be otherwise the same. This could allow XML output for
139 several files to be concatenated, but to make it valid XML a
140 root element must be added. Disabling this option will also
141 remove the binding of the namespace prefix "syn:", so an
142 "xmlns:syn" attribute would have to be added elsewhere.
143 vim_command
145 The name of the executable which will be run to invoke Vim.
146 The default is "vim".
147 vim_options
149 A reference to an array of options to pass to Vim. The default
150 options are:
151 qw( -RXZ -i NONE -u NONE -N )
153 vim_let
155 A reference to a hash of options to set in Vim before the
156 syntax file is loaded. Each of these is set using the ":let"
157 command to the value specified. No escaping is done on the
158 values, they are executed exactly as specified.
159 Values in this hash override some default options. Use a value
161 of "undef" to prevent a default option from being set at all.
162 The defaults are as follows:
163 (
165 perl_include_pod => 1, # Recognize POD inside Perl code
166 'b:is_bash' => 1, # Allow Bash syntax in shell scripts
167 )
168 These settings can be modified later with the "vim_let()"
170 method.
171 vim_let(name => value, ...)
173 Change the options that are set with the Vim "let" command when Vim
174 is run. See "new()" for details.
175 syntax_mark_file(file, options...)
177 Mark up the specified file. Subsequent calls to the output methods
178 will then return the markup. It is not necessary to call this if a
179 "file" or "string" option was passed to "new()".
180 Returns the object it was called on, so an output method can be
182 called on it directly:
183 my $syntax = Text::VimColor->new(
185 vim_command => '/usr/local/bin/special-vim',
186 );
187 foreach (@files) {
189 print $syntax->syntax_mark_file($_)->html;
190 }
191 You can override the filetype set in new() by passing in a
193 "filetype" option, like so:
194 $syntax->syntax_mark_file($filename, filetype => 'perl');
196 This option will only affect the syntax colouring for that one
198 call, not for any subsequent ones on the same object.
199 syntax_mark_string(string, options...)
201 Does the same as "syntax_mark_file" (see above) but uses a string
202 as input. string can also be a reference to a string. Returns the
203 object it was called on. Supports the "filetype" option just as
204 "syntax_mark_file" does.
205 html()
207 Return XHTML markup based on the Vim syntax colouring of the input
208 file.
209 Unless the "html_full_page" option is set, this will only return a
211 fragment of HTML, which can then be incorporated into a full page.
212 The fragment will be valid as either HTML and XHTML.
213 The only markup used for the actual text will be "<span>" elements
215 wrapped round appropriate pieces of text. Each one will have a
216 "class" attribute set to a name which can be tied to a foreground
217 and background color in a stylesheet. The class names used will
218 have the prefix "syn", for example "synComment". For the full list
219 see the section HIGHLIGHTING TYPES below.
220 xml()
222 Returns markup in a simple XML vocabulary. Unless the
223 "xml_root_element" option is turned off (it's on by default) this
224 will produce a complete XML document, with all the markup inside a
225 "<syntax>" element.
226 This XML output can be transformed into other formats, either using
228 programs which read it with an XML parser, or using XSLT. See the
229 text-vimcolor(1) program for an example of how XSLT can be used
230 with XSL-FO to turn this into PDF.
231 The markup will consist of mixed content with elements wrapping
233 pieces of text which Vim recognized as being of a particular type.
234 The names of the elements used are the ones listed in the
235 HIGHLIGHTING TYPES section below.
236 The "<syntax>" element will declare the namespace for all the
238 elements prodeced, which will be
239 "http://ns.laxan.com/text-vimcolor/1". It will also have an
240 attribute called "filename", which will be set to the value
241 returned by the "input_filename" method, if that returns something
242 other than undef.
243 The XML namespace is also available as
245 $Text::VimColor::NAMESPACE_ID.
246 marked()
248 This output function returns the marked-up text in the format which
249 the module stores it in internally. The data looks like this:
250 use Data::Dumper;
252 print Dumper($syntax->marked);
253 $VAR1 = [
255 [ 'Statement', 'my' ],
256 [ '', ' ' ],
257 [ 'Identifier', '$syntax' ],
258 [ '', ' = ' ],
259 ...
260 ];
261 The "marked()" method returns a reference to an array. Each item
263 in the array is itself a reference to an array of two items: the
264 first is one of the names listed in the HIGHLIGHTING TYPES section
265 below (or the empty string if none apply), and the second is the
266 actual piece of text.
267 input_filename()
269 Returns the filename of the input file, or undef if a filename
270 wasn't specified.
271
273 The following list gives the names of highlighting types which will be
274 set for pieces of text. For HTML output, these will appear as CSS
275 class names, except that they will all have the prefix "syn" added.
276 For XML output, these will be the names of elements which will all be
277 in the namespace "http://ns.laxan.com/text-vimcolor/1".
278 Here is the complete list:
280 · Comment
282 · Constant
284 · Identifier
286 · Statement
288 · PreProc
290 · Type
292 · Special
294 · Underlined
296 · Error
298 · Todo
300
302 These modules allow Text::VimColor to be used more easily in particular
303 environments:
304 Apache::VimColor
306 Kwiki::VimMode
307 Template-Plugin-VimColor
308
310 text-vimcolor(1)
311 A simple command line interface to this module's features. It can
312 be used to produce HTML and XML output, and can also generate PDF
313 output using an XSLT/XSL-FO stylesheet and the FOP processor.
314 http://www.vim.org/
316 Everything to do with the Vim text editor.
317 http://ungwe.org/blog/
319 The author's weblog, which uses this module. It is used to make
320 the code samples look pretty.
321
323 Quite a few, actually:
324 · Apparently this module doesn't always work if run from within a
326 'gvim' window, although I've been unable to reproduce this so far.
327 CPAN bug #11555.
328 · Things can break if there is already a Vim swapfile, but sometimes
330 it seems to work.
331 · There should be a way of getting a DOM object back instead of an
333 XML string.
334 · It should be possible to choose between HTML and XHTML, and perhaps
336 there should be some control over the DOCTYPE declaration when a
337 complete file is produced.
338 · With Vim versions earlier than 6.2 there is a 2 second delay each
340 time Vim is run.
341 · It doesn't work on Windows. I am unlikely to fix this, but if
343 anyone who knows Windows can sort it out let me know.
344
346 Geoff Richards <qef@laxan.com>
347 The Vim script mark.vim is a crufted version of 2html.vim by Bram
349 Moolenaar <Bram@vim.org> and David Ne\v{c}as (Yeti)
350 <yeti@physics.muni.cz>.
351
353 Copyright 2002-2006, Geoff Richards.
354 This library is free software; you can redistribute it and/or modify it
356 under the same terms as Perl itself.
357perl v5.12.0 2006-02-19 Text::VimColor(3)