<?php $isip_window_title = "ISIP Homepage"; ?>
<?php include("/data/isip/www/templates/documentation/header/header.html"); ?>

<!--#set var="isip_page_title" value="XMLParser" -->
<?php include("/data/isip/www/templates/documentation/body/index_class.html"); ?>
<?php include("/data/isip/www/templates/documentation/body/bar.html"); ?>

<a name="name">
<b>name: <a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h">XMLParser</a></b>

<br><br>

<a name="synopsis">
<b>synopsis:</b>
<br><br>

<blockquote>
<pre> 
g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_mmedia.a

#include &lt;XMLParser.h&gt;

boolean parseXML(String document_a);
boolean setValidTokenValues(Vector<String> valid_values_a);
boolean markUnhandledTokens();
boolean removeUnhandledTokens();
static const boolean setTokenDepths();
</pre>
</blockquote>

<a name="quick_start">
<b>quick start:</b>
<br><br>

<blockquote>
<pre>
String xml_string = L"&lt;xml_tag attrib1='val1'&gt; cdata tokens &lt;/xml_tag&gt;"; 
XMLPaser parser;
parser.parseXML(xml_string);
Console::put(parser.toXML());
</pre>
</blockquote>

<a name="description"> 
<b>description:</b>
<br><br>

The XMLParser class is used to parse an XML format document from a
String and store the document in a Vector of XMLToken objects which
will contain all of the raw information needed to process the XML
document. This class can also perform the service of filtering out 
unwanted XML tag types along with data contained within the unwanted tags, 
and resetting the depths of Vectors of XMLToken objects which have been
created or modified outside of the XMLParser class.

<br><br>
This class is built on top of the Expat parser, which checks for 
well-formedness but does not perform validation. For more 
information on the Expat parser, <a href="http://expat.sourceforge.net/">click here</a>.

<br><br>

<a name="dependencies">
<b>dependencies:</b>
<br><br>

<ul>
  <li> Expat
  <li> <a href="../../system/Console/index.html">Console</a>
  <li> <a href="../../io/Sof/index.html">Sof</a>
  <li> <a href="../../mmedia/XMLToken/index.html">XMLToken</a>
</ul>

<a name="constants">
<b>public constants:</b>
<br><br>

<ul>
  <li> define the class name:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_00.cc&constant=CLASS_NAME">static const String XMLParser::CLASS_NAME(L"XMLParser");</a></pre>

</ul>

<a name="error">
<b>error codes:</b>
<br><br>
<ul>
  <li> error code indicating XMLParser class general error:
       <pre><a href="/perl/ifc_document.pl?err=00050950">static const long ERR = 50950;</a></pre>
  <li> error code indicating that the Expat parser rejected the input:	
       <pre><a href="/perl/ifc_document.pl?err=00050951">static const long ERR_EXPAT_PARSE = 50951;</a></pre>
</ul>

<a name="protected">
<b>protected data:</b>
<br><br>

<ul> <!-- list of categories -->
  <li> A vector to store the xml tokens generated when parsing the document:
      <pre>token_vector_d;</pre>
  <li> A vector of values which will be considered valid:
      <pre>valid_values_d;</pre>
  <li> The debug level of the parser:
      <pre>Integral::DEBUG debug_level_d;</pre>     
</ul>

<a name="public">
<b>required public methods:</b>
<br><br>

<ul>
  <li> static methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=name">static const String& name();</a></pre>
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_02.cc&method=diagnose">static boolean diagnose(Integral::DEBUG debug_level);</a></pre>

  <li> debug methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser.h&method=setDebug">boolean setDebug(Integral::DEBUG debug_level);</a></pre>
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser.h&method=getDebug">Integral::DEBUG getDebug();</a></pre>

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_01.cc&method=debug">boolean debug(const unichar* msg) const;</a></pre>
       
  <li> constructor:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=default+constructor">XMLParser();</a></pre>
                          
  <li> i/o methods:
       
       <pre>these methods are omitted because XMLParser objects cannot write themselves to an Sof file</pre>

  <li> assign methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_01.cc&method=assign">boolean assign(const XMLParser& arg);</a></pre>

  <li> operator= methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=operator%3D&instance=0">XMLParser& operator=(const XMLParser& arg);</a></pre>

  <li> operator== methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=operator%3D%3D&instance=0">XMLParser& operator==(const XMLParser& arg);</a></pre>

  <li> equality methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=eq">boolean eq(const XMLParser& xp) const;</a></pre>

  <li> clear methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_01.cc&method=clear">boolean clear(Integral::CMODE ctype);</a></pre>

</ul>

<a name="specific">
<b>class-specific public methods:</b>
<br><br>

<ul>       
  <li> static methods:
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_05.cc&method=toXML">static const String toXML(Vector<XMLToken>& token_vector_a);</a></pre>  

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_04.cc&method=setTokenDepths">static const boolean setTokenDepths(Vector<XMLToken>& token_vector_a);</a></pre>  

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_04.cc&method=debugTokenDepths">static const boolean debugTokenDepths(Vector<XMLToken>& token_vector_a);</a></pre>  

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_05.cc&method=getIndent">static const String getIndent(long depth_a);</a></pre>  

  <li> get/set methods:
     
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=getTokenVector">Vector<XMLToken>& getTokenVector();</a></pre>    
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=setHandledValues">boolean setValidTokenValues(Vector<String> valid_values_a);</a></pre>    

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/XMLParser.h&method=getHandledValues">Vector<String>& getValidTokenValues();</a></pre>    

  <li> token vector manipulation methods:   

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_06.cc&method=addToken">boolean addToken(XMLToken token_a);</a></pre>
    
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_04.cc&method=markUnhandledTokens">boolean markUnhandledTokens();</a></pre>

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_04.cc&method=removeUnhandledTokens">boolean removeUnhandledTokens();</a></pre>    

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_04.cc&method=setTokenDepths">boolean setTokenDepths();</a></pre>

  <li> parsing  methods: 

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_06.cc&method=parseXML">boolean parseXML(String document_a);</a></pre>

  <li> miscellaneous methods: 
      
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_05.cc&method=parseXML">String toXML();</a></pre>

  <li> handler methods:

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_03.cc&method=OnPostCreate">String toXML();</a></pre>

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_03.cc&method=OnStartElement">void OnStartElement (const XML_Char *pszName, const XML_Char **papszAttrs);</a></pre>
       
       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_03.cc&method=OnEndElement">void OnEndElement (const XML_Char *pszName);
</a></pre>

       <pre><a href="/perl/ifc_document.pl?file=$isip/class/mmedia/XMLParser/xp_03.cc&method=OnCharacterData">void OnCharacterData (const XML_Char *parsedData, int nLength);</a></pre>

</ul>

<a name="examples">
<b>examples:</b>
<br><br>

<ul>
  <li> This example shows how to use an XMLParser object to
       parse an XML document from a String, how to remove undesired types of 
       tags from that document, and how to output the modified document as a 
       String.
   
<pre>
// store an arbitrary xml document in a string
//
String xml_string = L"&lt;xml_tag attrib1='val1'&gt; cdata tokens &lt;/xml_tag&gt;";
xml_string.concat(L" &lt;tag&gt; tag contents &lt;/tag&gt;");
xml_string.concat(L" &lt;metadata&gt; metadata contents &lt;/metadata&gt;"); 
xml_string.concat(L" &lt;item&gt; item contents &lt;/item&gt;");

// declare a parser
//
XMLPaser parser;

// specify which tokens we want to allow
// we will allow all but the item tokens
//
Vector&lt;String&gt; handled_values;
handled_values.concat(L"xml_tag");
handled_values.concat(L"tag");
handled_values.concat(L"metadata");

// parse the document. when the valid values are specified
// before this point, invalid tokens would be filtered automatically
//
parser.parseXML(xml_string);

// will output:
// &lt;xml_tag attrib1='val1'&gt;
//   cdata
//   tokens
// &lt;/xml_tag&gt;
// &lt;tag&gt; 
//   tag 
//   contents 
// &lt;/tag&gt;
// &lt;metadata&gt; 
//   metadata 
//   contents 
// &lt;/metadata&gt;
//
Console::put(parser.toXML());

// retrieve the document in a Vector&lt;XMLToken&gt; form for processing
// elsewhere
//
Vector&lt;XMLToken&gt; token_vector;
token_vector.assign(parser.getTokenVector());

// we may wish to modify the document outside of the parser
// lets add a few more xml tokens
//
XMLToken token;
token.init(START_TAG, L"new_token");
token_vector.concat(token);
token.init(CDATA, L"new_token_content");
token_vector.concat(token);
token.init(END_TAG, L"new_token");

// we didn't manually set the depths of the new tokens, so now
// the document is incorrect. The parser can take care of that for us.
//
XMLParser::setTokenDepths(token_vector);

// perhaps we wish to remove the metadata token type from the document
// to do so, put the token vector back in the parser
//
parser.setTokenVector(token_vector);

// define a set of valid values, which include the tokens we manually
// added, but not metadata tag
//
handled_values.clear(Integral::RESET);
handled_values.concat(L"xml_tag");
handled_values.concat(L"tag");
handled_values.concat(L"new_token");

// remove the invalid tokens
//
parser.setValidValues(handled_values);
parser.removeUnhandledTokens();

// see what the document looks like now.
// You've already seen how to do that with the parser,
// here's a way to do it without the parser object.
//
token_vector.assign(parser.getTokenVector());

// will output:
//
// &lt;xml_tag attrib1='val1'&gt;
//   cdata
//   tokens
// &lt;xml_tag&gt;
// &lt;tag&gt; 
//   tag 
//   contents 
// &lt;/tag&gt;
// &lt;new_token&gt; 
//   new_token_contents
// &lt;/new_token&gt;
//
Console::put(XMLParser::toXML(token_vector));
</pre>
</ul>

<!--#include virtual="/hse/ies/templates/documentation/footer/footer.html" -->
