IV. API Reference
[ Previous: A. Alphabetical Function List | Next: C. Language-Behavior Functions ]
B. Core Parsing Functions
BBCode::BBCode ( )
This is the constructor for the BBCode object. It assigns default values
to all settings and creates all attached objects like the BBCodeLibrary object.
Parameters: None.
Return Value: None.
string BBCode::Parse ( string $string )
This function is the public interface to the core BBCode
parser; supply this with BBCode as input, and it will return that BBCode converted to HTML.
Parameters:
- string: The string to be converted from BBCode to HTML.
Return Value: A string containing HTML converted from the input BBCode.
string BBCode::DoTag ( string $action , string $tag_name ,
string $default_value , array $params , string $contents )
This function is called by the parser to check tags and to convert tags into HTML.
It is called at most twice for each tag. Normally, it dispatches the checking/conversion job to
other functions, like library functions and callback functions, but you can override this
behavior by inheriting the BBCode class and overriding this function.
Parameters:
- action: One of BBCODE_CHECK or BBCODE_OUTPUT, depending
on the task to be performed. If this is BBCODE_CHECK, DoTag() must return
true if the inputs are acceptable, or false if the inputs are unacceptable;
if this is BBCODE_OUTPUT, DoTag() must return an HTML string that contains
the converted output of this tag.
- tag_name: The name of the tag being processed, without surrounding brackets
or an end-tag slash (/), as in "b" or "quote".
- default_value: The default value of the tag. The default value is the
value assigned to the tag name itself; for example, in [quote=John], the default
value is "John", but in [quote name=John] or [b], the default
value is the empty string.
- params: This is an array of key => value parameters given in the tag.
For example, in the tag [tag="foo" bar="baz" chocolate="good"], this array would be:
<![CDATA[ array(
"_name" => "tag",
"_default" => "foo",
"bar" => "baz",
"chocolate" => "good",
);]]>
The "_name" and "_default" parameters will always be present in this
array, and will always contain the same values as $tag_name and $default_value.
- contents: This parameter is only valid during BBCODE_OUTPUT;
during BBCODE_CHECK it will always be the empty string. This parameter contains
the "contents" of the tag, the text between the start tag and its matching end tag. For
example, with this input:
[b]The quick brown "fox" jumps over the lazy dog.[/b]
during BBCODE_OUTPUT, the $contents parameter will be set to:
The quick brown "fox" jumps over the lazy dog.
This parameter is always either the empty string or fully-validated HTML contents.
Return Value: For BBCODE_CHECK, this must return true if
the default value and parameters are acceptable, or false if they're malformed. For
BBCODE_OUTPUT, this must return clean HTML output text.
Warning: This function is part of NBBC's internal parser. It is exposed
and documented so that you can inherit and override its behavior if you want, should
you want exotic tag processing that NBBC does not perform by default; however,
be aware that by changing this you are changing NBBC's internals, so be careful.
void BBCode::SetDebug ( bool $enable )
This function enables NBBC's built-in debug mode. When in debug mode,
NBBC will dump huge quantities of data to the browser to indicate what it is doing
when it parses a given chunk of input (it's not unusual for a single line of BBCode input
to produce several pages of debug output). This is useful if you think NBBC is
misbehaving, or if you're adding a tag of your own and trying to figure out why it is or
is not working correctly. You should not enable debug mode in production environments.
Parameters:
- enable: Whether to turn debug mode on or off; if this parameter is true,
debug mode will be enabled and huge quantities of debugging information will be dumped to the
browser; if this parameter is false, no debugging information will be displayed.
Note: Debug mode is disabled by default, and is only available if
you use the multi-file version of NBBC (nbbc_main.php, nbbc_parse.php,
nbbc_lex.php, etc.): In the compressed version of NBBC (nbbc.php),
all debugging code has been removed to make the code smaller and faster. This function
and GetDebug() still both exist in the compressed version, but regardless of the state
of the debug flag, compressed NBBC will not display any debugging information.
bool BBCode::GetDebug ( )
This function returns the current state of NBBC's built-in
debug mode.
See
SetDebug() for more details.
Return values: Returns true or false, depending on
whether debug mode is enabled.
[ Previous: A. Alphabetical Function List | Next: C. Language-Behavior Functions ]
Copyright © 2010, the Phantom Inker. All rights reserved.