\HTML_BBCodeParser

Base HTML_BBCodeParser class to transform BBCode in XHTML

This is a parser to replace UBB style tags with their xhtml equivalents. It's the refundation of the class using the Text_Wiki transform engine

Usage: $parser = new HTML_BBCodeParser(); $parser->setText('normal [b]bold[/b] and normal again'); $parser->parse(); echo $parser->getParsed(); or: $parser = new HTML_BBCodeParser(); echo $parser->qparse('normal [b]bold[/b] and normal again'); or: echo HTML_BBCodeParser::staticQparse('normal [b]bold[/b] and normal again');

Setting the options from the ini file: $config = parse_ini_file('BBCodeParser.ini', true); $options = &PEAR::getStaticProperty('HTML_BBCodeParser', '_options'); $options = $config['HTML_BBCodeParser']; unset($options);

Summary

Methods
Properties
Constants
__construct()
singleton()
factory()
setParseConf()
getParseConf()
setRenderConf()
getRenderConf()
setFormatConf()
getFormatConf()
insertRule()
deleteRule()
changeRule()
enableRule()
disableRule()
transform()
parse()
render()
_renderToken()
registerRenderCallback()
popRenderCallback()
getSource()
getTokens()
addToken()
setToken()
loadParseObj()
loadRenderObj()
loadFormatObj()
addPath()
getPath()
findFile()
fixPath()
error()
isError()
HTML_BBCodeParser()
pruneOptions()
parseIniFile()
filtersToRules()
setText()
getText()
getPreparsed()
getParsed()
qparse()
staticQparse()
$rules
$disable
$parseConf
$renderConf
$formatConf
$delim
$tokens
$_countRulesTokens
$source
$output
$parseObj
$renderObj
$formatObj
$path
$_dirSep
$renderingType
$_renderCallbacks
$_block
$_blocks
$_text
$_parsed
$_options
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Properties

$rules

$rules : array

The default list of rules, in order, to apply to the source text.

Type

array

$disable

$disable : array

The list of rules to not-apply to the source text.

Type

array

$parseConf

$parseConf : array

Custom configuration for rules at the parsing stage.

In this array, the key is the parsing rule name, and the value is an array of key-value configuration pairs corresponding to the $conf property in the target parsing rule.

For example:

$parseConf = array( 'Include' => array( 'base' => '/path/to/scripts/' ) );

Note that most default rules do not need any parsing configuration.

Type

array

$renderConf

$renderConf : array

Custom configuration for rules at the rendering stage.

Because rendering may be different for each target format, the first-level element in this array is always a format name (e.g., 'Xhtml').

Within that first level element, the subsequent elements match the $parseConf format. That is, the sub-key is the rendering rule name, and the sub-value is an array of key-value configuration pairs corresponding to the $conf property in the target rendering rule.

Type

array

$formatConf

$formatConf : array

Custom configuration for the output format itself.

Even though Text_Wiki will render the tokens from parsed text, the format itself may require some configuration. For example, RTF needs to know font names and sizes, PDF requires page layout information, and DocBook needs a section hierarchy. This array matches the $conf property of the the format-level renderer (e.g., Text_Wiki_Render_Xhtml).

In this array, the key is the rendering format name, and the value is an array of key-value configuration pairs corresponding to the $conf property in the rendering format rule.

Type

array

$delim

$delim : string

The delimiter for token numbers of parsed elements in source text.

Type

string

$tokens

$tokens : array

The tokens generated by rules as the source text is parsed.

As Text_Wiki applies rule classes to the source text, it will replace portions of the text with a delimited token number. This is the array of those tokens, representing the replaced text and any options set by the parser for that replaced text.

The tokens array is sequential; each element is itself a sequential array where element 0 is the name of the rule that generated the token, and element 1 is an associative array where the key is an option name and the value is an option value.

Type

array

$_countRulesTokens

$_countRulesTokens : array

How many tokens generated pro rules.

Intended to load only necessary render objects

Type

array

$source

$source : string

The source text to which rules will be applied.

This text will be transformed in-place, which means that it will change as the rules are applied.

Type

string

$output

$output : string

The output text

Type

string

$parseObj

$parseObj : array

Array of rule parsers.

Text_Wiki creates one instance of every rule that is applied to the source text; this array holds those instances. The array key is the rule name, and the array value is an instance of the rule class.

Type

array

$renderObj

$renderObj : array

Array of rule renderers.

Text_Wiki creates one instance of every rule that is applied to the source text; this array holds those instances. The array key is the rule name, and the array value is an instance of the rule class.

Type

array

$formatObj

$formatObj : array

Array of format renderers.

Type

array

$path

$path : array

Array of paths to search, in order, for parsing and rendering rules.

Type

array

$_dirSep

$_dirSep : string

The directory separator character.

Type

string

$renderingType

$renderingType : string

Temporary configuration variable

Type

string

$_renderCallbacks

$_renderCallbacks : Array

Stack of rendering callbacks

Type

Array

$_block

$_block : string

Current output block

Type

string

$_blocks

$_blocks : 

A stack of blocks

Type

$_text

$_text : string

A string containing the input

Type

string

$_parsed

$_parsed : string

A string containing the parsed version of the text

Type

string

$_options

$_options : array

An array of options, filled by an ini file or through the contructor

Type

array

Methods

__construct()

__construct(mixed  $rules = null) : $this

A fix for PHP5.

DEPRECATED Please use the singleton() or factory() methods.

Parameters

mixed $rules

null or an array.

Returns

$this

singleton()

singleton(string  $parser = 'Default', array  $rules = null) : \&object

Singleton.

This avoids instantiating multiple Text_Wiki instances where a number of objects are required in one call, e.g. to save memory in a CMS invironment where several parsers are required in a single page.

$single = singleton();

or

$single = singleton('Parser', array('Prefilter', 'Delimiter', 'Code', 'Function', 'Html', 'Raw', 'Include', 'Embed', 'Anchor', 'Heading', 'Toc', 'Horiz', 'Break', 'Blockquote', 'List', 'Deflist', 'Table', 'Image', 'Phplookup', 'Center', 'Newline', 'Paragraph', 'Url', 'Freelink', 'Interwiki', 'Wikilink', 'Colortext', 'Strong', 'Bold', 'Emphasis', 'Italic', 'Underline', 'Tt', 'Superscript', 'Subscript', 'Revise', 'Tighten'));

Call using a subset of this list. The order of passing rulesets in the $rules array is important!

After calling this, call $single->setParseConf(), setRenderConf() or setFormatConf() as usual for a constructed object of this class.

The internal static array of singleton objects has no index on the parser rules, the only index is on the parser name. So if you call this multiple times with different rules but the same parser name, you will get the same static parser object each time.

Parameters

string $parser

The parser to be used (defaults to 'Default').

array $rules

The set of rules to instantiate the object. This will only be used when the first call to singleton is made, if included in further calls it will be effectively ignored.

Returns

\&object —

a reference to the Text_Wiki unique instantiation.

factory()

factory(string  $parser = 'Default', array  $rules = null) : \Text_Wiki

Returns a Text_Wiki Parser class for the specified parser.

Parameters

string $parser

The name of the parse to instantiate you need to have Text_Wiki_XXX installed to use $parser = 'XXX', it's E_FATAL

array $rules

The rules to pass into the constructor {@see Text_Wiki::singleton} for a list of rules

Returns

\Text_Wiki

a Parser object extended from Text_Wiki

setParseConf()

setParseConf(string  $rule, array|string  $arg1, string  $arg2 = null) : void

Set parser configuration for a specific rule and key.

Parameters

string $rule

The parse rule to set config for.

array|string $arg1

The full config array to use for the parse rule, or a conf key in that array.

string $arg2

The config value for the key.

getParseConf()

getParseConf(string  $rule, string  $key = null) : mixed

Get parser configuration for a specific rule and key.

Parameters

string $rule

The parse rule to get config for.

string $key

A key in the conf array; if null, returns the entire conf array.

Returns

mixed —

The whole conf array if no key is specified, or the specific conf key value.

setRenderConf()

setRenderConf(string  $format, string  $rule, array|string  $arg1, string  $arg2 = null) : void

Set renderer configuration for a specific format, rule, and key.

Parameters

string $format

The render format to set config for.

string $rule

The render rule to set config for in the format.

array|string $arg1

The config array, or the config key within the render rule.

string $arg2

The config value for the key.

getRenderConf()

getRenderConf(string  $format, string  $rule, string  $key = null) : mixed

Get renderer configuration for a specific format, rule, and key.

Parameters

string $format

The render format to get config for.

string $rule

The render format rule to get config for.

string $key

A key in the conf array; if null, returns the entire conf array.

Returns

mixed —

The whole conf array if no key is specified, or the specific conf key value.

setFormatConf()

setFormatConf(string  $format,   $arg1,   $arg2 = null) : void

Set format configuration for a specific rule and key.

Parameters

string $format

The format to set config for.

$arg1
$arg2

getFormatConf()

getFormatConf(string  $format, mixed  $key = null) : mixed

Get configuration for a specific format and key.

Parameters

string $format

The format to get config for.

mixed $key

A key in the conf array; if null, returns the entire conf array.

Returns

mixed —

The whole conf array if no key is specified, or the specific conf key value.

insertRule()

insertRule(string  $name, string  $tgt = null) : void

Inserts a rule into to the rule set.

Parameters

string $name

The name of the rule. Should be different from all other keys in the rule set.

string $tgt

The rule after which to insert this new rule. By default (null) the rule is inserted at the end; if set to '', inserts at the beginning.

deleteRule()

deleteRule(  $name) : void

Delete (remove or unset) a rule from the $rules property.

Parameters

$name

changeRule()

changeRule(string  $old, string  $new) : void

Change from one rule to another in-place.

Parameters

string $old

The name of the rule to change from.

string $new

The name of the rule to change to.

enableRule()

enableRule(  $name) : void

Enables a rule so that it is applied when parsing.

Parameters

$name

disableRule()

disableRule(  $name) : void

Disables a rule so that it is not applied when parsing.

Parameters

$name

transform()

transform(string  $text, string  $format = 'Xhtml') : string

Parses and renders the text passed to it, and returns the results.

First, the method parses the source text, applying rules to the text as it goes. These rules will modify the source text in-place, replacing some text with delimited tokens (and populating the $this->tokens array as it goes).

Next, the method renders the in-place tokens into the requested output format.

Finally, the method returns the transformed text. Note that the source text is transformed in place; once it is transformed, it is no longer the same as the original source text.

Parameters

string $text

The source text to which wiki rules should be applied, both for parsing and for rendering.

string $format

The target output format, typically 'xhtml'. If a rule does not support a given format, the output from that rule is rule-specific.

Returns

string —

The transformed wiki text.

parse()

parse(string  $text = null) : \none

Parses the text set in the object

Parameters

string $text

: if set, that's a call to the parent Text_Wiki::parse()

Returns

\none

render()

render(string  $format = 'Xhtml') : string

Renders tokens back into the source text, based on the requested format.

Parameters

string $format

The target output format, typically 'xhtml'. If a rule does not support a given format, the output from that rule is rule-specific.

Returns

string —

The transformed wiki text.

_renderToken()

_renderToken(  $matches) : string

Renders a token, for use only as an internal callback

Parameters

$matches

Returns

string —

The rendered text for the token

registerRenderCallback()

registerRenderCallback(  $callback) 

Parameters

$callback

popRenderCallback()

popRenderCallback() 

getSource()

getSource() : string

Returns the parsed source text with delimited token placeholders.

Returns

string —

The parsed source text.

getTokens()

getTokens(array  $rules = null) : array

Returns tokens that have been parsed out of the source text.

Parameters

array $rules

If an array of rule names is passed, only return tokens matching these rule names. If no array is passed, return all tokens.

Returns

array —

An array of tokens.

addToken()

addToken(  $rule, array  $options = array(), boolean  $id_only = false) : string|integer

Add a token to the Text_Wiki tokens array, and return a delimited token number.

Parameters

$rule
array $options

An associative array of options for the new token array element. The keys and values are specific to the rule, and may or may not be common to other rule options. Typical options keys are 'text' and 'type' but may include others.

boolean $id_only

If true, return only the token number, not a delimited token string.

Returns

string|integer —

By default, return the number of the newly-created token array element with a delimiter prefix and suffix; however, if $id_only is set to true, return only the token number (no delimiters).

setToken()

setToken(integer  $id, integer  $rule, array  $options = array()) : void

Set or re-set a token with specific information, overwriting any previous rule name and rule options.

Parameters

integer $id

The token number to reset.

integer $rule

The rule name to use.

array $options

An associative array of options for the token array element. The keys and values are specific to the rule, and may or may not be common to other rule options. Typical options keys are 'text' and 'type' but may include others.

loadParseObj()

loadParseObj(  $rule) : boolean

Load a rule parser class file.

Parameters

$rule

Returns

boolean —

True if loaded, false if not.

loadRenderObj()

loadRenderObj(  $format,   $rule) : boolean

Load a rule-render class file.

Parameters

$format
$rule

Returns

boolean —

True if loaded, false if not.

loadFormatObj()

loadFormatObj(  $format) : boolean

Load a format-render class file.

Parameters

$format

Returns

boolean —

True if loaded, false if not.

addPath()

addPath(string  $type, string  $dir) : void

Add a path to a path array.

Parameters

string $type

The path-type to add (parse or render).

string $dir

The directory to add to the path-type.

getPath()

getPath(string  $type = null) : array

Get the current path array for a path-type.

Parameters

string $type

The path-type to look up (plugin, filter, or template). If not set, returns all path types.

Returns

array —

The array of paths for the requested type.

findFile()

findFile(array  $type, string  $file) : string|boolean

Searches a series of paths for a given file.

Parameters

array $type

The type of paths to search (template, plugin, or filter).

string $file

The file name to look for.

Returns

string|boolean —

The full path and file name for the target file, or boolean false if the file is not found in any of the paths.

fixPath()

fixPath(string  $path) : string

Append a trailing '/' to paths, unless the path is empty.

Parameters

string $path

The file path to fix

Returns

string —

The fixed file path

error()

error(string  $message) : object

Simple error-object generator.

Parameters

string $message

The error message.

Returns

object —

PEAR_Error

isError()

isError(mixed  $obj) : boolean

Simple error checker.

Parameters

mixed $obj

Check if this is a PEAR_Error object or not.

Returns

boolean —

True if a PEAR_Error, false if not.

HTML_BBCodeParser()

HTML_BBCodeParser(  $options = array()) : \none

Constructor, initialises the options and filters

Sets the private variable _options with base options defined with &PEAR::getStaticProperty(), overwriting them with (if present) the argument to this method. Then it sets the extra options to properly escape the tag characters in preg_replace() etc. The set options are then stored back with &PEAR::getStaticProperty(), so that the filter classes can use them. All the filters in the options are initialised and their defined tags are copied into the private variable _definedTags.

Parameters

$options

Returns

\none

pruneOptions()

pruneOptions(  $options) : array

Prune (unset) empty arrays in options

Parameters

$options

Returns

array —

the corresponding options as a tree array general|Parse|RenderFormatRule

parseIniFile()

parseIniFile(string  $iniFile = 'BBCodeParser.ini') : array

Parse configuration file to set an option array

Parameters

string $iniFile

the configuration file name (default 'BBCodeParser.ini')

Returns

array —

the corresponding options as a tree general|parse|render|formatFormatRule

filtersToRules()

filtersToRules(  $filters = array()) : array

Sets rules list from Filters (groups of rules)

Parameters

$filters

Returns

array —

the corresponding rules

setText()

setText(  $str) : \none

Sets text in the object to be parsed

Parameters

$str

Returns

\none

getText()

getText() : string

Gets the unparsed text from the object

Returns

string —

the text set in the object

getPreparsed()

getPreparsed() : string

Gets the preparsed text from the object

Returns

string —

the text set in the object

getParsed()

getParsed() : string

Gets the parsed text from the object

Returns

string —

the parsed text set in the object

qparse()

qparse(  $str) : \none

Quick method to do setText(), parse() and getParsed at once

Parameters

$str

Returns

\none

staticQparse()

staticQparse(  $str) : \none

Quick static method to do setText(), parse() and getParsed at once

Parameters

$str

Returns

\none