diff options
Diffstat (limited to 'framework/3rdParty/TextHighlighter/Text/README')
| -rw-r--r-- | framework/3rdParty/TextHighlighter/Text/README | 455 |
1 files changed, 455 insertions, 0 deletions
diff --git a/framework/3rdParty/TextHighlighter/Text/README b/framework/3rdParty/TextHighlighter/Text/README new file mode 100644 index 00000000..b6f22450 --- /dev/null +++ b/framework/3rdParty/TextHighlighter/Text/README @@ -0,0 +1,455 @@ +# $Id: README,v 1.1 2007/06/03 02:35:28 ssttoo Exp $
+
+Introduction
+============
+
+Text_Highlighter is a class for syntax highlighting. The main idea is to
+simplify creation of subclasses implementing syntax highlighting for
+particular language. Subclasses do not implement any new functioanality, they
+just provide syntax highlighting rules. The rules sources are in XML format.
+To create a highlighter for a language, there is no need to code a new class
+manually. Simply describe the rules in XML file and use Text_Highlighter_Generator
+to create a new class.
+
+
+This document does not contain a formal description of API - it is very
+simple, and I believe providing some examples of code is sufficient.
+
+
+Highlighter XML source
+======================
+
+Basics
+------
+
+Creating a new syntax highlighter begins with describing the highlighting
+rules. There are two basic elements: block and region. A block is just a
+portion of text matching a regular expression and highlighted with a single
+color. Keyword is an example of a block. A region is defined by two regular
+expressions: one for start of region, and another for the end. The main
+difference from a block is that a region can contain blocks and regions
+(including same-named regions). An example of a region is a group of
+statements enclosed in curly brackets (this is used in many languages, for
+example PHP and C). Also, characters matching start and end of a region may be
+highlighted with their own color, and region contents with another.
+
+Blocks and regions may be declared as contained. Contained blocks and regions
+can only appear inside regions. If a region or a block is not declared as
+contained, it can appear both on top level and inside regions. Block or region
+declared as not-contained can only appear on top level.
+
+For any region, a list of blocks and regions that can appear inside this
+region can be specified.
+
+In this document, the term "color group" is used. Chunks of text assigned to
+same color group will be highlighted with same color. Note that in versions
+prior 0.5.0 color goups were refered as CSS classes, but since 0.5.0 not only
+HTML output is supported, so "color group" is more appropriate term.
+
+Elements
+--------
+
+The toplevel element is <highlight>. Attribute lang is required and denotes
+the name of the language. Its value is used as a part of generated class name,
+and must only contain letters, digits and underscores. Optional attribute
+case, when given value yes, makes the language case sensitive (default is case
+insensitive). Allowed subelements are:
+
+ * <authors>: Information about the authors of the file.
+ <author>: Information about a single author of the file. (May be used
+ multiple times, one per author.)
+ - name="...": Author's name. Required.
+ - email="...": Author's email address. Optional.
+
+ * <default>: Default color group.
+ - innerGroup="...": color group name. Required.
+
+ * <region>: Region definition
+ - name="...": Region name. Required.
+ - innerGroup="...": Default color group of region contents. Required.
+ - delimGroup="...": color group of start and end of region. Optional,
+ defaults to value of innerGroup attribute.
+ - start="...", end="...": Regular expression matching start and end
+ of region. Required. Regular expression delimiters are optional, but
+ if you need to specify delimiter, use /. The only case when the
+ delimiters are needed, is specifying regular expression modifiers,
+ such as m or U. Examples: \/\* or /$/m.
+ - contained="yes": Marks region as contained.
+ - never-contained="yes": Marks region as not-contained.
+ - <contains>: Elements allowed inside this region.
+ - all="yes" Region can contain any other region or block
+ (except not-contained). May be used multiple times.
+ - <but> Do not allow certain regions or blocks.
+ - region="..." Name of region not allowed within
+ current region.
+ - block="..." Name of block not allowed within
+ current region.
+ - region="..." Name of region allowed within current region.
+ - block="..." Name of block allowed within current region.
+ - <onlyin> Only allow this region within certain regions. May be
+ used multiple times.
+ - block="..." Name of parent region
+
+ * <block>: Block definition
+ - name="...": Block name. Required.
+ - innerGroup="...": color group of block contents. Optional. If not
+ specified, color group of parent region or default color group will be
+ used. One would only want to omit this attribute if there are
+ keyword groups (see below) inherited from this block, and no special
+ highlighting should apply when the block does not match the keyword.
+ - match="..." Regular expression matching the block. Required.
+ Regular expression delimiters are optional, but if you need to
+ specify delimiter, use /. The only case when the delimiters are
+ needed, is specifying regular expression modifiers, such as m or U.
+ Examples: #|\/\/ or /$/m.
+ - contained="yes": Marks block as contained.
+ - never-contained="yes": Marks block as not-contained.
+ - <onlyin> Only allow this block within certain regions. May be used
+ multiple times.
+ - block="..." Name of parent region
+ - multiline="yes": Marks block as multi-line. By default, whole
+ blocks are assumed to reside in a single line. This make the things
+ faster. If you need to declare a multi-line block, use this
+ attribute.
+ - <partgroup>: Assigns another color group to a part of the block that
+ matched a subpattern.
+ - index="n": Subpattern index. Required.
+ - innerGroup="...": color group name. Required.
+
+ This is an example from CSS highlighter: the measure is matched as
+ a whole, but the measurement units are highlighted with different
+ color.
+
+ <block name="measure" match="\d*\.?\d+(\%|em|ex|pc|pt|px|in|mm|cm)"
+ innerGroup="number" contained="yes">
+ <onlyin region="property"/>
+ <partGroup index="1" innerGroup="string" />
+ </block>
+
+ * <keywords>: Keyword group definition. Keyword groups are useful when you
+ want to highlight some words that match a condition for a block with a
+ different color. Keywords are defined with literal match, not regular
+ expressions. For example, you have a block named identifier matching a
+ general identifier, and want to highlight reserved words (which match
+ this block as well) with different color. You inherit a keyword group
+ "reserved" from "identifier" block.
+ - name="...": Keyword group. Required.
+ - ifdef="...", ifndef="..." : Conditional declaration. See
+ "Conditions" below.
+ - inherits="...": Inherited block name. Required.
+ - innerGroup="...": color group of keyword group. Required.
+ - case="yes|no": Overrides case-sensitivity of the language.
+ Optional, defaults to global value.
+ - <keyword>: Single keyword definition.
+ - match="..." The keyword. Note: this is not a regular
+ expression, but literal match (possibly case insensitive).
+
+Note that for BC reasons element partClass is alias for partGroup, and
+attributes innerClass and delimClass are aliases of innerGroup and
+delimGroup, respectively.
+
+
+Conditions
+----------
+
+Conditional declarations allow enabling or disabling certain highlighting
+rules at runtime. For example, Java highlighter has a very big list of
+keywords matching Java standard classes. Finding a match in this list can take
+much time. For that reason, corresponding keyword group is declared with
+"ifdef" attribute :
+
+ <keywords name="builtin" inherits="identifier" innerClass="builtin"
+ case="yes" ifdef="java.builtins">
+ <keyword match="AbstractAction" />
+ <keyword match="AbstractBorder" />
+ <keyword match="AbstractButton" />
+ ...
+ ...
+ <keyword match="_Remote_Stub" />
+ <keyword match="_ServantActivatorStub" />
+ <keyword match="_ServantLocatorStub" />
+ </keywords>
+
+This keyword group will be only enabled when "java.builtins" is passed as an
+element of "defines" option:
+
+ $options = array(
+ 'defines' => array(
+ 'java.builtins',
+ ),
+ 'numbers' => HL_NUMBERS_TABLE,
+ );
+ $highlighter =& Text_Highlighter::factory('java', $options);
+
+"ifndef" attribute has reverse meaning.
+
+Currently, "ifdef" and "ifndef" attributes are only supported for <keywords>
+tag.
+
+
+
+Class generation
+================
+
+Creating XML description of highlighting rules is the most complicated part of
+the process. To generate the class, you need just few lines of code:
+
+ <?php
+ require_once 'Text/Highlighter/Generator.php';
+ $generator =& new Text_Highlighter_Generator('php.xml');
+ $generator->generate();
+ $generator->saveCode('PHP.php');
+ ?>
+
+
+
+Command-line class generation tool
+==================================
+
+Example from previous section looks pretty simple, but it does not handle any
+errors which may occur during parsing of XML source. The package provides a
+command-line script to make generation of classes even more simple, and takes
+care of possible errors. It is called generate (on Unix/Linux) or generate.bat
+(on Windows). This script is able to process multiple files in one run, and
+also to process XML from standard input and write generated code to standard
+output.
+
+ Usage:
+ generate options
+
+ Options:
+ -x filename, --xml=filename
+ source XML file. Multiple input files can be specified, in which
+ case each -x option must be followed by -p unless -d is specified
+ Defaults to stdin
+ -p filename, --php=filename
+ destination PHP file. Defaults to stdout. If specied multiple times,
+ each -p must follow -x
+ -d dirname, --dir=dirname
+ Default destination directory. File names will be taken from XML input
+ ("lang" attribute of <highlight> tag)
+ -h, --help
+ This help
+
+Examples
+
+ Read from php.xml, write to PHP.php
+
+ generate -x php.xml -p PHP.php
+
+ Read from php.xml, write to standard output
+
+ generate -x php.xml
+
+ Read from php.xml, write to PHP.php, read from xml.xml, write to XML.php
+
+ generate -x php.xml -p PHP.php -x xml.xml -p XML.php
+
+ Read from php.xml, write to /some/dir/PHP.php, read from xml.xml, write to
+ /some/dir/XML.php (assuming that xml.xml contains <highlight lang="xml">, and
+ php.xml contains <highlight lang="php">)
+
+ generate -x php.xml -x xml.xml -d /some/dir/
+
+
+
+Renderers
+=========
+
+Introduction
+------------
+
+Text_Highlighter supports renderes. Using renderers, you can get output in
+different formats. Two renderers are included in the package:
+
+ - HTML renderer. Generates HTML output. A style sheet should be linked to
+ the document to display colored text
+
+ - Console renderer. Can be used to output highlighted text to
+ color-capable terminals, either directly or trough less -r
+
+
+Renderers API
+-------------
+
+Renderers are subclasses of Text_Highlighter_Renderer. Renderer should
+override at least two methods - acceptToken and getOutput. Overriding other
+methods is optional, depending on the nature of renderer's output and details
+of implementation.
+
+ string reset()
+ resets renderer state. This method is called every time before a new
+ source file is highlighted.
+
+ string preprocess(string $code)
+ preprocesses code. Can be used, for example, to normalize whitespace
+ before highlighting. Returns preprocessed string.
+
+ void acceptToken(string $group, string $content)
+ the core method of the renderer. Highlighter passes chunks of text to
+ this method in $content, and color group in $group
+
+ void finalize()
+ signals the renderer that no more tokens are available.
+
+ mixed getOutput()
+ returns generated output.
+
+
+Setting renderer options
+--------------------------------
+
+Renderers accept an optional argument to their constructor - options array.
+Elements of this array are renderer-specific.
+
+HTML renderer
+-------------
+
+HTML renderer produces HTML output with optional line numbering. The renderer
+itself does not provide information about actual colors of highlighted text.
+Instead, <span class="hl-XXX"> is used, where XXX is replaced with color group
+name (hl-var, hl-string, etc.). It is up to you to create a CSS stylesheet.
+If 'use_language' option with value evaluating to true was passed, class names
+will be formatted as "hl-LANG-XXX", where LANG is language name as defined in
+highlighter XML source ("lang" attribute of <highlight> tag) in lower case.
+
+There are 3 special CSS classes:
+
+ hl-main - this class applies to whole output or right table column,
+ depending on 'numbers' option
+ hl-gutter - applies to left column in table
+ hl-table - applies to whole table
+
+HTML renderer accepts following options (each being optional):
+
+ * numbers - line numbering style.
+ 0 - no numbering (default)
+ HL_NUMBERS_LI - use <ol></ol> for line numbering
+ HL_NUMBERS_TABLE - create a 2-column table, with line numbers in left
+ column and highlighted text in right column
+
+ * tabsize - tabulation size. Defaults to 4
+
+ Example:
+
+ require_once 'Text/Highlighter/Renderer/Html.php';
+ $options = array(
+ 'numbers' => HL_NUMBERS_LI,
+ 'tabsize' => 8,
+ );
+ $renderer =& new Text_Highlighter_Renderer_HTML($options);
+
+Console renderer
+----------------
+
+Console renderer produces output for displaying on a color-capable terminal,
+either directly or through less -r, using ANSI escape sequences. By default,
+this renderer only highlights most common color groups. Additional colors
+can be specified using 'colors' option. This renderer also accepts 'numbers'
+option - a boolean value, and 'tabsize' option.
+
+ Example :
+
+ require_once 'Text/Highlighter/Renderer/Console.php';
+ $colors = array(
+ 'prepro' => "\033[35m",
+ 'types' => "\033[32m",
+ );
+ $options = array(
+ 'numbers' => true,
+ 'tabsize' => 8,
+ 'colors' => $colors,
+ );
+ $renderer =& new Text_Highlighter_Renderer_Console($options);
+
+
+ANSI color escape sequences have the following format:
+
+ ESC[#;#;....;#m
+
+where ESC is character with ASCII code 27 (033 octal, 0x1B hexadecimal). # is
+one of the following:
+
+ 0 for normal display
+ 1 for bold on
+ 4 underline (mono only)
+ 5 blink on
+ 7 reverse video on
+ 8 nondisplayed (invisible)
+ 30 black foreground
+ 31 red foreground
+ 32 green foreground
+ 33 yellow foreground
+ 34 blue foreground
+ 35 magenta foreground
+ 36 cyan foreground
+ 37 white foreground
+ 40 black background
+ 41 red background
+ 42 green background
+ 43 yellow background
+ 44 blue background
+ 45 magenta background
+ 46 cyan background
+ 47 white background
+
+
+How to use Text_Highlighter class
+=================================
+
+Creating a highlighter object
+-----------------------------
+
+To create a highlighter for a certain language, use Text_Highlighter::factory()
+static method:
+
+ require_once 'Text/Highlighter.php';
+ $hl =& Text_Highlighter::factory('php');
+
+
+Setting a renderer
+------------------
+
+Actual output is produced by a renderer.
+
+ require_once 'Text/Highlighter.php';
+ require_once 'Text/Highlighter/Renderer/Html.php';
+ $options = array(
+ 'numbers' => HL_NUMBERS_LI,
+ 'tabsize' => 8,
+ );
+ $renderer =& new Text_Highlighter_Renderer_HTML($options);
+ $hl =& Text_Highlighter::factory('php');
+ $hl->setRenderer($renderer);
+
+Note that for BC reasons, it is possible to use highlighter without setting a
+renderer. If no renderer is set, HTML renderer will be used by default. In
+this case, you should pass options as second parameter to factory method. The
+following example works exactly as previous one:
+
+ require_once 'Text/Highlighter.php';
+ $options = array(
+ 'numbers' => HL_NUMBERS_LI,
+ 'tabsize' => 8,
+ );
+ $hl =& Text_Highlighter::factory('php', $options);
+
+
+Getting output
+--------------
+
+And finally, do the highlighting and get the output:
+
+ require_once 'Text/Highlighter.php';
+ require_once 'Text/Highlighter/Renderer/Html.php';
+ $options = array(
+ 'numbers' => HL_NUMBERS_LI,
+ 'tabsize' => 8,
+ );
+ $renderer =& new Text_Highlighter_Renderer_HTML($options);
+ $hl =& Text_Highlighter::factory('php');
+ $hl->setRenderer($renderer);
+ $html = $hl->highlight(file_get_contents('example.php'));
+
+# vim: set autoindent tabstop=4 shiftwidth=4 softtabstop=4 tw=78: */
+
|