xpathexpression.h

简单的xml解析类

//************************************************************************************************************************** 
//* Blue Xml Extension
//* Copyright (c) 2002-2004 Josh Harler
//* 
//* Blue - General Purpose C++ Library
//* Copyright (c) 2002-2004 Josh Harler
//* 
//* This software is provided 'as-is', without any express or implied warranty. In no event
//* will the authors be held liable for any damages arising from the use of this software.
//* 
//* Permission is granted to anyone to use this software for any purpose, including commercial
//* applications, and to alter it and redistribute it freely, subject to the following restrictions:
//* 
//* 	1. The origin of this software must not be misrepresented; you must not claim that you
//* 	wrote the original software. If you use this software in a product, an acknowledgment in the
//* 	product documentation would be appreciated but is not required.
//* 
//* 	2. Altered source versions must be plainly marked as such, and must not be misrepresented as
//* 	being the original software.
//* 
//* 	3. This notice may not be removed or altered from any source distribution.
//*
//*
//* file   Blue/Extension/Xml/XPathExpression.h
//**

#ifndef __blue_ext_xml_XPathExpression_h_included__
#define __blue_ext_xml_XPathExpression_h_included__

// Public Headers ==========================================================================================================

#include "Blue/Extension/Xml/DomNodes.h"


// Public Defines/Enums/Typedefs/Etc. ======================================================================================

// Public Classes/Structs ==================================================================================================

namespace blue {
namespace ext {
namespace xml {

	/***
	 * Forward Declarations
	 */
	class XPathToken;
	class XPathFunction;
	class XPathPredicate;



	/**
	 * \class XPathExpression
	 * \brief Resolves an XPath expression.
	 * \ingroup Xml
	 *
	 * XPath is for Xml files as SQL is for relational databases.
	 * Essentially, XPath is a way to query the Xml file and return
	 * nodes that match the condition of the XPath expression.
	 *
	 * You can read the official XPath specs here:
	 *     http://www.w3.org/TR/xpath
	 *
	 * An excellent XPath tutorial can be found here:
	 *     http://www.zvon.org/xxl/XPathTutorial/General/examples.html
	 *
	 */
	class BLUE_EXPORT_XML XPathExpression
	{
	public:
		// ===========================================================
		//  creation/destruction
		// ===========================================================

		/** Constructor. */
		XPathExpression();
		/** Constructor. */
		XPathExpression( DomNode* root );

		/** Destructor. */
		~XPathExpression();


		// ===========================================================
		//  query
		// ===========================================================

		/**
		 * Returns the node being used a the root node for all
		 * expressions.
		 */
		DomNode* getRootNode();
		/** overload. */
		const DomNode* getRootNode() const;

		/**
		 * Returns a pointer to the requested function.
		 */
		XPathFunction* getFunction( String function );
		/** overload. */
		const XPathFunction* getFunction( String function ) const;


		/**
		 * Returns the nodes that match the given expression.
		 */
		Array<DomNode*> findNodes( String xpathExpr );
		/** overload. */
		const Array<DomNode*> findNodes( String xpathExpr ) const;

		/**
		 * Returns the values of the nodes that match the given
		 * expression.
		 */
		Array<String> findValues( String xpathExpr ) const;

		/**
		 * Returns the first that matches the given expression.
		 */
		DomNode* findNode( String xpathExpr );
		/** overload. */
		const DomNode* findNode( String xpathExpr ) const;

		/**
		 * Returns the value of the first node that matches the given
		 * expression.
		 */
		String findValue( String xpathExpr ) const;


		// ===========================================================
		//  manipulation
		// ===========================================================

		/**
		 * Sets the node to use as the root node for all expressions.
		 */
		void setRootNode( DomNode* root );

		/**
		 * Adds a custom function that can be used in XPath expressions.
		 */
		void addFunction( XPathFunction* function );
		/**
		 * Removes a function from use within an XPath expression.
		 */
		void removeFunction( String function );

	private:
		/**
		 * Copy constructor. Private because XPathExpressions should not be
		 * manipulated by more than one instance.
		 */
		XPathExpression( const XPathExpression& );
		/** Private assignment operator. See copy constructor documentation. */
		const XPathExpression& operator=( const XPathExpression& );


		struct xp_path_item
		{
			String m_axis;
			String m_node;
			Array< Array<XPathToken> > m_predicates;
		};

		void extractInfo( String xpathExpr, Array< Array<xp_path_item> >& info );
		
		Array<DomNode*> processPass( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processPassAxis( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processRecursiveMatch( DomNode* node, xp_path_item& item );

		Array<DomNode*> processAxisChild           ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisDescendant      ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisParent          ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisAncestor        ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisFollowingSibling( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisPrecedingSibling( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisFollowing       ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisPreceding       ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisDescendantOrSelf( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisAncestorOrSelf  ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisSelf            ( Array<DomNode*> search, xp_path_item& item );
		Array<DomNode*> processAxisAttribute       ( Array<DomNode*> search, xp_path_item& item );

		Array<DomNode*> processPredicates( Array<DomNode*> search, xp_path_item& item );

		bool checkForMatch( DomNode* node, xp_path_item& item );


		DomNode* m_root;
		XPathPredicate* m_predicate;
	};




	/**
	 * \class XPathToken
	 * \ingroup Xml
	 * \brief Represents a token in an XPath predicate.
	 */
	class BLUE_EXPORT_XML XPathToken
	{
	public:
		enum type_e
		{
			STRING,      //!< String value
			NUMBER_INT,  //!< Integer numeric value
			NUMBER_DBL,  //!< Double floating point precision value
			BOOLEAN,     //!< Boolean value
			NODESET,     //!< Nodeset

			OPERATOR,    //!< An operator
			PAREN,       //!< A parenthesis
			FUNCTION,    //!< The name of a function
		};

		// ===========================================================
		//  creation/destruction
		// ===========================================================
		
		/** Constructor. */
		XPathToken();
		/** Constructor. */
		XPathToken( String value, type_e type );
		/** Constructor. */
		XPathToken( String value );
		/** Constructor. */
		XPathToken( bool value );
		/** Constructor. */
		XPathToken( int value );
		/** Constructor. */
		XPathToken( double value );


		// ===========================================================
		//  query
		// ===========================================================
		
		/** Returns the value of the token as a String. */
		String getValue( DomNode* context ) const;
		/** Returns the type of the value of this token. */
		type_e getType() const;

		/**
		 * Returns the value of this token if it is a boolean.
		 * If the value is not a boolean, an XPathException will be thrown.
		 */
		String getValueString() const;
		/**
		 * Returns the value of this token if it is a boolean.
		 * If the value is not a boolean, an XPathException will be thrown.
		 */
		bool getValueBool() const;
		/**
		 * Returns the value of this token if it is a number.
		 * If the value is not a number, an XPathException will be thrown.
		 */
		int getValueNumberInt() const;
		/**
		 * Returns the value of this token if it is a number.
		 * If the value is not a number, an XPathException will be thrown.
		 */
		double getValueNumberDouble() const;
		/**
		 * Returns the value of this token if it is a nodeset.
		 * If the value is not a nodeset, an XPathException will be thrown.
		 */
		Array<DomNode*> getValueNodeSet( DomNode* context ) const;

		/**
		 * Determines if the value type of this token is compatible with the
		 * given value type.
		 *
		 * For example, a BOOLEAN is compatible with a STRING (true => "true").
		 */
		bool isCompatibleWith( type_e type ) const;


	private:
		String m_value;
		type_e m_type;
	};



	/**
	 * \class XPathFunction
	 * \ingroup Xml
	 * \brief A function that can be called in an XPath predicate.
	 *
	 * Custom XPath functions are created by deriving new classes
	 * from this one and overloading the execute() function.
	 */
	class BLUE_EXPORT_XML XPathFunction
	{
	public:
		// ===========================================================
		//  creation/destruction
		// ===========================================================

		/** Destructor. */
		virtual ~XPathFunction()
		{}


		// ===========================================================
		//  query
		// ===========================================================

		/** Returns the name of the function. */
		String getName() const;
		/** Returns the number of parameters the function expects. */
		int getParmCount() const;


		// ===========================================================
		//  manipulation
		// ===========================================================

		/**
		 * Called to execute the function.  This must be overloaded by
		 * all deriving classes.
		 *
		 * \param search - The nodes that match the path so far.
		 * \param context - The node currently being processed
		 * \param parms - The parameters being passed to the function.
		 *        these should be validated using validateParm().
		 */
		virtual XPathToken execute( Array<DomNode*> search, DomNode* context, Array<XPathToken> parms ) = 0;


	protected:
		/**
		 * Constructor.
		 *
		 * \param name - The name of the function.
		 * \param parmCount - The number of parameters that must be
		 *        passed to the function.  If this value is '-1' then
		 *        there is no set number of parameters.
		 */
		XPathFunction( String name, int parmCount );

		/**
		 * Called in the execute() function to validate the given parameters.
		 */
		void validateParm( XPathToken& parm, XPathToken::type_e type );


	private:
		/**
		 * Copy constructor. Private because XPathFunctions should not be
		 * manipulated by more than one instance.
		 */
		XPathFunction( const XPathFunction& );
		/** Private assignment operator. See copy constructor documentation. */
		const XPathFunction& operator=( const XPathFunction& );

		
		String m_name;
		int    m_parmCount;
	};



	/**
	 * \class XPathException
	 * \brief Thrown when a syntax error is encountered in the XPath expression.
	 * \ingroup XmlExceptions
	 */
	class BLUE_EXPORT_XML XPathException :public XmlException
	{
	public:
		XPathException( String desc )
			:XmlException(desc) {}

		virtual String getException() const {
			return (String("XPathException", String::STATIC));
		}
	};


}}}	// namespaces


// Public External Variables ===============================================================================================

// Public Function Prototypes ==============================================================================================

// Public Inline Functions =================================================================================================

#endif // include guard