Colorer Library console tools

Colorer library provides useful program colorer/bin/colorer.exe (/usr/bin/colorer in unix systems), which allows you to use common features of the library itself. These includes:

• Listing and test load of all the available languages.
• Highlighted source files HTML markup generation.
• Highlighted files viewing in console window (win32 only).
• Regular Expressions tests.

Listing Languages

To list all available types of syntax rules, run colorer -l command. This will print out into the standard output all the supported computer languages and file types. If you want to test full database and load all types, run colorer -ll. This will take little more time to load and test HRC database. All errors, warnings and other messages you'll found in the log file, specified in catalog.xml file.

Additionally you can use colorer -lt syntax to list not type descriptions, but their internal names. This can be used in automated environments.

Highlighted HTML sources generation

You can use Colorer to format you source files into HTML markup. This is useful when publishing sources on your web-site, or making documentation based on your source files. You can find generated examples of some sources on start page in section Highlighting. Also you can check Online HTML Generator on colorer.sf.net site.

To generate highlighted source of filename, you have to run colorer -h filename. This will print out the generated HTML file into the standard output. If you want to write this HTML code into some other file, you can specify this file with -o option. Also you can specify input and output character encodings (-ei ENCNAME and -eo ENCNAME) to read and write data.

So, running colorer -h -ei UTF-8 -eo UTF-16BE -o NAME.HTML yoursource.cpp will cause highlighted html generation of yoursource.cpp file with output name NAME.HTML, using UTF-8 as input encoding and UTF-16BE as encoding of result file.

If placing "-" instead of input file name, colorer will read data from standard input.

You can specify special "doclinks" file with external help references to any tokens in your generated HTML. Use -ls"filename" to activate this feature. You can find sample doclink files in colorer/bin/doclinks directory.

Viewing file in a console window

To run internal colorer viewer you can execute colorer -v filename. This should work only on win32 systems. Console viewer uses unicode versions of Win32 API, so it can view files with different character sets. In w9x systems colorer additionally uses output encoding parameter because w9x doesn't support unicode console output. Viewer supports standard navigation keys, but has minimal functionality.

Additional options

Colorer provides a set of different command line options, you can check all of them running colorer without any parameters.

Token generator

This option is similar with HTML generation more, with exception that generated HTML file defines tokens not with colors, but with abstract CSS classes, with the same name as the name of the appropriate token (Region). Each token is assigned here to a CSS class with its region's name and to all its parent classes. For instance simple comment token will be formatted as <span class='c_Comment def_Comment def_Syntax'>//comment</span>. To use colorer in tokenizer more, you have to run colorer -ht filename.

Type detection

By default, colorer tries to automatically detect filetype. You can redefine used language with -t parameter. Just specify -t name, and colorer will use language name to highlight requiried file.

Changing catalog path

You can specify custom path to catalog.xml file. This file contains references to all other library resources. By default, colorer tries to search this file within a set of predefined locations.

Highlighting styles selection

You can change color style, used to highlight source files. Colorer makes this through the HRD files set. You can change default used coloring style with -i option. Text viewer and HTML generator has different sets of HRD styles, you can find available style names in catalog.xml file. For example, specify -i black to activate black styled scheme of colors.
Extended formatting properties are available for RGB styles: bold, italic, underline. These are customized via 'style' attribute of HRD description.
Link references definitions (doc-links) can be used additionally to provide special links formatting. Special doc-links format files can be specified via -ls option.

Customizing HTML output

There is a number of options available, which control HTML output. These are:

• -ln Place line numbers into the generated file.
• -db Disable BOM insertion in start of output files when one of Unicode encodings is used.
• -dc Disable informational&copyright header output in start of each HTML file.
• -ds Disable HTML special symbols substitutions with entities.
• -dh Disable HTML header and footer output.

Simple file forwarding

Last useful option of colorer tool is -f processing mode. With this command colorer simply forwards input file into the output one with optional encoding convertion.