GeSHi - Generic Syntax Highlighter

Context: https://sourceforge.net/tracker/?func=detail&aid=2817741&group_id=114997&atid=670234

This is a proposal for GeSHi's extension API. Some parts are somewhat vague because not all details are known, and some have not been considered. For
example, all variables and functions would be best in a class(es), but this class's name is unknown. On the other hand, some specific points may be incorrect. <<< Comments are delimited like so. >>>

Requirements:
* Source must be available in both unmodified readonly and modified read/write forms.
* Calling order of callbacks must be sequential, and configurable from user code (by registration order, for example) for callbacks which receive the same element.
* Callbacks must be able to modify each passed source segment by return value (or reference, if GeSHi requires that something else be returned).

string $output - the formatted source code. This must be available to user modifications. <<< Should unformatted code be included in this string? >>>

array $elements - a numerical array of numbers. Each index marks the beginning of exactly one syntax element in the formatted source; its value is the corresponding index in the unformatted source. (I would prefer this the other way around, but more than one syntax element may have the same start in the unformatted source, while HTML will separate them in the formatted.) <<< How can formatted indices be tracked across direct modifications by user code? >>>


<<< return value? >>> setCallback(int $element_types, callback $function)

Registers $callback to be notified of every element of the specified types.

int $element_types - a bitmask of element types which will be passed to $callback.

callback $function - passed to call_user_func; see prototype below.


string $function(string $source, int $index, string $element, int $type)

User code to react to $element and/or change $output.

string $source - the original source code. A copy must be passed so the "real" source can't be modified by reference.

int $index - the index of $element in $output (not $source).

string $element - the element, already formatted by GeSHi. Must include the whole element, not just the contents. For example, quotes must not be stripped from a passed string.

int $type - the bit passed to setCallback which matched this element.

Returns: an updated $element, or a non-string to leave it unaltered.


array explore(string $before, int $index, string $after)

Finds the smallest source segment which matches the given pattern segments. <<< My intention is that the containing statement, or block, or function, or whatever may be found from within the callback. >>>

string $before - a pattern segment identifying the leading delimiter, or NULL.

int $index - the index to be contained in the returned source segment.

string $after - a pattern segment identifying the trailing delimiter, or NULL.

Returns: a two-element array containing the start and end indices of the found source segment within $output. For each NULL pattern segment passed, the corresponding index is also NULL.