
colorer extension to PHP
=========================

Colorer take5 is a syntax highlighting and text parsing library, that provides
services of text parsing in host editor systems in real-time and transforming
results into colored text. For details, see http://colorer.sourceforge.net/

While colorer is primarily designed for use with text editors, it can be also
used for non-interactive syntax highlighting, for example, in web
applications. This PHP extension provides basic functions for syntax
highlighting. Only tested on Linux (Mandrake 10 Officaial), with both PHP 4
and PHP 5, but should compile on most UNIX flavours (I hope).


Installation
============

You need colorer library installed. Compile PHP with --with-colorer.
Default colorer library istallation directory is assumed to be /usr/local.
If you installed colorer in different directory, use --with-colorer=DIR


Performance
===========

Colorer library is very slow when loading highlighting rules. Highlighting
rules are loaded on the fly when necessary. Each instance of colorer class
maintains list of loaded rules separately. To maximize highlighting speed when
highlighting multiple files in one script, create and use single instance of
colorer (see colorer_open()).



Brief reference
===============

Most of functions can be used in both procedural and OO style.



    object colorer_open()

Creates colorer object. You can call methods of this object, or pass it as
first parameter to functions.



    string colorer_highlight_string(object colorer, string str [,string type='' [, bool ret=false]])
    string colorer::highlightString(string str [,string type='' [, bool ret=false]])

Highligts code passed in parameter str, and outputs result. An attempt to
determine language from first line of code is performed. Language can be
specified explicitely using type parameter. Use colorer_list_types() to get
list of supported types. To return result as a string instead of printing it,
pass ret=true



    string colorer_highlight_string_cb(object colorer, string str, callback cb [,string type=''])
    string colorer::highlightStringCB(string str, callback cb [,string type=''])

Parses code passed in parameter str, and calls cb for each chunk of text that
normally would be outputted.  An attempt to determine language from first line
of code is performed. Language can be specified explicitely using type
parameter. Use colorer_list_types() to get list of supported types.
Callback function should accept 2 parameters: class and text. Class shows what
is the role of this particular chunk of text. It looks like this: php_OpenTag,
def_Var, html_htmlParam, etc.



    string colorer_highlight_file(object colorer, string filename [,string type='' [, bool ret=false]])
    string colorer::highlightFile(string filename [,string type='' [, bool ret=false]])

Highligts code from file filename, and outputs result. An attempt to
determine language from file extension is performed. Language can be
specified explicitely using type parameter. Use colorer_list_types() to get
list of supported types. To return result as a string instead of printing it,
pass ret=true




    string colorer_highlight_file_cb(object colorer, string filename, callback cb [,string type=''])
    string colorer::highlightFileCB(string filename, callback cb [,string type=''])

Parses code from file filename, and calls cb for each chunk of text that
normally would be outputted.  An attempt to determine language from file
extension is performed. Language can be specified explicitely using type
parameter. Use colorer_list_types() to get list of supported types.
Callback function should accept 2 parameters: class and text. Class shows what
is the role of this particular chunk of text. It looks like this: php_OpenTag,
def_Var, html_htmlParam, etc.



    bool colorer_set_input_encoding(string encoding)
    bool colorer::setInputEncoding(string encoding)

Sets encoding of source text.  If output encoding was not already set, output
encoding will be set same as input encoding. Returns true on success, false if
specified encoding is not supported. Currently, colorer supports the following
encodings:

  UTF-32LE
  UTF-16BE
  UTF-32BE
  UTF-16LE
  UTF-32
  UTF-16
  UTF-8
  ISO-8859-1
  ASCII
  US-ASCII
  LATIN1
  8859-1
  8859-2
  LATIN2
  ISO-8859-2
  8859-3
  LATIN3
  ISO-8859-3
  CP1250
  Windows-1250
  CP1251
  Windows-1251
  CP1252
  Windows-1252
  CP866
  KOI8-R
  KOI-8

Obviously, some encoding names are just aliases (ISO-8859-1 and 8859-1, for
example).



    bool colorer_set_output_encoding(string encoding)
    bool colorer::setOutputEncoding(string encoding)

Sets output encoding. Returns true on success, false if specified encoding is
not supported. See colorer_set_input_encoding for list of supported encodings.



    string colorer_version()
    string colorer::version()

Returns version of colorer library



    bool colorer_direct_markup(object colorer [, bool value])
    bool colorer::directMarkup([bool value])

Specifies whether to use direct markup or CSS classes, and returns old value
of this option. If optional parameter is not passed, just returns current
value. By default, direct markup is off, and output is generated using
<span class="xxx"> tags. When direct markup is on, output is generated using
either <span style="xxx"> or custom murkup (which may be non-html), depending
on colorer_hrd_name() setting.



    string colorer_hrd_name(object colorer [, string hrd_name])
    string colorer::hrdName([string hrd_name])

Specifies region definition to use, and returns old value of this option.
Region definition specifies color scheme to use for highlighting. It should be
base name of one of files with region definitions installed on your system.
If no value is passed, just returns current setting.


    string colorer_type(object colorer [, string type])
    string colorer::type([string type])

Specifies language of code and returns old value of this
option. If no value is passed, just returns current setting.
Language is affected by colorer_type(), type parameter of colorer_highlight_*
functions, and filename parameter of colorer_higlight_file* functions. type
parameter has highest precedence, filename parameter -- lowest.



    array colorer_list_types()
    array colorer::listTypes()

Returns array of supported file types with descriptions. Each element of array
is an array with 3 elements: file type(refered here as language), group and
description:

Array
(
    [0] => Array
        (
            [0] => c
            [1] => main
            [2] => C
        )

    [1] => Array
        (
            [0] => cpp
            [1] => main
            [2] => C++
        )

    [2] => Array
        (
            [0] => asm
            [1] => main
            [2] => ASM
        )

    [3] => Array
        (
            [0] => perl
            [1] => main
            [2] => Perl
        )
...
...
)



/* vim: set et ts=4 sw=4 sts=4 tw=78 ai: */
$Id: README 4 2005-04-26 12:47:22Z andrey $
