## 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:

          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 &quot;fox&quot; 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.