<?php
/*=====================================================================*\
|| ###################################################################
|| # Blue Static ISSO Framework
|| # Copyright Š2002-[#]year[#] Blue Static
|| #
|| # This program is free software; you can redistribute it and/or modify
|| # it under the terms of the GNU General Public License as published by
|| # the Free Software Foundation; version [#]gpl[#] of the License.
|| #
|| # This program is distributed in the hope that it will be useful, but
|| # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|| # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|| # more details.
|| #
|| # You should have received a copy of the GNU General Public License along
|| # with this program; if not, write to the Free Software Foundation, Inc.,
|| # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
|| ###################################################################
\*=====================================================================*/

/**
* XML Parser
* xml.php
*
* @package	ISSO
*/

/**
* XML Parser
*
* This framework is a wrapper for a robust XML parser.
*
* @author		Blue Static
* @copyright	Copyright Š2002 - [#]year[#], Blue Static
* @version		$Revision$
* @package		ISSO
* 
*/
class XML
{
	/**
	* Framework registry object
	* @var	object
	* @access	private
	*/
	var $registry = null;
	
	/**
	* Parser resource
	* @var	integer
	* @access	private
	*/
	var $parser = null;
	
	/**
	* An array of function names that are to be executed for each tag name (name => function)
	* @var	array()
	* @access	private
	*/
	var $taghandler = array();
	
	/**
	* Current CDATA value
	* @var	string
	* @access	private
	*/
	var $cdata = '';
	
	/**
	* Tag stack of all open nodes
	* @var	array
	* @access	private
	*/
	var $stack = array();
	
	/**
	* Node list for all open tag attributes
	* @var	array
	* @access	private
	*/
	var $attribs = array();
	
	/**
	* Resulting parsed array
	* @var	array
	* @access	private
	*/
	var $result = array();
	
	// ###################################################################
	/**
	* Constructor
	*/
	function __construct(&$registry)
	{
		$this->registry =& $registry;
	}
	
	// ###################################################################
	/**
	* (PHP 4) Constructor
	*/
	function XML(&$registry)
	{
		$this->__construct($registry);
	}
	
	// ###################################################################
	/**
	* Parse an XML file
	*
	* @access	public
	*
	* @param	string	XML file data
	* @param	string	Parse file as UTF-8 instead of ISSO-8859-1
	*
	* @return	array	Array with all the XML data parsed
	*/
	function parse($data, $utf8 = true)
	{
		$this->stack = array();
		$this->attribs = array();
		$this->result = array();
		$this->cdata = '';
		
		if ($utf8)
		{
			$this->parser = xml_parser_create('UTF-8');
		}
		else
		{
			$this->parser = xml_parser_create('ISO-8859-1');
		}
		
		// create a new parser
		xml_set_object($this->parser, $this);
		xml_parser_set_option($this->parser, XML_OPTION_CASE_FOLDING, 0);
		xml_set_element_handler($this->parser, 'handle_tag_start', 'handle_tag_end');
		xml_set_character_data_handler($this->parser, 'handle_cdata');
		
		$this->attach_node($this->result);
		
		// parse the data and check for errors
		if (!xml_parse($this->parser, $data))
		{
			$error['code'] = xml_get_error_code($this->parser);
			$error['string'] = xml_error_string($error['code']);
			$error['line'] = xml_get_current_line_number($this->parser);
			$error['column'] = xml_get_current_column_number($this->parser);
			trigger_error("XML Error: $error[string] at line $error[line] colunn $error[column]", E_USER_ERROR);
			exit;
		}
		
		// destroy the parser
		xml_parser_free($this->parser);
		
		// done... send the results back
		return $this->result;
	}
	
	// ###################################################################
	/**
	* Process the opening location of an XML tag
	*
	* @access	private
	*
	* @param	integer	XML parser
	* @param	string	Tag name
	* @param	array	Tag attributes
	*/
	function handle_tag_start(&$parser, $name, $attrs)
	{
		// we need to keep track of indicies to monitor the last key in $this->attribs
		static $index;
		
		// trim attributes
		array_walk($attrs, 'trim');

		// existing node set
		if (isset($this->attribs["$name"]))
		{
			// node set has < 1 child nodes
			if (!isset($this->attribs["$name"][0]))
			{
				$tmp = $this->attribs["$name"];
				unset($this->attribs["$name"]);
				$this->attribs["$name"][0] = $tmp;
			}
			
			// create a new child node
			$this->attribs["$name"][ $index["$name"] ] = (array)$attrs;
			$this->attach_node($this->attribs["$name"][ $index["$name"] ]);
			$index["$name"]++;
		}
		// node set doesn't exist, so create it
		else
		{
			$this->attribs["$name"] = (array)$attrs;
			$this->attach_node($this->attribs["$name"]);
			$index["$name"] = 1;
		}
	}
	
	// ###################################################################
	/**
	* Process XML CDATA
	*
	* @access	private
	*
	* @param	integer	XML parser
	* @param	string	CDATA from tag
	*/
	function handle_cdata(&$parser, $data)
	{
		$this->cdata .= $data;
	}
	
	// ###################################################################
	/**
	* Process the closing of an XML tag
	*
	* @access	private
	*
	* @param	integer	XML parser
	* @param	string	Tag name
	*/
	function handle_tag_end(&$parser, $name)
	{
		// attach data to the node
		if (($this->cdata = trim($this->cdata)) != '')
		{
			$this->attribs['value'] = $this->cdata;
		}
		
		$this->cdata = '';
		
		// remove the node
		$this->detach_node();
	}
	
	// ###################################################################
	/**
	* Shifts the node tree
	*
	* @access	private
	*
	* @param	array	Node to place into the stack
	*/
	function attach_node(&$node)
	{
		// create a new node
		$this->stack[ sizeof($this->stack) ] =& $node;
		
		// new attributes to work with
		$this->attribs =& $node;
	}
	
	// ###################################################################
	/**
	* Unshifts the node tree
	*
	* @access	private
	*/
	function detach_node()
	{
		// drop the newest node
		unset($this->stack[ sizeof($this->stack) - 1 ]);
		
		// assign the attributes to the next newest node
		$this->attribs =& $this->stack[ sizeof($this->stack) - 1 ];
	}
	
	// ###################################################################
	/**
	* Unless a node has multiple children, there will not be a numerical
	* index for the child node. So this means that if you have variable
	* XML structure with some of the same types of nodes having one children
	* or multiple children, you'd have different things to parse. If
	* you want the node unified (as in, all single-children would be indexed
	* numerically, run this function on the node. It works on references.
	*
	* @access	 public
	*
	* @param	array	The node to int-index
	*/
	function unify_node(&$node)
	{
		if (!isset($node[0]))
		{
			$node = array($node);
		}
	}
}

/*=====================================================================*\
|| ###################################################################
|| # $HeadURL$
|| # $Id$
|| ###################################################################
\*=====================================================================*/
?>