[PHP-DEV] CVS update: php3/doc/functions From: ssb (php-dev <email protected>)
Date: 10/21/98

Date: Wednesday October 21, 1998 @ 17:49
Author: ssb

Update of /repository/php3/doc/functions
In directory asf:/u2/tmp/cvs-serv8564

Modified Files:
        xml.sgml
Log Message:
completed the XML docs

Index: php3/doc/functions/xml.sgml
diff -c php3/doc/functions/xml.sgml:1.1 php3/doc/functions/xml.sgml:1.2
*** php3/doc/functions/xml.sgml:1.1 Wed Oct 21 13:50:58 1998
--- php3/doc/functions/xml.sgml Wed Oct 21 17:49:34 1998
***************
*** 26,40 ****
        currently uses single-byte characters.
       </para>
       <para>
        This extension lets you <link
        linkend="function.xml-parsercreate">create XML parsers</link>
        and then define <emphasis>handlers</emphasis> for different XML
        events. Each parser also has a few parameters you can adjust.
       </para>
       <para>
! The types of XML events supported are:
        <table>
! <title>Supported XML events</title>
         <tgroup cols="2">
          <thead>
           <row>
--- 26,45 ----
        currently uses single-byte characters.
       </para>
       <para>
+ The function names, parameters and constant names in this
+ extension are as much as possible based on the names used in
+ <productname>expat</productname>.
+ </para>
+ <para>
        This extension lets you <link
        linkend="function.xml-parsercreate">create XML parsers</link>
        and then define <emphasis>handlers</emphasis> for different XML
        events. Each parser also has a few parameters you can adjust.
       </para>
       <para>
! The XML event handlers defined are:
        <table>
! <title>Supported XML handlers</title>
         <tgroup cols="2">
          <thead>
           <row>
***************
*** 108,119 ****
        </table>
       </para>
      </sect2>
     </sect1>
  
     <sect1 id="xml.examples">
      <title>Some Examples</title>
      <para>
! Here are some examples of PHP scripts parsing XML documents.
      </para>
      <sect2 id="example.xml-structure">
       <title>XML Element Structure Example</title>
--- 113,174 ----
        </table>
       </para>
      </sect2>
+ <sect2 id="xml.case-folding">
+ <title>Case Folding</title>
+ <para>
+ The element handler functions may get their element names
+ <glossterm>case-folded</glossterm>. Case-folding is defined by
+ the XML standard as "a process applied to a sequence of
+ characters, in which those identified as non-uppercase are
+ replaced by their uppercase equivalents". In other words, when
+ it comes to XML, case-folding simply means uppercasing.
+ </para>
+ <para>
+ By default, all the element names that are passed to the handler
+ functions are case-folded. This behaviour can be queried and
+ controlled per parser with the
+ <function>XML_ParserGetOption</function> and
+ <function>XML_ParserSetOption</function> functions,
+ respectively.
+ </para>
+ </sect2>
+ <sect2 id="xml.error-codes">
+ <title>Error Codes</title>
+ <para>
+ The following constants are defined for XML error codes (as
+ returned by <function>XML_Parse</function>):
+ <simplelist>
+ <member>XML_ERROR_NONE</member>
+ <member>XML_ERROR_NO_MEMORY</member>
+ <member>XML_ERROR_SYNTAX</member>
+ <member>XML_ERROR_NO_ELEMENTS</member>
+ <member>XML_ERROR_INVALID_TOKEN</member>
+ <member>XML_ERROR_UNCLOSED_TOKEN</member>
+ <member>XML_ERROR_PARTIAL_CHAR</member>
+ <member>XML_ERROR_TAG_MISMATCH</member>
+ <member>XML_ERROR_DUPLICATE_ATTRIBUTE</member>
+ <member>XML_ERROR_JUNK_AFTER_DOC_ELEMENT</member>
+ <member>XML_ERROR_PARAM_ENTITY_REF</member>
+ <member>XML_ERROR_UNDEFINED_ENTITY</member>
+ <member>XML_ERROR_RECURSIVE_ENTITY_REF</member>
+ <member>XML_ERROR_ASYNC_ENTITY</member>
+ <member>XML_ERROR_BAD_CHAR_REF</member>
+ <member>XML_ERROR_BINARY_ENTITY_REF</member>
+ <member>XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF</member>
+ <member>XML_ERROR_MISPLACED_XML_PI</member>
+ <member>XML_ERROR_UNKNOWN_ENCODING</member>
+ <member>XML_ERROR_INCORRECT_ENCODING</member>
+ <member>XML_ERROR_UNCLOSED_CDATA_SECTION</member>
+ <member>XML_ERROR_EXTERNAL_ENTITY_HANDLING</member>
+ </simplelist>
+ </para>
+ </sect2>
     </sect1>
  
     <sect1 id="xml.examples">
      <title>Some Examples</title>
      <para>
! Here are some examples PHP scripts parsing XML documents.
      </para>
      <sect2 id="example.xml-structure">
       <title>XML Element Structure Example</title>
***************
*** 166,179 ****
         <title>Map XML to HTML</title>
         <para>
          This example maps tags in an XML document directly to HTML
! tags. Of course, this will only work with a specific XML
          document type.
          <programlisting role=php>
  $file = "data.xml";
  $map_array = array(
! "BOLD" => "B",
      "EMPHASIS" => "I",
! "LITERAL" => "TT"
  );
  
  function startElement($parser, $name, $attrs)
--- 221,235 ----
         <title>Map XML to HTML</title>
         <para>
          This example maps tags in an XML document directly to HTML
! tags. Elements not found in the "map array" are ignored. Of
! course, this examples will only work with a specific XML
          document type.
          <programlisting role=php>
  $file = "data.xml";
  $map_array = array(
! "BOLD" => "B",
      "EMPHASIS" => "I",
! "LITERAL" => "TT"
  );
  
  function startElement($parser, $name, $attrs)
***************
*** 223,233 ****
        This example highlights XML code. It illustrates how to use an
        external entity reference handler to include and parse other
        documents, as well as how PIs can be processed, and a way of
! determining trust for PIs containing code.
       </para>
       <para>
        XML documents that can be used for this example are found below
! the example.
       </para>
       <para>
        <example>
--- 279,290 ----
        This example highlights XML code. It illustrates how to use an
        external entity reference handler to include and parse other
        documents, as well as how PIs can be processed, and a way of
! determining "trust" for PIs containing code.
       </para>
       <para>
        XML documents that can be used for this example are found below
! the example (<filename>xmltest.xml</filename> and
! <filename>xmltest2.xml</filename>.)
       </para>
       <para>
        <example>
***************
*** 385,391 ****
    &lt;title>About this Document&lt;/title>
    &lt;para>
     &lt;!-- this is a comment -->
- &lt;!-- [CDATA[this is CDATA]] -->
     &lt;?php print 'Hi! This is PHP version '.phpversion(); ?>
    &lt;/para>
   &lt;/sect1>
--- 442,447 ----
***************
*** 394,400 ****
        </example>
       </para>
       <para id="example.xml-xmltest2.xml">
! This file is included from <filename>xmltest.xml</filename>.
        <example>
         <title>xmltest2.xml</title>
         <programlisting role=xml>
--- 450,456 ----
        </example>
       </para>
       <para id="example.xml-xmltest2.xml">
! This file is included from <filename>xmltest.xml</filename>:
        <example>
         <title>xmltest2.xml</title>
         <programlisting role=xml>
***************
*** 405,411 ****
  &lt;foo>
   &lt;element attrib="value"/>
   &amp;testEnt;
! &lt;?php print "TROJAN PHP code?"; ?>
  &lt;/foo>
  </programlisting>
        </example>
--- 461,467 ----
  &lt;foo>
   &lt;element attrib="value"/>
   &amp;testEnt;
! &lt;?php print "This is some more PHP code being executed."; ?>
  &lt;/foo>
  </programlisting>
        </example>
***************
*** 432,437 ****
--- 488,1256 ----
     </refsect1>
    </refentry>
  
+ <refentry id="function.xml-setelementhandler">
+ <refnamediv>
+ <refname>XML_SetElementHandler</refname>
+ <refpurpose>set up start and end element handlers</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetElementHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>startElementHandler</parameter></paramdef>
+ <paramdef>string <parameter>endElementHandler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the element handler functions for the XML parser
+ <parameter>parser</parameter>.
+ <parameter>startElementHandler</parameter> and
+ <parameter>endElementHandler</parameter> are strings containing
+ the names of functions that must exist when
+ <function>XML_Parse</function> is called for
+ <parameter>parser</parameter>.
+ <para>
+ The function named by <parameter>startElementHandler</parameter>
+ must accept three parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>startElementHandler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>name</parameter></paramdef>
+ <paramdef>string <parameter>attribs</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ The first parameter, <replaceable>parser</replaceable>, is a
+ reference to the XML parser calling the handler.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>name</parameter>, contains
+ the name of the element for which this handler is called. If
+ <link linkend="xml.case-folding">case-folding</link> is in
+ effect for this parser, the element name will be in uppercase
+ letters.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>attribs</parameter></term>
+ <listitem>
+ <simpara>
+ The third parameter, <parameter>attribs</parameter>, contains
+ an associative array with the element's attributes (if any).
+ The keys of this array are the attribute names, the values
+ are the attribute values. Attribute names are <link
+ linkend="xml.case-folding">case-folded</link> on the same
+ criteria as element names. Attribute values are
+ <emphasis>not</emphasis> case-folded.
+ <simpara>
+ The original order of the attributes can be retrieved by
+ walking through <parameter>attribs</parameter> the normal
+ way, using <function>each</function>. The first key in the
+ array was the first attribute, and so on.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The function named by <parameter>endElementHandler</parameter>
+ must accept two parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>endElementHandler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>name</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ The first parameter, <replaceable>parser</replaceable>, is a
+ reference to the XML parser calling the handler.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>name</parameter>, contains
+ the name of the element for which this handler is called. If
+ <link linkend="xml.case-folding">case-folding</link> is in
+ effect for this parser, the element name will be in uppercase
+ letters.
+ </varlistentry>
+ </variablelist>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-setcharacterdatahandler">
+ <refnamediv>
+ <refname>XML_SetCharacterDataHandler</refname>
+ <refpurpose>set up character data handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetCharacterDataHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>handler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the character data handler function for the XML parser
+ <parameter>parser</parameter>. <parameter>handler</parameter> is
+ a string containing the name of a function that must exist when
+ <function>XML_Parse</function> is called for
+ <parameter>parser</parameter>.
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ two parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>handler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>data</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ The first parameter, <replaceable>parser</replaceable>, is a
+ reference to the XML parser calling the handler.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>data</parameter>, contains
+ the character data as a string.
+ </varlistentry>
+ </variablelist>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-setprocessinginstructionhandler">
+ <refnamediv>
+ <refname>XML_SetProcessingInstruction</refname>
+ <refpurpose>set up processing instruction (PI) handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetProcessingInstructionHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>handler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the processing instruction (PI) handler function for the XML
+ parser <parameter>parser</parameter>.
+ <parameter>handler</parameter> is a string containing the name of
+ a function that must exist when <function>XML_Parse</function> is
+ called for <parameter>parser</parameter>.
+ <para>
+ A processing instruction has the following format:
+ <informalexample>
+ <programlisting>&lt;?<replaceable>target</replaceable> <replaceable>data</replaceable>?></programlisting>
+ </informalexample>
+ You can put PHP code into such a tag, but be aware of one
+ limitation: in an XML PI, the PI end tag
+ (<literal>?&gt;</literal>) can not be quoted, so this character
+ sequence should not appear in the PHP code you embed with PIs in
+ XML documents. If it does, the rest of the PHP code, as well as
+ the "real" PI end tag, will be treated as character data.
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ three parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>handler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>target</parameter></paramdef>
+ <paramdef>string <parameter>data</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ The first parameter, <replaceable>parser</replaceable>, is a
+ reference to the XML parser calling the handler.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>target</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>target</parameter>, contains
+ the PI target.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem><simpara>
+ The third parameter, <parameter>data</parameter>, contains
+ the PI data.
+ </varlistentry>
+ </variablelist>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-setdefaulthandler">
+ <refnamediv>
+ <refname>XML_SetDefaultHandler</refname>
+ <refpurpose>set up default handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetDefaultHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>handler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the default handler function for the XML parser
+ <parameter>parser</parameter>. <parameter>handler</parameter> is
+ a string containing the name of a function that must exist when
+ <function>XML_Parse</function> is called for
+ <parameter>parser</parameter>.
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ two parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>handler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>data</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ The first parameter, <replaceable>parser</replaceable>, is a
+ reference to the XML parser calling the handler.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>data</parameter>, contains
+ the character data. This may be the XML declaration,
+ document type declaration, entities or other data for which
+ no other handler exists.
+ </varlistentry>
+ </variablelist>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-setunparsedentitydeclhandler">
+ <refnamediv>
+ <refname>XML_SetUnparsedEntityDeclHandler</refname>
+ <refpurpose>set up unparsed entity declaration handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetUnparsedEntityDeclHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>handler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the unparsed entity declaration handler function for the XML
+ parser <parameter>parser</parameter>.
+ <parameter>handler</parameter> is a string containing the name of
+ a function that must exist when <function>XML_Parse</function> is
+ called for <parameter>parser</parameter>.
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ six parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>handler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>entityName</parameter></paramdef>
+ <paramdef>string <parameter>base</parameter></paramdef>
+ <paramdef>string <parameter>systemId</parameter></paramdef>
+ <paramdef>string <parameter>publicId</parameter></paramdef>
+ <paramdef>string <parameter>notationName</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-setnotationdeclhandler">
+ <refnamediv>
+ <refname>XML_SetNotationDeclHandler</refname>
+ <refpurpose>set up notation declaration handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetNotationDeclHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>handler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the notation declaration handler function for the XML parser
+ <parameter>parser</parameter>. <parameter>handler</parameter> is
+ a string containing the name of a function that must exist when
+ <function>XML_Parse</function> is called for
+ <parameter>parser</parameter>.
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ five parameters:
+ <funcsynopsis>
+ <funcdef><replaceable>handler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>notationName</parameter></paramdef>
+ <paramdef>string <parameter>base</parameter></paramdef>
+ <paramdef>string <parameter>systemId</parameter></paramdef>
+ <paramdef>string <parameter>publicId</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-setexternalentityrefhandler">
+ <refnamediv>
+ <refname>XML_SetExternalEntityRefHandler</refname>
+ <refpurpose>set up external entity reference handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_SetExternalEntityRefHandler</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>handler</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ Sets the notation declaration handler function for the XML parser
+ <parameter>parser</parameter>. <parameter>handler</parameter> is
+ a string containing the name of a function that must exist when
+ <function>XML_Parse</function> is called for
+ <parameter>parser</parameter>.
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ five parameters, and should return an integer value. If the
+ value returned from the handler is false (which it will be if no
+ value is returned), the XML parser will stop parsing and
+ <function>XML_GetErrorCode</function> will return <systemitem
+ class="constant">XML_ERROR_EXTERNAL_ENTITY_HANDLING</systemitem>.
+
+ <funcsynopsis>
+ <funcdef>int <replaceable>handler</replaceable></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>openEntityNames</parameter></paramdef>
+ <paramdef>string <parameter>base</parameter></paramdef>
+ <paramdef>string <parameter>systemId</parameter></paramdef>
+ <paramdef>string <parameter>publicId</parameter></paramdef>
+ </funcsynopsis>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ The first parameter, <replaceable>parser</replaceable>, is a
+ reference to the XML parser calling the handler.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>openEntityNames</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>openEntityNames</parameter>,
+ is a space-separated list of the names of the entities that
+ are open for the parse of this entity (including the name of
+ the referenced entity).
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>base</parameter></term>
+ <listitem><simpara>
+ The third parameter, <parameter>base</parameter>, is
+ currently reserved for future use. It should be the system
+ identifier that should be used as the base for resolving
+ <parameter>systemId</parameter> if systemId was relative.
+ <!-- XXX this is set by XML_SetBase -->
+ This parameter may be an empty string.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>systemId</parameter></term>
+ <listitem><simpara>
+ The fourth parameter, <parameter>systemId</parameter>, is the
+ system identifier as specified in the entity declaration.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>publicId</parameter></term>
+ <listitem><simpara>
+ The fifth parameter, <parameter>publicId</parameter>, is the
+ public identifier as specified in the entity declaration, or
+ an empty string if none was specified; the whitespace in the public
+ identifier will have been normalized as required by the XML spec.
+ </varlistentry>
+ </variablelist>
+ <para>
+ If a handler function is set to an empty string, or
+ <literal>false</literal>, the handler in question is disabled.
+ <para>
+ True is returned on success, false if
+ <parameter>parser</parameter> is not a parser.
+ <para>
+ There is currently no support for handlers in methods/objects.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parse">
+ <refnamediv>
+ <refname>XML_Parse</refname>
+ <refpurpose>start parsing an XML document</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_Parse</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>string <parameter>data</parameter></paramdef>
+ <paramdef>int <parameter><optional>isFinal</optional></parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to use.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem><simpara>
+ Chunk of data to parse. A document may be parsed piece-wise
+ by calling <function>XML_Parse</function> several times with
+ new data, as long as the <parameter>isFinal</parameter>
+ parameter is set and true when the last data is parsed.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>isFinal</parameter> (optional)</term>
+ <listitem><simpara>
+ If set and true, <parameter>data</parameter> is the last
+ piece of data sent in this parse.
+ </varlistentry>
+ </variablelist>
+ <para>
+ When the XML document is parsed, the handlers for the configured
+ events are called as many times as necessary, after which this
+ function returns true or false.
+ <para>
+ True is returned if the parse was successful, false if it was not
+ successful, or if <parameter>parser</parameter> does not refer to
+ a valid parser. For unsuccessful parses, error information can
+ be retrieved with <function>XML_GetErrorCode</function>,
+ <function>XML_ErrorString</function>,
+ <function>XML_GetCurrentLineNumber</function>,
+ <function>XML_GetCurrentColumnNumber</function> and
+ <function>XML_GetCurrentByteIndex</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-geterrorcode">
+ <refnamediv>
+ <refname>XML_GetErrorCode</refname>
+ <refpurpose>get XML parser error code</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_GetErrorCode</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to get error code from.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or else it returns one of the error
+ codes listed in the <link linkend="xml.error-codes">error codes
+ section</link>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-errorstring">
+ <refnamediv>
+ <refname>XML_ErrorString</refname>
+ <refpurpose>get XML parser error string</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>string <function>XML_ErrorString</function></funcdef>
+ <paramdef>int <parameter>code</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>code</parameter></term>
+ <listitem><simpara>
+ An error code from <function>XML_GetErrorCode</function>.
+ </varlistentry>
+ </variablelist>
+ <para>
+ Returns a string with a textual description of the error code
+ <parameter>code</parameter>, or false if no description was found.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-getcurrentlinenumber">
+ <refnamediv>
+ <refname>XML_GetCurrentLineNumber</refname>
+ <refpurpose>get current line number for an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_GetCurrentLineNumber</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to get line number from.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or else it returns which line the
+ parser is currently at in its data buffer.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-getcurrentcolumnnumber">
+ <refnamediv>
+ <refname>XML_GetCurrentColumnNumber</refname>
+ <refpurpose>get current column number for an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_GetCurrentColumnNumber</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to get column number from.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or else it returns which column on
+ the current line (as given by
+ <function>XML_GetCurrentLineNumber</function>) the parser is
+ currently at.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-getcurrentbyteindex">
+ <refnamediv>
+ <refname>XML_GetCurrentByteIndex</refname>
+ <refpurpose>get current byte index for an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_GetCurrentByteIndex</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to get byte index from.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or else it returns which byte index
+ the parser is currently at in its data buffer (starting at 0).
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parserfree">
+ <refnamediv>
+ <refname>XML_ParserFree</refname>
+ <refpurpose>free an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>string <function>XML_ParserFree</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to free.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or else it frees the parser and
+ returns true.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parsersetoption">
+ <refnamediv>
+ <refname>XML_ParserSetOption</refname>
+ <refpurpose>set options in an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>int <function>XML_ParserSetOption</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>int <parameter>option</parameter></paramdef>
+ <paramdef>mixed <parameter>value</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to set an option in.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>option</parameter></term>
+ <listitem><simpara>
+ Which option to set. See below.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>value</parameter></term>
+ <listitem><simpara>
+ The option's new value.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or if the option could not be set.
+ Else the option is set and true is returned.
+ </para>
+ <para>
+ The following options are available:
+ <table>
+ <title>XML parser options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Option constant</entry>
+ <entry>Data type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XML_OPTION_CASE_FOLDING</entry>
+ <entry>integer</entry>
+ <entry>Controls whether <link
+ linkend="xml.case-folding">case-folding</link> is enabled for
+ this parser. Enabled by default.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parsergetoption">
+ <refnamediv>
+ <refname>XML_ParserGetOption</refname>
+ <refpurpose>get options from an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcdef>mixed <function>XML_ParserGetOption</function></funcdef>
+ <paramdef>int <parameter>parser</parameter></paramdef>
+ <paramdef>int <parameter>option</parameter></paramdef>
+ </funcsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem><simpara>
+ A reference to the XML parser to get an option from.
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>option</parameter></term>
+ <listitem><simpara>
+ Which option to fetch. See
+ <function>XML_ParserSetOption</function> for a list of options.
+ </varlistentry>
+ </variablelist>
+ <para>
+ This function returns false if <parameter>parser</parameter> does
+ not refer to a valid parser, or if the option could not be set.
+ Else the option's value is returned.
+ </para>
+ <para>
+ See <function>XML_ParserSetOption</function> for the list of
+ options.
+ </para>
+ </refsect1>
+ </refentry>
  
   </reference>
  <!-- Keep this comment at the end of the file 

--
PHP Development Mailing List   http://www.php.net/
To unsubscribe send an empty message to php-dev-unsubscribe <email protected>
For help: php-dev-help <email protected>