parser.h

ACE自适配通信环境（ADAPTIVE Communication Environment）是可以自由使用、开放源码的面向对象（OO）框架（Framework）

// -*- C++ -*-

//=============================================================================
/**
 *  @file    Parser.h
 *
 *  Parser.h,v 1.14 2006/02/09 22:53:20 kitty Exp
 *
 *  @author Nanbor Wang <[e-mail]>
 *  @author Krishnakumar B <[e-mail]>
 */
//=============================================================================

#ifndef _ACEXML_BASIC_PARSER_H_
#define _ACEXML_BASIC_PARSER_H_

#include /**/ "ace/pre.h"
#include "ACEXML/parser/parser/Parser_export.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
#pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#include "ACEXML/common/XMLReader.h"
#include "ACEXML/common/LocatorImpl.h"
#include "ACEXML/common/NamespaceSupport.h"
#include "ACEXML/common/CharStream.h"
#include "ace/Obstack.h"
#include "ace/Functor.h"
#include "ace/SString.h"
#include "ace/Hash_Map_Manager.h"
#include "ace/Unbounded_Set.h"
#include "ace/Containers_T.h"
#include "ace/Auto_Ptr.h"
#include "ACEXML/parser/parser/Entity_Manager.h"
#include "ACEXML/parser/parser/ParserInternals.h"
#include "ACEXML/parser/parser/ParserContext.h"

/**
 * @class ACEXML_Parser Parser.h "ACEXML/parser/parser/Parser.h"
 *
 * @brief A SAX based parser.
 *
 */
class ACEXML_PARSER_Export ACEXML_Parser : public ACEXML_XMLReader
{
public:
  /// Default constructor.
  ACEXML_Parser (void);

  /// Destructor.
  virtual ~ACEXML_Parser (void);

  /**
   *  Initialize the parser state.
   *
   *  @retval 0 if parser was initialized correctly else -1.
   */
  int initialize (ACEXML_InputSource* input);

   /**
   * Return the current content handler.
   */
  virtual ACEXML_ContentHandler *getContentHandler (void) const;

  /*
   * Return the current DTD handler.
   */
  virtual ACEXML_DTDHandler *getDTDHandler (void) const;

  /*
   * Return the current entity resolver.
   */
  virtual ACEXML_EntityResolver *getEntityResolver (void) const;

  /*
   * Return the current error handler.
   */
  virtual ACEXML_ErrorHandler *getErrorHandler (void) const;

  /**
   * Look up the value of a feature.  This method allows
   * programmers to check whether a specific feature has been
   * activated in the parser.
   */
  virtual int getFeature (const ACEXML_Char *name ACEXML_ENV_ARG_DECL)
          ACE_THROW_SPEC ((ACEXML_SAXNotRecognizedException,
                           ACEXML_SAXNotSupportedException)) ;

  /**
   * Activating or deactivating a feature.
   */
  virtual void setFeature (const ACEXML_Char *name,
                           int boolean_value ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXNotRecognizedException,
                     ACEXML_SAXNotSupportedException)) ;

  /*
   * Look up the value of a property.
   */
  virtual void * getProperty (const ACEXML_Char *name ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXNotRecognizedException,
                     ACEXML_SAXNotSupportedException)) ;

  /*
   * Set the value of a property.
   */
  virtual void setProperty (const ACEXML_Char *name,
                            void *value ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXNotRecognizedException,
                     ACEXML_SAXNotSupportedException)) ;

  /*
   * Parse an XML document.
   */
  virtual void parse (ACEXML_InputSource *input ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException)) ;

  /*
   * Parse an XML document from a system identifier (URI).
   */
  virtual void parse (const ACEXML_Char *systemId ACEXML_ENV_ARG_DECL)
        ACE_THROW_SPEC ((ACEXML_SAXException))
    ;

  /*
   * Allow an application to register a content event handler.
   */
  virtual void setContentHandler (ACEXML_ContentHandler *handler);

  /*
   * Allow an application to register a DTD event handler.
   */
  virtual void setDTDHandler (ACEXML_DTDHandler *handler);

  /*
   * Allow an application to register an entity resolver.
   */
  virtual void setEntityResolver (ACEXML_EntityResolver *resolver);

  /*
   * Allow an application to register an error event handler.
   */
  virtual void setErrorHandler (ACEXML_ErrorHandler *handler);



protected:
  /**
   * Parse XML Prolog.
   */
  void parse_xml_prolog (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse VersionInfo declaration.
   *
   */
  void parse_version_info (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a EncodingDecl declaration.
   *
   */
  void parse_encoding_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a XMLDecl declaration.
   *
   */
  void parse_xml_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a TextDecl declaration.
   */
  int parse_text_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse a PI statement.  The first character encountered
   * should always be '?' in the PI prefix "@<?".
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_processing_instruction (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse the DOCTYPE declaration.  The first character encountered
   * should always be  'D' in doctype prefix: "@<@!DOCTYPE".
   */
  int parse_doctypedecl (ACEXML_ENV_SINGLE_ARG_DECL)
        ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse an XML element.  The first character encountered should
   * be the first character of the element "Name".
   *
   * @param is_root If not 0, then we are expecting to see the "root"
   * element now, and the next element's name need to match the name
   * defined in DOCTYPE definition, i.e., @a this->doctype_.
   *
   * @todo Instead of simply checking for the root element based on the
   * argument @a is_root, we should instead either pass in some sort
   * of validator or allow the function to return the element name so it
   * can be used in a validator.
   */
  void parse_element (int is_root ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a content declaration.
   *
   */
  int parse_content (const ACEXML_Char* startname, const ACEXML_Char*& ns_uri,
                     const ACEXML_Char*& ns_lname, int ns_flag
                     ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse a character reference, i.e., "&#x20;" or "&#30;".   The first
   * character encountered should be the '#' char.
   *
   * @param buf points to a character buffer for the result.
   *
   * @param len In/out argument which initially specifies the size of the
   * buffer and is later set to the no. of characters in the reference.
   *
   * @retval 0 on success and -1 otherwise.
   */
  int parse_char_reference (ACEXML_Char *buf, size_t& len);

  /**
   * Parse a reference name, i.e., foo in "&foo;" or "%foo;". The first
   * character encountered should be the character following '&' or '%'.
   * Effectively the same as @sa parse_name but we don't use the parser's
   * obstack. Caller is responsible for deleting the memory.
   *
   * @retval  A pointer to name of reference, 0 otherwise.
   */
  ACEXML_Char* parse_reference_name (void);

  /**
   * Parse a CDATA section.  The first character should always be the first
   * '[' in CDATA definition.
   *
   * @retval 0 on success.
   * @retval -1 if fail.
   */
  int parse_cdata (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse a "markupdecl" section, this includes both "markupdecl" and
   * "DeclSep" sections in XML specification
   */
  int parse_internal_dtd (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Skip over a comment. The first character encountered should always be
   *  the first '-' in the comment prefix "@<@!--".
   */
  int parse_comment (void);

  /**
   * Parse an "ELEMENT" decl.  The first character this method
   * expects is always the 'L' (the second char) in the word
   * "ELEMENT".
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_element_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse an "ENTITY" decl.  The first character this method expects
   * is always the 'N' (the second char) in the word "ENTITY".
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_entity_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse an "ATTLIST" decl.  Thse first character this method
   * expects is always the 'A' (the first char) in the word
   * "ATTLIST".
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_attlist_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse a AttType declaration.
   *
   */
  int parse_atttype (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *Parse a "NOTATION" decl.  The first character this method
   * expects is always the 'N' (the first char) in the word
   * "NOTATION".
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_notation_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse an ExternalID or a reference to PUBLIC ExternalID.
   * Possible cases are in the forms of: <code>
   *
   * SYSTEM 'quoted string representing system resource'
   * PUBLIC 'quoted name of public ID' 'quoted resource'
   * PUBLIC 'quoted name we are referring to'
   * </code>
   *
   * The first character this function sees must be either 'S' or 'P'.
   * When the function finishes parsing, the input stream points
   * at the first non-whitespace character.
   *
   * @param publicId returns the unquoted publicId read.  If none
   *        is available, it will be reset to 0.
   * @param systemId returns the unquoted systemId read.  If none
   *        is available, it will be reset to 0.
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_external_id (ACEXML_Char *&publicId, ACEXML_Char *&systemId
                         ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse an external DTD.
   *
   */
  int parse_external_dtd (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse an external subset. This does the actual parsing of an external
   *  subset and is called by @sa parse_external_dtd.
   *
   */
  int parse_external_subset (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a markupDecl section.
   *
   */
  int parse_markup_decl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a conditionalSect declaration.
   *
   */
  int parse_conditional_section (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a includeSect declaration.
   *
   */
  int parse_includesect (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *
   *  Parse a ignoreSect declaration.
   */
  int parse_ignoresect (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse a PEReference.
   *
   */
  int parse_PE_reference (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a Reference.
   *
   */
  int parse_entity_reference (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse an entityValue.
   *
   */
  int parse_entity_value (ACEXML_Char *&str ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a DefaultDecl specification.
   *
   */
  int parse_defaultdecl (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));


  /**
   * Parse the "children" and "Mixed" non-terminals in contentspec.
   *
   * The first character this function sees must be the first
   * open paren '(' in children.
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_children_definition (ACEXML_ENV_SINGLE_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   * Parse a @c cp non-terminal.  @c cp can either be a @c seq or a @c choice.
   * This function calls itself recursively.
   *
   * @param skip_open_paren when non-zero, it indicates that the open paren of
   *        the @c seq or @c choice has already been removed from the input
   *        stream.
   *
   * @retval 0 on success, -1 otherwise.
   */
  int parse_child (int skip_open_paren ACEXML_ENV_ARG_DECL)
    ACE_THROW_SPEC ((ACEXML_SAXException));

  /**
   *  Parse a name from the input CharStream. If @a ch @!= 0, then we have
   *  already consumed the first name character from the input CharStream,
   *  otherwise, parse_name will use this->get() to acquire the initial
   *  character.
   *
   *  @return A pointer to the string in the obstack, 0 if it's not a
   *  valid name.
   */
  ACEXML_Char *parse_name (ACEXML_Char ch = 0);

  /**
   *  Parse a NMTOKEN from the input stream.
   *
   * @return A pointer to the string in the obstack, 0 if it's not a valid
   * NMTOKEN.
   */
  ACEXML_Char* parse_nmtoken (ACEXML_Char ch = 0);