sdParse is a PHP class used to parse a text string looking for commands.  Each command found is replaced by the text returned by an associated callback function.  For example, the command "{sdMacros logoSmall left/}" might be replaced by the HTML code to generate a logo (go to sdMacros for examples like this, or to download sdMacros to see how an extension uses sdParse).

sdParse is free!  But, feel free to donate if you like it! 

 

Download sdParse here: download sdParse

 

The sdParse command syntax is analogous to XML:

Command Syntax:

{tag [arg1] [arg2] ...}value{/tag}

{tag [arg1] [arg2] .../}

  • There are two syntaxes, an opening and closing tag with a value between, and a self-closing tag with no value.
  • The closing tag is indicated by a "/" preceding the tag name.
  • A self-closing tag is indicate by a "/" preceding the closing bracket.
  • The opening tag may contain any number of arguments separated by white-space.
  • If an argument contains white-space, the argument must be delimited with quotation marks (").
  • Commands may be nested within each other, but must be well-formed.
  • Other delimiters may be used other than "{}".

sdParse was developed for use in Joomla extensions but is not limited to them.  It is currently used by both sdMacros and gCalMarkup.

The syntax of the handleTags() function is as follows:

Description:

string handleTags( string $text, string $delimiters, array $tags, callback $callbacks, mixed $callbackData, bool $tagsOnly )

  • The handleTags() function parses the $text string looking for the commands contained in the $tags array and within nested delimiters.  Each command (delimiters, tag and any arguments) is replaced by the text returned by the associated function in the $callbacks array.

Parameters:

  • string $text - a string containing command tags surround by delmiters.
  • string $delimiters - a string containing the starting and ending tag delimiters.  The starting delimiter is the first character in the string ($delmiter[0]), and the ending delimiter is the second character in the string ($delmiter[1]).  Any other characters in the string are ignored.
  • array $tags - an array of strings with each string representing one of the command tags to be searched for.  Each command tag in the array must have a corresponding callback function in the $callbacks array.
  • callback $callbacks - an array of callback objects, each pointing to a function that returns a string which is used to replace the matched command (including the delimiters).
  • mixed $callbackData -an optional additional object that is passed to each callback function.  It normally contains data used to create the replacement string.
  • boolean $tagsOnly - if false, the source text string is returned along with all commands replaced.  If true, only the replaced commands are returned, any text between the commands will be removed.  This is typically used with nested macros where only the replaced internal macros are desired.  e.g. they might have undesired HTML surrounding them that was added by a text editor.

Return Value:

  • Returns a string containing the modified version of the input text string.  Any matched delimiters and tags are replaced with the text provided by the tags callback function.

 

This syntax of the callback functions is as follows:

Description:

string callbackFunction( array $commandArgs, string $commandValue, mixed $callbackData, array $command )

Parameters:

  • array $commandArgs - an array of strings, each containing one of the command tag arguments.  If an argument was a quoted string the quotes have been removed.
  • string $commandValue - a string containing any text between the opening and closing tags.  If the tag was a ?? ?? tag this will be an empty string.
  • mixed $callbackData - the optional $callbackData passed to the handleTags() function
  • array $command - an internal array from the handleTags() function containing information about the current command.

Return Value:

  • Returns a string containing the string used to replace the matched command tag