InterJinn

Development Framework For PHP











Documentation

interJinn
Class JinnSimpleXml (EXPERIMENTAL)

public class JinnSimpleXml
extends JinnBaseService
This services implements an API for setting and retrieving simplistic information in an XML document. By simple the API expects that the content of a tag will not be a combination of text and sub-tags.

Given the simple nature of this API, no validation of the XML wil be performed against a schema or DTD. The engine presumes the XML is well-formed and follows whatever structure it is supposed to follow. Generally speaking XML data from webservices will be correct.

Example:
$xml =
    '<lev1>'."\n"
   .'  <lev2>'."\n";
   .'    <lev3>'."\n";
   .'      <lev4>'."\n";
   .'        <lev5>apple</lev5>'."\n"
   .'        <lev5 citrus="true">orange</lev5>'."\n"
   .'        <lev5>plum</lev5>'."\n"
   .'      </lev4>'."\n";
   .'    </lev3>'."\n";
   .'  </lev2>'."\n";
   .'</lev1>'."\n";

$xmlObj = &$this->getServiceRef( 'simpleXml' );
$xmlObj->parse( $xml );

//
// Prints 'apple'
//
echo $xmlObj->getValue( 'lev1/lev2/lev3/lev4/lev5' );

//
// Prints 'orange'
//
echo $xmlObj->getValue( 'lev1/lev2/lev3/lev4/lev5#1' );

//
// Puts the target path's subtree into focus.
//
$xmlObj->focus( 'lev1/lev2/lev3/lev4/lev5' );

//
// Prints 'plum'
//
echo $xmlObj->getValue( '#2' );

//
// Loops through all of the <lev5/> values and prints each
// (don't forget <lev5/> is currently in focus).
//
foreach( $xmlObj->getIndexes() as $index )
{
    echo $xmlObj->getValue( "#$index" );
}

//
// Echo's the citrus attribute for each <lev5/> entry.
//
foreach( $xmlObj->getIndexes() as $index )
{
    echo $xmlObj->getValue( "#$index@citrus" );
}

//
// Reset focus back to root.
//
$xmlObj->focusReset();

//
// Loops through all of the <lev5/> values and prints each.
//
foreach( $xmlObj->getIndexes( 'lev1/lev2/lev3/lev4/lev5' ) as $index )
{
    echo $xmlObj->getValue( "lev1/lev2/lev3/lev4/lev5#$index" );
}


Direct Known Subclasses

Method Summary
public JinnSimpleXml( )

The constructor.
protected array ___createGroup( )

Groups are used to group together nodes with the same name into an indexed lookup map.
protected array ___createNode( )

Used to construct the node tree.
public bool ___focusCriteriaRecursive( array   & node , string   tagName , string   attName =null , string   attValue =null )

Traverses the XML tree from the currently focused node and attempts to match the given criteria.
public ___getCriteriaPathsRecursive( array   & $paths , array   & $node , string   $tagName , string   $attName =null , string   $attValue =null )

Traverses the XML tree from the currently focused node and attempts to match the given criteria.
public ___jinnConstruct( )

The constructor.
protected ___nodeAddChild( array   & $mommyNode , array   & $babyNode , mixed   & $index =null )

Inserts $babyNode into the XML structure as a child of $mommyNode.
protected boolean ___nodeDelete( array   & $node )

Removes the node from the XML structure and updates any references to ensure the node's entire hierarchy is removed.
protected ___nodeDeleteChildren( array   & $node )

Removes all the children of the given node from the XML structure.
protected ___nodeGetPath( array   & $node , boolean   $absolute =false )

Used to retrieve the targetting path for a given node.
protected ___nodeSetSubTree( array   & $node , array   & $subTree , JinnSimpleXml   & $xml , boolean   $isFirst )

Updates the given $node to have the same value, attributes, and hierarchical structure as the given $subTree.
protected ___setRoot( array   & $root )

This initializes the XML structure with a valid root.
protected bool allowCopies( )

Returns true to indicate to InterJinn that multiple instances of the service may exist.
public string asInnerString( int   $pretty =0 )

Positive values for the $pretty parameter indicate that the XML should be rendered in 'pretty' mode which generally makes it more readable.
public string asRawString( int   $pretty =0 )

Positive values for the $pretty parameter indicate that the XML should be rendered in 'pretty' mode which generally makes it more readable.
public string asString( int   $pretty =0 )

Positive values for the $pretty parameter indicate that the XML should be rendered in 'pretty' mode which generally makes it more readable.
public string asStringDebug( )

This can be used to debug problems with the XML lib.
protected asStringDebugPrimitive( mixed   $node , int   $depth =0 )

Recursive function for rendering the XML structure to a debugging output hierarchy.
protected asStringPrimitive( mixed   $node , int   $pretty =0 , int   $depth =0 )

Recursive function for rendering the XML structure to a standard textual representation.
protected mixed createPath( string   $path )

Creates nodes as necessary to fulfill the requested path criteria.
public delete( string   $path =null )

Removes the node at the requested path's target.
public deleteValue( string   $path =null )

Removes the node at the requested path's target.
public doPrint( int   $pretty =0 , string   $colour =null , string   $mode =null )

This function prints the results of getPrint() directly to standard output.
public doPrintDebug( string   $colour =null , string   $mode =null )

This function prints the results of getPrintDebug() directly to standard output.
public bool elementExists( string   $path )

Traverses the path and determines if it resolves to an actual element entry in the XML structure.
public bool focus( string   $path )

Attempts to change the focus to the given path.
public bool focusCriteria( string   tagName , string   attName =null , string   attValue =null )

Traverses the XML tree from the currently focused node and attempts to match the given criteria.
public bool focusId( string   id )

Changes the focus to the the node denoted by the given unique ID.
public bool focusParent( )

Changes the focus to the currently focused element's parent if it exists (root has no parent).
public focusReset( )

Resets the currently focused element back to the XML root.
public array getChildPaths( string   $path =null )

Returns an array of sub-paths that can be used to traverse the children of the target $path in order.
public array getChildren( string   $path =null )

Retrieved element names can be used as part of a path description to dynamically retrieve XML values.
public array getCriteriaPaths( string   $tagName , string   $attName =null , string   $attValue =null )

Traverses the XML tree from the currently focused node and attempts to match the given criteria.
public string getFocusName( )

Useful for determining the name of the currently focused node.
public string getFocusPath( )

Useful for determining the path to the currently focused node.
public array getIndexes( string   $path =null )

Returns an array of valid indexes for the path's target element.
public mixed getLiteral( string   $path =null , mixed   $dValue =null )

Returns the literal found at the requested path or the given default.
public string getParentName( )

Useful for determining the name of the currently focused node's parent.
protected array getPathTarget( string   $path )

Returns an associative array consisting of a target entry and an index entry.
protected mixed getPathTargetValue( string   $path )

Returns a reference to the actual value found at the target of the path.
public string getPrint( int   $pretty =0 , string   $colour =null , string   $mode =null )

Similar to the asString() method with the exception that the XML content is formatted with indentation denoting nesting levels of sub tags.
public string getPrintDebug( string   $colour =null , string   $mode =null )

Useful for debugging problems with the XML lib.
public string getRootName( )

Useful for determining the name of the XML tree's root node.
public mixed getString( string   $path =null , mixed   $dValue =null )

Returns a string representation of the value found at the requested path or the given default.
public mixed getSubTree( string   $path =null )

Returns the subtree found at the requested path.
public string getTagName( )

Useful for determining the name of the currently focused node.
public mixed getValue( string   $path =null )

Returns the value found at the requested path.
public bool parse( string   $xml , boolean   $trim =false )

The starting point for handling an XML document.
protected array parsePath( string   $path )

Many of the JinnSimpleXml methods utilizie this method to process requested paths.
public setRootName( string   $name )

Useful for changing the name of the tree's root node.
public integer setValue( string   $path , mixed   $value )

Sets a value at the given path's target.
public bool valueExists( string   $path )

Traverses the path and determines if it resolves to an actual entry in the XML structure.

Methods Inherited from JinnBaseClassReal
JinnBaseClassReal , ___jinnConstruct , __destruct , applyCallbackRecursively , checkpoint , cleanPath , createClone , error , extractPairs , flattenPath , getBacktrace , getCharset , getCodeRoot , getCompileVar , getCompileVars , getCoreRoot , getFilename , getHttpCookieVar , getHttpCookieVars , getHttpEnvVar , getHttpEnvVars , getHttpGetOrPostVar , getHttpGetVar , getHttpGetVars , getHttpLinkVar , getHttpLinkVars , getHttpPostFile , getHttpPostFiles , getHttpPostOrGetVar , getHttpPostVar , getHttpPostVars , getHttpServerVar , getHttpServerVars , getImageBase , getInterJinnVar , getInterJinnVars , getLanguage , getLanguageDefault , getLibrary , getLibraryRef , getLoadInfo , getPageBase , getPageRoot , getPath , getPathPrefixType , getPrintData , getPrintFlat , getRunMode , getRunUid , getService , getServiceRef , getShellArg , getShellArgc , getShellArgv , getTime , getUniqueId , getVersion , getWebProfilingCategoryColour , getWebProfilingDataColour , getWebProfilingDefaultColour , halt , haltWithProfile , hashAppend , hashKeyDelete , hashKeyExists , hashKeyGet , hashKeyIsSet , hashKeySet , hashPathDelete , hashPathDeleteData , hashPathExists , hashPathGet , hashPathGetData , hashPathIsSet , hashPathSet , hashPathSetData , includeResource , isProfiling , libraryExists , localizeImage , localizePage , localizePath , logData , logFlat , makeRelativePath , markup , multilingualize , multilingualizeRef , normalizeArray , notice , overrideWarning , printData , printFlat , purgeOutputBuffers , redirect , refresh , serviceExists , setInterJinnVar , stripSlashes , stripSlashes_primitive , unwrapIfNecessary , unwrapObject , warning , wrapIfNecessary , wrapObject , xpathExists , xpathGet , xpathGetData , xpathIsSet  

Methods Inherited from JinnBaseClass
JinnBaseClass , ___jinnConstruct  

Methods Inherited from JinnBaseService
JinnBaseService , ___jinnConstruct , allowCopies , postLoadExecute  

Method Details
JinnSimpleXml

public JinnSimpleXml ( )

The constructor.

Source Code
function JinnSimpleXml()
{
    $this->___jinnConstruct();
}

___createGroup

protected array ___createGroup ( )

Returns:
Returns an initialized XML grouping structure.

Groups are used to group together nodes with the same name into an indexed lookup map. The gorup stores the node ID and the name. This is necessary to target a specific node in a sequence of like-named nodes.

Source Code
function ___createGroup()
{
    return
        array
        (
            'gid'   => ++$this->maxGid,     // ID of this group.
            'name'  => null,                // Name of group (tag name).
            'nids'  => array(),             // Array of nodes: idx => nid.
            'midx'  => 0,                   // Max node idx within group.
        );
}

___createNode

protected array ___createNode ( )

Returns:
Returns an initialized XML node structure.

Used to construct the node tree. The method will create a blank node structure and automatically assign it the next available node ID. The node is not associated witht he XML structure by this method.

Source Code
function ___createNode()
{
    return
        array
        (
            'nid'   => ++$this->maxNid,     // ID of node.
            'pid'   => 0,                   // ID of parent node.
            'gid'   => 0,                   // ID of grouping container.
            'idx'   => 0,                   // ID of node within group.
            'name'  => null,                // Tag name.
            'text'  => null,                // Textual content of the tag.
            'atts'  => array(),             // Array of attributes/values.
            'nids'  => array(),             // Array of child node IDs.
            'gids'  => array(),             // Array of child gids by tag.
        );
}

___focusCriteriaRecursive

public bool ___focusCriteriaRecursive
(
     array      & node ,
     string      tagName ,
     string      attName = null ,
     string      attValue = null
)

Parameters:
node - The node to be checked.
tagName - The name of the tag to find.
attName - The name of the attribute to find.
attValue - The value of the attribute to find.

Returns:
True if the focus was successful, otherwise false.

Traverses the XML tree from the currently focused node and attempts to match the given criteria. If a match is found then the node is focused and true is returned. Otherwise false is returned. If null is assigned to a parameter then any value will match.

Source Code
function ___focusCriteriaRecursive( &$node, $tagName, $attName=null, $attValue=null )
{
    //
    // Check if current node is a match.
    //

    $preg = false;
    if( substr( $tagName, 0, 7 ) == 'preg://' )
    {
        $preg = true;
    }

    if( $tagName === null
        ||
        (!$preg
         &&
         $node['name'] === (string)$tagName)
        ||
        ($preg
         &&
         preg_match( substr( $tagName, 7 ), $node['name'] )) )
    {
        if( $attName === null
            ||
            isset( $node['atts'][$attName] ) )
        {
            if( $attValue === null )
            {
                $this->focus = &$node;
                return true;
            }
            else
            if( $attName !== null
                &&
                $node['atts'][$attName] === (string)$attValue )
            {
                $this->focus = &$node;
                return true;
            }
            else
            {
                foreach( $node['atts'] as $key => $value )
                {
                    if( $value === (string)$attValue )
                    {
                        $this->focus = &$node;
                        return true;
                    }
                }
            }
        }
    }

    //
    // Recurse on children.
    //

    foreach( $node['nids'] as $nid )
    {
        if( ($child = &$this->nodes[$nid]) )
        {
            if( $this->___focusCriteriaRecursive(
                    $child, $tagName, $attName, $attValue ) )
            {
                return true;
            }
        }
    }

    return false;
}

___getCriteriaPathsRecursive

public ___getCriteriaPathsRecursive
(
     array      & $paths ,
     array      & $node ,
     string      $tagName ,
     string      $attName = null ,
     string      $attValue = null
)

Parameters:
$paths - The node to be checked.
$node - The node to be checked.
$tagName - The name of the tag to find.
$attName - The name of the attribute to find.
$attValue - The value of the attribute to find.

Traverses the XML tree from the currently focused node and attempts to match the given criteria. If a match is found then its targetting path is added to the $paths parameter.

Source Code
function ___getCriteriaPathsRecursive
( &$paths, &$node, $tagName, $attName=null, $attValue=null )
{
    //
    // Check if current node is a match.
    //

    $preg = false;
    if( substr( $tagName, 0, 7 ) == 'preg://' )
    {
        $preg = true;
    }

    if( $tagName === null
        ||
        (!$preg
         &&
         $node['name'] === (string)$tagName)
        ||
        ($preg
         &&
         preg_match( substr( $tagName, 7 ), $node['name'] )) )
    {
        if( $attName === null
            ||
            isset( $node['atts'][$attName] ) )
        {
            if( $attValue === null )
            {
                $paths[] = $this->___nodeGetPath( $node );
            }
            else
            if( $attName !== null
                &&
                $node['atts'][$attName] === (string)$attValue )
            {
                $paths[] = $this->___nodeGetPath( $node );
            }
            else
            {
                foreach( $node['atts'] as $key => $value )
                {
                    if( $value === (string)$attValue )
                    {
                        $paths[] = $this->___nodeGetPath( $node );
                    }
                }
            }
        }
    }

    //
    // Recurse on children.
    //

    foreach( $node['nids'] as $nid )
    {
        if( ($child = &$this->nodes[$nid]) )
        {
            $this->___getCriteriaPathsRecursive(
                $paths, $child, $tagName, $attName, $attValue );
        }
    }
}

___jinnConstruct

public ___jinnConstruct ( )

The constructor.

Source Code
function ___jinnConstruct()
{
    static $xid = 0;

    parent::___jinnConstruct();

    $this->xid = ++$xid;
}

___nodeAddChild

protected ___nodeAddChild
(
     array      & $mommyNode ,
     array      & $babyNode ,
     mixed      & $index = null
)

Parameters:
$mommyNode - The parent node to which the child will be added.
$babyNode - The child node being added to the parent.
$index - The group index for the node. When null the next available index for the group is assigned.

Inserts $babyNode into the XML structure as a child of $mommyNode. This appropriately updates the structure to properly conect the node to the parent, the node list, and an appropriate grouping.

Source Code
function ___nodeAddChild( &$mommyNode, &$babyNode, $index=null )
{
    $mommyNid = $mommyNode['nid'];

    $babyNode['pid'] = $mommyNid;

    $babyNid    = $babyNode['nid'];
    $babyName   = $babyNode['name'];
    $babyGroup  = null;

    if( isset( $mommyNode['gids'][$babyName] ) )
    {
        //
        // Retrieve existing group.
        //
        $babyNode['gid'] = $mommyNode['gids'][$babyName];
        $babyGroup = &$this->groups[$babyNode['gid']];
    }
    else
    {
        //
        // Create new group.
        //
        $babyGroup = $this->___createGroup();
        $babyGroup['name'] = $babyName;
        $babyNode['gid'] = $babyGroup['gid'];
        $this->groups[$babyNode['gid']] = &$babyGroup;
    }

    if( $index === null )
    {
        $babyNode['idx'] = $babyGroup['midx']++;
    }
    else
    {
        $babyNode['idx'] = $index;
        if( $index >= $babyGroup['midx'] )
        {
            $babyGroup['midx'] = $index + 1;
        }
    }

    $babyGroup['nids'][$babyNode['idx']] = $babyNid;

    $mommyNode['gids'][$babyName] = $babyNode['gid'];
    $mommyNode['nids'][$babyNid]  = $babyNid;

    $this->nodes[$babyNid] = &$babyNode;
}

___nodeDelete

protected boolean ___nodeDelete
(
     array      & $node
)

Parameters:
$node - The node to be deleted from the XML structure.

Returns:
Returns true if the node is successfully removed; otherwise false is returned.

Removes the node from the XML structure and updates any references to ensure the node's entire hierarchy is removed.

Source Code
function ___nodeDelete( &$node )
{
    $nid = $node['nid'];
    $idx = $node['idx'];

    if( $this->root
        &&
        $this->root['nid'] === $nid )
    {
        //
        // No sir! Won't delete root.
        //
        return false;
    }

    $this->___nodeDeleteChildren( $node );
    if( $this->focus
        &&
        $this->focus['nid'] === $nid )
    {
        unset( $this->focus );
    }

    $parent = &$this->nodes[$node['pid']];
    unset( $parent['nids'][$nid] );

    unset( $this->groups[$node['gid']]['nids'][$idx] );

    return true;
}

___nodeDeleteChildren

protected ___nodeDeleteChildren
(
     array      & $node
)

Parameters:
$node - The node for which all children will be removed from the XML structure.

Removes all the children of the given node from the XML structure.

Source Code
function ___nodeDeleteChildren( &$node )
{
    foreach( $node['nids'] as $childNid )
    {
        $this->___nodeDelete( $this->nodes[$childNid] );
    }
}

___nodeGetPath

protected ___nodeGetPath
(
     array      & $node ,
     boolean      $absolute = false
)

Parameters:
$node - The node for which the path will be retrieved.
$absolute - Whether or not to return an absolute or relative path. By default a relative path is returned.

Used to retrieve the targetting path for a given node.

Source Code
function ___nodeGetPath( $node, $absolute=false )
{
    $path = array();

    while( $node )
    {
        if( !$absolute
            &&
            $this->focus
            &&
            $this->focus['nid'] == $node['nid'] )
        {
            break;
        }

        $path[] = $node['name'].'#'.$node['idx'];

        if( $node['pid'] > 0 )
        {
            $node = $this->nodes[$node['pid']];
        }
        else
        {
            $node = null;
        }
    }

    if( $absolute || !$this->focus )
    {
        $path[] = '';
    }

    $path = array_reverse( $path );

    return implode( '/', $path );
}

___nodeSetSubTree

protected ___nodeSetSubTree
(
     array      & $node ,
     array      & $subTree ,
     JinnSimpleXml      & $xml ,
     boolean      $isFirst
)

Parameters:
$node - The node for which the value will be updated.
$subTree - The root node of the sub-tree for which the value and children will be assigned to $node.
$xml - An XML object instance to which the $subTree belongs.
$isFirst - When set to true the given $node is considered to be the first node in the recursive process for which the sub-tree value is being assigned. This has the distinction of preventing the node's name from being updated to that of the $subTree node.

Updates the given $node to have the same value, attributes, and hierarchical structure as the given $subTree. This can be used to attached entire sub trees of XML objects to other XML objects. The tag name of the recipient node is not affected by this process.

Notes
Warning:
 The tag name of the recipient node is not affected by this process.  

Source Code
function ___nodeSetSubTree( &$node, &$subTree, $xml, $isFirst=true )
{
    $this->___nodeDeleteChildren( $node );

    $node['text'] = '';
    $node['atts'] = $subTree['atts'];

    if( !$subTree )
    {
        //
        // It's a non-sub-tree so we're done.
        //

        return;
    }

    $name = $node['name'];
    if( !$isFirst
        &&
        $subTree['name'] !== $name
        &&
        $node['pid'] > 0 )
    {
        //
        // Need to re-configure group indexing by tag name.
        //

        unset( $this->groups[$node['gid']][$node['idx']] );

        $babyGroup = null;
        $mommyNode = &$this->nodes[$node['pid']];

        if( isset( $mommyNode['gids'][$name] ) )
        {
            //
            // Retrieve existing group.
            //
            $node['gid'] = $mommyNode['gids'][$name];
            $babyGroup = &$this->groups[$node['gid']];
        }
        else
        {
            //
            // Create new group.
            //
            $babyGroup = $this->___createGroup();
            $babyGroup['name'] = $name;
            $node['gid'] = $babyGroup['gid'];
            $this->groups[$node['gid']] = &$babyGroup;
            $mommyNode['gids'][$name] = $node['gid'];
        }

        $node['idx'] = $babyGroup['midx']++;
        $babyGroup['nids'][$node['idx']] = $node['nid'];
    }

    foreach( $subTree['nids'] as $nid )
    {
        //
        // Recursively set child nodes.
        //

        $child = &$xml->nodes[$nid];
        $clone = $this->___createNode();

        $clone['name'] = $child['name'];

        $this->___nodeAddChild( $node, $clone );
        $this->___nodeSetSubTree( $clone, $child, $xml, false );

        $clone['text'] = $child['text'];
        $clone['atts'] = $child['atts'];

        unset( $clone );
    }

    if( !$isFirst )
    {
        $node['name'] = $subTree['name'];
    }

    return true;
}

___setRoot

protected ___setRoot
(
     array      & $root
)

Parameters:
$root - A node to be assigned to the root of the XML structure.

This initializes the XML structure with a valid root. All other nodes will be descendents of the root node. The root node cannot have any siblings.

Source Code
function ___setRoot( &$root )
{
    $this->root  = &$root;
    $this->focus = &$root;

    $this->nodes[$root['nid']] = &$root;
}

allowCopies

protected bool allowCopies ( )

Returns:
Whether to allow multiple instances of the service.

Returns true to indicate to InterJinn that multiple instances of the service may exist.

Source Code
function allowCopies()
{
    return true;
}

asInnerString

public string asInnerString
(
     int      $pretty = 0
)

Parameters:
$pretty - Non-zero indicates the XML should be rendered in 'pretty' mode.

Returns:
The inner XML document (excludes root tag).

Positive values for the $pretty parameter indicate that the XML should be rendered in 'pretty' mode which generally makes it more readable. The actual value of this parameter when non-zero determines indentation distance in spaces for the XML tag nesting levels.

Source Code
function asInnerString( $pretty=0 )
{
    $childPaths = $this->getChildPaths();

    $innerChunks = array();
    foreach( $childPaths as $childPath )
    {
        $temp = $this->getSubTree( $childPath );
        if( $temp !== null )
        {
            if( is_string( $temp ) )
            {
                $innerChunks[] = $temp;
            }
            else
            {
                $innerChunks[] = $temp->asString( $pretty );
            }
        }
    }

    $string = implode( $pretty ? "\n" : '', $innerChunks );

    return $string;
}

asRawString

public string asRawString
(
     int      $pretty = 0
)

Parameters:
$pretty - Non-zero indicates the XML should be rendered in 'pretty' mode.

Returns:
The XML document.

Positive values for the $pretty parameter indicate that the XML should be rendered in 'pretty' mode which generally makes it more readable. The actual value of this parameter when non-zero determines indentation distance in spaces for the XML tag nesting levels. Unlike the asString() method this version will prevent entity markers from being converted back into entities.

Source Code
function asRawString( $pretty=0 )
{
    return $this->asStringPrimitive( $this->root, $pretty, 0, false );
}

asString

public string asString
(
     int      $pretty = 0
)

Parameters:
$pretty - Non-zero indicates the XML should be rendered in 'pretty' mode.

Returns:
The XML document.

Positive values for the $pretty parameter indicate that the XML should be rendered in 'pretty' mode which generally makes it more readable. The actual value of this parameter when non-zero determines indentation distance in spaces for the XML tag nesting levels.

Source Code
function asString( $pretty=0 )
{
    return $this->asStringPrimitive( $this->root, $pretty );
}

asStringDebug

public string asStringDebug ( )

Returns:
A debugging string representative of the internal structure.

This can be used to debug problems with the XML lib.

Source Code
function asStringDebug()
{
    return $this->asStringDebugPrimitive( $this->root );
}

asStringDebugPrimitive

protected asStringDebugPrimitive
(
     mixed      $node ,
     int      $depth = 0
)

Parameters:
$node - The current node being rendered to a debugging string.
$depth - The nesting depth of the given node.

Recursive function for rendering the XML structure to a debugging output hierarchy.

Source Code
function asStringDebugPrimitive( $node, $depth=0 )
{
    $tab = str_repeat( ' ', ($depth * 4) );

    $mommyName = null;
    if( $node['pid'] > 0 )
    {
        $mommy = &$this->nodes[$node['pid']];
        $mommyName = $mommy['name'];
    }

    $out =
        $tab.'nid: '.$node['nid'].' ('.$node['name'].")\n"
       .$tab.'pid: '.$node['pid'].' ('.$mommyName.")\n"
       .$tab.'gid: '.$node['gid']."\n"
       .$tab.'idx: '.$node['idx']."\n";

    $out .=
        $tab.'atts: ';

    if( $node['atts'] )
    {
        $first = true;
        foreach( $node['atts'] as $key => $value )
        {
            $pre = $tab.'>>>>: ';
            if( $first )
            {
                $first = false;
                $pre = '';
            }

            $out .= $pre.$key.' => '.$value."\n";
        }
    }
    else
    {
        $out .= "\n";
    }

    if( $node['nids'] )
    {
        $out .=
            $tab.'nids: '.implode( ', ', $node['nids'] )."\n";
    }

    if( $node['nids'] )
    {
        $out .=
            $tab.'subs:'."\n"
           .$tab.'('."\n";

        foreach( $node['gids'] as $name => $gid )
        {
            $group = &$this->groups[$gid];
            foreach( $group['nids'] as $nid )
            {
                $sub = &$this->nodes[$nid];
                $out .= $this->asStringDebugPrimitive( $sub, $depth + 1 );
            }
        }

        $out .=
            $tab.')'."\n";
    }
    else
    if( (string)$node['text'] === '' )
    {
        $out .=
            $tab.'null:'."\n";
    }
    else
    {
        $out .=
            $tab.'text: '.((string)$node['text'])."\n";
    }

    return $out."\n";
}

asStringPrimitive

protected asStringPrimitive
(
     mixed      $node ,
     int      $pretty = 0 ,
     int      $depth = 0
)

Parameters:
$node - The current node being rendered to a string.
$pretty - Non-zero indicates the XML should be rendered in 'pretty' mode.
$depth - The nesting depth of the given node.

Recursive function for rendering the XML structure to a standard textual representation.

Source Code
function asStringPrimitive( $node, $pretty=0, $depth=0 )
{
    $xml =
        str_repeat( ' ', ($depth * $pretty) )
       .'<'.$node['name'];

    foreach( $node['atts'] as $key => $value )
    {
        $xml .=
            ' '.htmlspecialchars( $key )
           .'="'.htmlspecialchars( $value ).'"';
    }

    $xml .= '>';

    $subxml = '';
    if( $node['nids'] )
    {
        foreach( $node['nids'] as $childNid )
        {
            $child = &$this->nodes[$childNid];
            $subxml .= $this->asStringPrimitive( $child, $pretty, $depth + 1 );
        }

        if( $subxml !== '' )
        {
            $xml .= "\n".$subxml;
        }
    }
    else
    {
        $xml .= htmlspecialchars( $node['text'] );
    }

    if( $subxml !== '' )
    {
        $xml .= str_repeat( ' ', ($depth * $pretty) );
    }

    $xml .=
        '</'.$node['name'].'>'.($pretty ? "\n" : '');

    return $xml;
}

createPath

protected mixed createPath
(
     string      $path
)

Parameters:
$path - The path to the desired target.

Returns:
The created or previously existing target of the given path.

Creates nodes as necessary to fulfill the requested path criteria. In addition to the normal path semantics, an index of + indicates that a new element index should be created at for the element. This is convenient for looping through a series of values that should be sequentially added to the XML structure.

Notes
See parsePath() for path semantics.  

Source Code
function createPath( $path )
{
    $this->createdIndex = null;

    if( $path === null )
    {
        if( $this->focus )
        {
            return
                array
                (
                    'node'  => &$this->focus,
                    'index' => $this->focus['idx'],
                    'att'   => null,
                );
        }

        return null;
    }

    $pathInfo = $this->parsePath( $path );

    $focus = &$this->focus;
    if( $pathInfo['root'] || !$focus )
    {
        $focus = &$this->root;
    }

    if( !$focus )
    {
        $retnull = null;
        return $retnull;
    }

    $step = null;
    foreach( $pathInfo['path'] as $step )
    {
        if( $step['name'] === '' )
        {
            if( isset( $step['indexNull'] ) )
            {
                //
                // Do nothing, we're already in focus!
                //
            }
            else
            if( $focus['pid'] > 0 )
            {
                //
                // Focus a sibling of a non-root node.
                //
                $group = &$this->groups[$focus['gid']];
                if( isset( $group['nids'][$step['index']] ) )
                {
                    $focus = &$this->nodes[$group['nids'][$step['index']]];
                }
                else
                {
                    unset( $node );
                    $node = $this->___createNode();

                    $node['pid']  = $focus['pid'];
                    $node['gid']  = $focus['gid'];
                    $node['idx']  = $step['index'];
                    $node['name'] = $focus['name'];

                    $this->nodes[$node['nid']] = &$node;
                    $group['nids'][$node['idx']] = $node['nid'];

                    if( $node['idx'] >= $group['midx'] )
                    {
                        $group['midx'] = $node['idx'] + 1;
                    }

                    $focus = &$node;
                }
            }
            else
            {
                //
                // No sir! Can't create root node siblings.
                //
                $retnull = null;
                return $retnull;
            }
        }
        else
        {
            if( isset( $focus['gids'][$step['name']] )
                &&
                isset( $this->groups[$focus['gids'][$step['name']]]
                                    ['nids'][$step['index']] ) )
            {
                $nid =
                    $this->groups
                        [$focus['gids'][$step['name']]]
                        ['nids'][$step['index']];

                $focus = &$this->nodes[$nid];
            }
            else
            {
                unset( $node );

                $node = $this->___createNode();
                $node['name'] = $step['name'];

                if( $step['index'] === '+' )
                {
                    $this->___nodeAddChild( $focus, $node );
                }
                else
                {
                    $this->___nodeAddChild(
                        $focus, $node, $step['index'] );
                }

                $focus = &$node;
            }
        }
    }

    $att = null;
    if( $step !== null )
    {
        $att = $step['att'];
        if( (string)$att !== '' )
        {
            $focus['atts'][$att] = null;
        }
    }

    $retval = array
    (
        'node'  => &$focus,
        'index' => $focus['idx'],
        'att'   => $att,
    );

    return $retval;
}

delete

public delete
(
     string      $path = null
)

Parameters:
$path - The path to the desired target.

Removes the node at the requested path's target. If the path is null then the currently focused element is removed.

Notes
Warning:
 If the element deleted is the focused node then the XML object will lose focus and all relative paths will fail until the focus is reset.  
See parsePath() for path semantics.  

Source Code
function delete( $path=null )
{
    if( ($target = $this->getPathTarget( $path )) !== null )
    {
        if( (string)$target['att'] === '' )
        {
            return $this->___nodeDelete( $target['node'] );
        }

        unset( $target['node']['atts'][$target['att']] );

        return true;
    }

    return false;
}

deleteValue

public deleteValue
(
     string      $path = null
)

Parameters:
$path - The path to the desired target.

Removes the node at the requested path's target. If the path is null then the currently focused element is removed.

Notes
Warning:
 If the element deleted is the focused node then the XML object will lose focus and all relative paths will fail until the focus is reset.  
This is an alias for the delete() method.  

Source Code
function deleteValue( $path=null )
{
    return $this->delete( $path );
}

doPrint

public doPrint
(
     int      $pretty = 0 ,
     string      $colour = null ,
     string      $mode = null
)

Parameters:
$pretty - When set to a positive integer value it enables "pretty" rendering of the XML content with indentation width determined by the value.
$colour - A colour string compatible with CSS color attribute.
$mode - A string denoting in what mode to render the output. Supported modes are the same as the run mode types (currently 'shell' and 'web'). The default is to use the current run mode.

This function prints the results of getPrint() directly to standard output.

Source Code
function doPrint( $pretty=false, $colour=null, $mode=null )
{
    echo
        $this->getPrintData(
            $this->asString( $pretty ), $colour, $mode );
}

doPrintDebug

public doPrintDebug
(
     string      $colour = null ,
     string      $mode = null
)

Parameters:
$colour - A colour string compatible with CSS color attribute.
$mode - A string denoting in what mode to render the output. Supported modes are the same as the run mode types (currently 'shell' and 'web'). The default is to use the current run mode.

This function prints the results of getPrintDebug() directly to standard output.

Source Code
function doPrintDebug( $colour=null, $mode=null  )
{
    echo $this->getPrintDebug( $colour, $mode );
}

elementExists

public bool elementExists
(
     string      $path
)

Parameters:
$path - The path to the desired target.

Returns:
True if the path resolves to an existing element, otherwise false.

Traverses the path and determines if it resolves to an actual element entry in the XML structure.

Notes
Contrast this to valueExists() which also checks for a specific index.  
See parsePath() for path semantics.  

Source Code
function elementExists( $path )
{
    if( $this->getPathTarget( $path ) === null )
    {
        return false;
    }

    return true;
}

focus

public bool focus
(
     string      $path
)

Parameters:
$path - The path to the desired target.

Returns:
True if the focus was successful, otherwise false.

Attempts to change the focus to the given path. The focus feature is extremely convenient for optimizing data access speed and shortening path sequences when working with specific XML subtree sections.

Example:
//
// Long and cumbersome lookup which degrades code readability:
//

$indexes = $xmlObj->getIndexes( 'a/b/c/d/e/f/g/h' );
foreach( $indexes as $i )
{
    $name   = $xmlObj->getIndexes( "a/b/c/d/e/f/g/h#$i/name" );
    $author = $xmlObj->getIndexes( "a/b/c/d/e/f/g/h#$i/author" );
    $price  = $xmlObj->getIndexes( "a/b/c/d/e/f/g/h#$i/price" );

    echo "Book: $price<br />"
        ."Author: $author<br />"
        ."Price: $price<br />";
}

//
// Better version but still inefficient since the paths are still
// searched on each request.
//

$path = 'a/b/c/d/e/f/g/h';
$indexes = $xmlObj->getIndexes( $path );
foreach( $indexes as $i )
{
    $name   = $xmlObj->getIndexes( "$path#$i/name" );
    $author = $xmlObj->getIndexes( "$path#$i/author" );
    $price  = $xmlObj->getIndexes( "$path#$i/price" );

    echo "Book: $price<br />"
        ."Author: $author<br />"
        ."Price: $price<br />";
}

//
// Optimal solution since the path is shortened and there's no
// need to constantly pass a $path variable.
//

$xmlObj->focus( 'a/b/c/d/e/f/g/h' );
$indexes = $xmlObj->getIndexes();
foreach( $indexes as $i )
{
    $name   = $xmlObj->getIndexes( "#$i/name" );
    $author = $xmlObj->getIndexes( "#$i/author" );
    $price  = $xmlObj->getIndexes( "#$i/price" );

    echo "Book: $price<br />"
        ."Author: $author<br />"
        ."Price: $price<br />";
}


Notes
See parsePath() for path semantics.  

Source Code
function focus( $path )
{
    $target = $this->getPathTarget( $path );

    if( $target !== null )
    {
        $this->focus = &$target['node'];
        return true;
    }

    return false;
}

focusCriteria

public bool focusCriteria
(
     string      tagName ,
     string      attName = null ,
     string      attValue = null
)

Parameters:
tagName - The name of the tag to find.
attName - The name of the attribute to find.
attValue - The value of the attribute to find.

Returns:
True if the focus was successful, otherwise false.

Traverses the XML tree from the currently focused node and attempts to match the given criteria. If a match is found then the node is focused and true is returned. Otherwise false is returned. If null is assigned to a parameter then any value will match.

Source Code
function focusCriteria( $tagName, $attName=null, $attValue=null )
{
    return
        $this->___focusCriteriaRecursive(
            $this->focus, $tagName, $attName, $attValue );
}

focusId

public bool focusId
(
     string      id
)

Parameters:
id - The unique ID of an XML node to focus.

Returns:
True if the focus was successful, otherwise false.

Changes the focus to the the node denoted by the given unique ID.

Source Code
function focusId( $id )
{
    if( isset( $this->idMap[$id] ) )
    {
        $this->focus = &$this->idMap[$id];
        return true;
    }

    return false;
}

focusParent

public bool focusParent ( )

Returns:
True if the focus was successful, otherwise false.

Changes the focus to the currently focused element's parent if it exists (root has no parent).

Source Code
function focusParent()
{
    if( !$this->focus )
    {
        return false;
    }

    if( $this->focus['pid'] > 0 )
    {
        $this->focus = &$this->nodes[$this->focus['pid']];
        return true;
    }

    return false;
}

focusReset

public focusReset ( )

Resets the currently focused element back to the XML root.

Source Code
function focusReset()
{
    $this->focus = &$this->root;
}

getChildPaths

public array getChildPaths
(
     string      $path = null
)

Parameters:
$path - The path to the desired target. If the path is null then the currently focused element and index is used.

Returns:
An array of valid sub-paths that represent each child found at the target $path and in the order found.

Returns an array of sub-paths that can be used to traverse the children of the target $path in order.

Notes
See parsePath() for path semantics.  

Source Code
function getChildPaths( $path=null )
{
    $target = $this->getPathTarget( $path );

    if( !$target
        ||
        !$target['node']
        ||
        !($nids = $target['node']['nids']) )
    {
        return array();
    }

    $paths = array();
    foreach( $nids as $nid )
    {
        $node = &$this->nodes[$nid];
        $paths[] = $node['name'].'#'.$node['idx'];
    }

    return $paths;
}

getChildren

public array getChildren
(
     string      $path = null
)

Parameters:
$path - The path to the desired target. If the path is null then the currently focused element and index is used.

Returns:
An array consisting of the element names for the direct children of the path's target element.

Retrieved element names can be used as part of a path description to dynamically retrieve XML values.

Notes
See parsePath() for path semantics.  

Source Code
function getChildren( $path=null )
{
    $target = $this->getPathTarget( $path );

    if( $target
        &&
        $target['node']
        &&
        $target['node']['gids'] )
    {
        return array_keys( $target['node']['gids'] );
    }

    return array();
}

getCriteriaPaths

public array getCriteriaPaths
(
     string      $tagName ,
     string      $attName = null ,
     string      $attValue = null
)

Parameters:
$tagName - The name of the tag to find.
$attName - The name of the attribute to find.
$attValue - The value of the attribute to find.

Returns:
An array of targetting paths to any nodes matching the criteria.

Traverses the XML tree from the currently focused node and attempts to match the given criteria. If a match is found then its targetting path is added to the array of matches.

Source Code
function getCriteriaPaths( $tagName, $attName=null, $attValue=null )
{
    $paths = array();

    $this->___getCriteriaPathsRecursive(
        $paths, $this->focus, $tagName, $attName, $attValue, $paths );

    return $paths;
}

getFocusName

public string getFocusName ( )

Returns:
The name of the currently focused node.

Useful for determining the name of the currently focused node.

Source Code
function getFocusName()
{
    if( $this->focus )
    {
        return $this->focus['name'];
    }

    return null;
}

getFocusPath

public string getFocusPath ( )

Returns:
The path to the currently focused node.

Useful for determining the path to the currently focused node.

Source Code
function getFocusPath()
{
    if( !$this->focus )
    {
        return null;
    }

    $focus = &$this->focus;

    $path = array();
    do
    {
        $path[] = $focus['name'].'#'.$focus['idx'];

        if( $focus['pid'] > 0 )
        {
            $focus = $this->nodes[$focus['pid']];
        }
        else
        {
            unset( $focus );
            $focus = null;
        }
    }
    while( $focus );

    return '/'.implode( '/', array_reverse( $path ) );
}

getIndexes

public array getIndexes
(
     string      $path = null
)

Parameters:
$path - The path to the desired target. If the path is null then the currently focused element and index is used.

Returns:
An array of valid indexes for the requested path's element.

Returns an array of valid indexes for the path's target element. This is preferrable than assuming sequentially indexed entries since some indexes may or may not exist depending on set and delete operations on the XML structure. The indexes can then be used as part of a path description.

Notes
See parsePath() for path semantics.  

Source Code
function getIndexes( $path=null )
{
    $path = preg_replace( '=@[^@/]*$=', '', $path );
    $path = preg_replace( '=#[^#/]*$=', '', $path );
    $path = $path.'#?';

    if( ($target = $this->getPathTarget( $path )) === null )
    {
        return array();
    }

    $info = array
    (
        'groupId' => $target['node']['gid'],
        'group'   => $this->groups[$target['node']['gid']],
        'nids'    => $this->groups[$target['node']['gid']]['nids'],
    );

    return array_keys( $this->groups[$target['node']['gid']]['nids'] );
}

getLiteral

public mixed getLiteral
(
     string      $path = null ,
     mixed      $dValue = null
)

Parameters:
$path - The path to the desired target.
$dValue - A default value to return if the path does not point to a literal.

Returns:
The literal found at the given path otherwise the default.

Returns the literal found at the requested path or the given default. If the path is null then the currently focused element and index is used. A literal is a string value and not a tag subtree.

Notes
See parsePath() for path semantics.  

Source Code
function getLiteral( $path=null, $dValue=null )
{
    if( ($value = $this->getPathTargetValue( $path )) === null )
    {
        return $dValue;
    }

    if( !is_string( $value ) )
    {
        return $dValue;
    }

    return $value;
}

getParentName

public string getParentName ( )

Returns:
The name of the currently focused node's parent.

Useful for determining the name of the currently focused node's parent.

Source Code
function getParentName( $path=null )
{
    if( $path === null )
    {
        if( $this->focus
            &&
            $this->focus['pid'] > 0 )
        {
            $parent = &$this->nodes[$this->focus['pid']];
            return $parent['name'];
        }
    }
    else
    {
        if( ($target = $this->getPathTarget( $path )) )
        {
            $parent = &$this->nodes[$target['node']['pid']];
            return $parent['name'];
        }
    }

    return null;
}

getPathTarget

protected array getPathTarget
(
     string      $path
)

Parameters:
$path - The path to the desired target.

Returns:
The target info indicated by the given path.

Returns an associative array consisting of a target entry and an index entry. The target entry is a reference to the target element and the index entry is the index of the specific element sequence. The null value is returned on path failure. A special index of '?' may be used to have the first valid element targetted regardless of its actual index. This feature is specifically used by the getIndexes() method to retrieve a valid node in a group for which it wants the indexes of all the available nodes in the group.

Notes
See parsePath() for path semantics.  

Source Code
function getPathTarget( $path )
{
    $pathInfo = $this->parsePath( $path );

    $focus = &$this->focus;
    if( $pathInfo['root'] || !$focus )
    {
        $focus = &$this->root;
    }

    if( !$focus )
    {
        return null;
    }

    $step = null;
    foreach( $pathInfo['path'] as $step )
    {
        if( $step['name'] === '' )
        {
            if( isset( $step['indexNull'] ) )
            {
                //
                // Do nothing, we're already in focus!
                //
            }
            else
            if( $focus['pid'] > 0 )
            {
                //
                // Focus a sibling of a non-root node.
                //
                $group = &$this->groups[$focus['gid']];
                if( $step['index'] === '?' )
                {
                    if( $group['nids'] )
                    {
                        $tnid = array_values( $group['nids'] );
                        $tnid = $tnid[0];
                        $focus = &$this->nodes[$tnid];
                    }
                    else
                    {
                        return null;
                    }
                }
                else
                if( isset( $group['nids'][$step['index']] ) )
                {
                    $focus =
                        &$this->nodes[$group['nids'][$step['index']]];
                }
                else
                {
                    return null;
                }
            }
            else
            {
                return null;
            }
        }
        else
        {
            if( isset( $focus['gids'][$step['name']] ) )
            {
                if( $step['index'] === '?' )
                {
                    $tgid = $focus['gids'][$step['name']];
                    $group = &$this->groups[$tgid];

                    $tnid = array_values( $group['nids'] );
                    $tnid = $tnid[0];
                    $focus = &$this->nodes[$tnid];
                }
                else
                if( isset( $this->groups
                                [$focus['gids'][$step['name']]]
                                ['nids'][$step['index']] ) )
                {
                    $nid =
                        $this->groups
                            [$focus['gids'][$step['name']]]
                            ['nids'][$step['index']];

                    $focus = &$this->nodes[$nid];
                }
                else
                {
                    return null;
                }
            }
            else
            {
                return null;
            }
        }
    }

    $att = null;
    if( $step !== null )
    {
        $att = $step['att'];
    }

    $retval = array
    (
        'node'  => &$focus,
        'index' => $focus['idx'],
        'att'   => $att,
    );

    return $retval;
}

getPathTargetValue

protected mixed getPathTargetValue
(
     string      $path
)

Parameters:
$path - The path to the desired target.

Returns:
The actual value at the requested path.

Returns a reference to the actual value found at the target of the path. If the path is invalid then null is returned.

Notes
See parsePath() for path semantics.  

Source Code
function getPathTargetValue( $path, $default=null )
{
    if( ($target = $this->getPathTarget( $path )) === null )
    {
        //
        // No target.
        //
        return $default;
    }

    if( $target['att'] !== null
        &&
        $target['att'] !== '' )
    {
        //
        // Returning an attribute value.
        //
        if( $target['att'] === '*' )
        {
            return $target['node']['atts'];
        }
        else
        if( isset( $target['node']['atts'][$target['att']] ) )
        {
            return $target['node']['atts'][$target['att']];
        }

        return $default;
    }

    if( !$target['node']['nids'] )
    {
        //
        // Returning the literal text.
        //
        return $target['node']['text'];
    }

    //
    // Returning a subtree.
    //
    $subTree = new JinnSimpleXml();

    $subTree->maxNid        = &$this->maxNid;
    $subTree->maxGid        = &$this->maxGid;
    $subTree->maxSid        = &$this->maxSid;
    $subTree->nodes         = &$this->nodes ;
    $subTree->groups        = &$this->groups;

    $subTree->root  = &$target['node'];
    $subTree->focus = &$target['node'];

    return $subTree;
}

getPrint

public string getPrint
(
     int      $pretty = 0 ,
     string      $colour = null ,
     string      $mode = null
)

Parameters:
$pretty - When set to a positive integer value it enables "pretty" rendering of the XML content with indentation width determined by the value.
$colour - A colour string compatible with CSS color attribute.
$mode - A string denoting in what mode to render the output. Supported modes are the same as the run mode types (currently 'shell' and 'web'). The default is to use the current run mode.

Returns:
The XML content formatted to be more visually appealing.

Similar to the asString() method with the exception that the XML content is formatted with indentation denoting nesting levels of sub tags.

Source Code
function getPrint( $pretty=false, $colour=null, $mode=null )
{
    return
        $this->getPrintData(
            $this->asString( $pretty ), $colour, $mode );
}

getPrintDebug

public string getPrintDebug
(
     string      $colour = null ,
     string      $mode = null
)

Parameters:
$colour - A colour string compatible with CSS color attribute.
$mode - A string denoting in what mode to render the output. Supported modes are the same as the run mode types (currently 'shell' and 'web'). The default is to use the current run mode.

Returns:
A string representation of the internal structure of the XML data.

Useful for debugging problems with the XML lib. Since the engine uses IDs that point into a linear array of XML nodes, the representation cannot easily be gleaned using the traditional JinnBaseClassReal::getPrintData().

Source Code
function getPrintDebug( $colour=null, $mode=null )
{
    return $this->getPrintData( $this->asStringDebug(), $colour, $mode );
}

getRootName

public string getRootName ( )

Returns:
The name of the tree's root node.

Useful for determining the name of the XML tree's root node.

Source Code
function getRootName()
{
    if( $this->root )
    {
        return $this->root['name'];
    }

    return null;
}

getString

public mixed getString
(
     string      $path = null ,
     mixed      $dValue = null
)

Parameters:
$path - The path to the desired target.
$dValue - A default value to return if the path does not exist.

Returns:
A string representation of whatever is found at the path, otherwise the default.

Returns a string representation of the value found at the requested path or the given default. If a node is found then its XML is returned as a string. If the path is null then the currently focused element and index is used. A literal is a string value and not a tag subtree.

Notes
See parsePath() for path semantics.  

Source Code
function getString( $path=null, $dValue='' )
{
    if( ($value = $this->getPathTargetValue( $path )) === null )
    {
        return $dValue;
    }

    if( is_string( $value ) )
    {
        $string = $value;
    }
    else
    {
        $string = $value->asInnerString();
    }

    return $string;
}

getSubTree

public mixed getSubTree
(
     string      $path = null
)

Parameters:
$path - The path to the desired target.

Returns:
The subtree found at the given path.

Returns the subtree found at the requested path. If the path is null then the currently focused element and index is used.

Notes
See parsePath() for path semantics.  

Source Code
function getSubTree( $path=null )
{
    if( ($target = $this->getPathTarget( $path )) === null )
    {
        //
        // No target.
        //
        return null;
    }

    //
    // Returning a subtree.
    //
    $subTree = new JinnSimpleXml();

    $subTree->maxNid        = &$this->maxNid;
    $subTree->maxGid        = &$this->maxGid;
    $subTree->maxSid        = &$this->maxSid;
    $subTree->nodes         = &$this->nodes ;
    $subTree->groups        = &$this->groups;

    $subTree->root  = &$target['node'];
    $subTree->focus = &$target['node'];

    return $subTree;
}

getTagName

public string getTagName ( )

Returns:
The name of the currently focused node's parent.

Useful for determining the name of the currently focused node.

Source Code
function getTagName( $path=null )
{
    if( $path === null )
    {
        if( $this->focus
            &&
            $this->focus['nid'] > 0 )
        {
            return $this->focus['name'];
        }
    }
    else
    {
        if( ($target = $this->getPathTarget( $path )) )
        {
            return $target['node']['name'];
        }
    }

    return null;
}

getValue

public mixed getValue
(
     string      $path = null
)

Parameters:
$path - The path to the desired target.

Returns:
The value found at the given path.

Returns the value found at the requested path. If the path is null then the currently focused element and index is used.

Notes
See parsePath() for path semantics.  

Source Code
function getValue( $path=null, $dValue=null )
{
    return $this->getPathTargetValue( $path, $dValue );
}

parse

public bool parse
(
     string      $xml ,
     boolean      $trim = false
)

Parameters:
$xml - The XML document to be parsed.
$trim - When set to true the content of parsed tags will have whitespace trimmed.

Returns:
True if the parse was successful, otherwise false.

The starting point for handling an XML document. The document must first be parsed so that internal data structures can be instantiated.

Source Code
function parse( $xml, $trim=false )
{
    $this->xid = null;

    $this->maxNid = 0;            // Max node ID.
    $this->maxGid = 0;            // Max group ID.
    $this->maxSid = 0;            // Max step ID.

    $this->nodes  = array();      // Linear map of nodes.
    $this->groups = array();      // Linear map of groups.

    unset( $this->root );
    $this->root  = null;          // The root node.

    unset( $this->focus );
    $this->focus = null;          // The node currently in focus.

    $this->createdIndex = null;   // Index of last auto created node.

    if( (string)$xml === '' )
    {
        $status = false;
    }
    else
    {
        $parser = new JinnSimpleXmlParser();

        $parser->generateWarnings = $this->generateWarnings;

        if( ($status = $parser->parse( $this, $xml, $trim )) )
        {
            if( ($this->focus = &$this->root) === null )
            {
                $status = false;
            }
        }
    }

    return $status;
}

parsePath

protected array parsePath
(
     string      $path
)

Parameters:
$path - A simple XML path to access the nodes of the XML structure.

Returns:
An array of individual path steps.

Many of the JinnSimpleXml methods utilizie this method to process requested paths. The format of a path is quite simple as is illustrated by the regular expression below:

((elementName)?(#index)?)(/((elementName)?(#index)?)))*

If you are not familiar with regular expressions then suffice to say that each step in the path consists of an element name and an index separated by a comma. Both the element name and the index are optional, and if no index is provided then the comma may be omitted. If the element name is not given then the last element in the path is used (this will be th element in focus if it is the first step in the path). If no index is given then an index of 0 is presumed. Completely empty path steps are ignored which allows for easier dynamic path syntax since a#/b/c#2/d is semantically identical to //a#/b/c#2//d///.

Source Code
function parsePath( $path )
{
    $root  = false;
    $step  = null;
    $steps = array();

    if( substr( $path, 0, 1 ) === '/' )
    {
        $root = true;
    }

    $pathBits = explode( '/', $path );
    foreach( $pathBits as $pathBit )
    {
        if( ($pathBit = trim( $pathBit )) === '' )
        {
            continue;
        }

        if( preg_match(
                '=^([^#@]*)?(#([^@]*))?(@(.*))?$=', $pathBit, $subBits ) )
        {
            $step = array();

            $step['name']  = trim( $subBits[1] );
            $step['index'] = trim( isset( $subBits[3] ) ? $subBits[3] : '' );
            $step['att']   = trim( isset( $subBits[5] ) ? $subBits[5] : '' );

            if( $step['index'] == '' )
            {
                $step['index'] = 0;
                $step['indexNull'] = true;
            }

            $steps[] = $step;
        }
    }

    if( $root )
    {
        if( $this->root
            &&
            $this->root['name'] == $steps[0]['name'] )
        {
            $steps[0]['name'] = '';
        }
    }

    return
        array
        (
            'root' => $root,
            'path' => $steps,
        );
}

setRootName

public setRootName
(
     string      $name
)

Parameters:
$name - A new name for the tree's root node.

Useful for changing the name of the tree's root node.

Source Code
function setRootName( $name )
{
    if( $this->root )
    {
        $this->root['name'] = $name;
        return true;
    }

    return false;
}

setValue

public integer setValue
(
     string      $path ,
     mixed      $value
)

Parameters:
$path - The path to the desired target.
$value - The value to set the target of the given path.

Returns:
If the special + index is used to denote creation of a new node, then this will return the index of the newly created node. Otherwise null is returned.

Sets a value at the given path's target. If the path doesn't exist, then the necessary elements will be created to facilitate the new value. If the path is null then the currently focused element and index is used. In addition to the normal path semantics, an index of + indicates that a new element index should be created for the element. This is convenient for looping through a series of values that should be sequentially added to the XML structure.

Notes
See parsePath() for path semantics.  

Source Code
function setValue( $path, $value )
{
    if( !($target = $this->createPath( $path )) )
    {
        return false;
    }

    if( is_object( $value )
        &&
        get_class( $value ) === get_class( $this ) )
    {
        $this->___nodeSetSubTree(
            $target['node'], $value->root, $value );
    }
    else
    {
        if( (string)$target['att'] !== '' )
        {
            $target['node']['atts'][$target['att']] = (string)$value;
        }
        else
        {
            $target['node']['text'] = (string)$value;
        }
    }

    return $target['index'];
}

valueExists

public bool valueExists
(
     string      $path
)

Parameters:
$path - The path to the desired target.

Returns:
True if the path resolves to an existing element and index, otherwise false.

Traverses the path and determines if it resolves to an actual entry in the XML structure.

Notes
Contrast this to elementExists() which doesn't check for a specific index.  
See parsePath() for path semantics.  

Source Code
function valueExists( $path )
{
    if( $this->getPathTargetValue( $path ) === null )
    {
        return false;
    }

    return true;
}


Copyright © 2001-2009 Robert Cummings
All Rights Reserved