gerzson Sun Apr 7 09:19:39 2002 EDT
Modified files:
/phpdoc/hu/functions xml.xml
Log:
tanslation started, 'intro' finished
Index: phpdoc/hu/functions/xml.xml
diff -u /dev/null phpdoc/hu/functions/xml.xml:1.3
--- /dev/null Sun Apr 7 09:19:39 2002
+++ phpdoc/hu/functions/xml.xml Sun Apr 7 09:19:39 2002
@@ -0,0 +1,2104 @@
+<?xml version="1.0" encoding="iso-8859-2"?>
+<!-- EN-Revision: 1.26 Maintainer: gerzson Status: just intro -->
+<!-- CRETIDS: acsontos -->
+
+ <reference id="ref.xml">
+ <title>XML értelmező függvények</title>
+ <titleabbrev>XML</titleabbrev>
+
+ <partintro>
+ <sect1 id="xml.partintro">
+ <title>Bemutatás</title>
+ <sect2 id="xml.intro">
+ <title>Az XML-ről néhány szóban</title>
+ <para>
+ Az XML (eXtensible Markup Language) olyan adatformátum, amit a Weben
+ keresztüli adatcserére terveztek. Ezt az ajánlást a World Wide Web
+ Consortium (W3C) dolgozta ki és gondozza. További információk az
+ XML-ről és a kapcsolódó technológiákról a <ulink
+ url="&url.xml;">&url.xml;</ulink> címen található.
+ </para>
+ </sect2>
+ <sect2 id="xml.install">
+ <title>Installálás</title>
+ <para>
+ Ez a kiterjesztés az <productname>expat</productname> könyvtárat
+ használja, amely a <ulink url="&url.expat;">&url.expat;</ulink> címen
+ beszerezhető. A Makefile, amely ezzel a csomaggal jön alapértelmezés
+ szerint nem telepíti a nekünk szükséges eljáráskönyvtárat, ehhez
+ a következő sorokat kell beleírni:
+ <programlisting role="makefile">
+<![CDATA[
+libexpat.a: $(OBJS)
+ ar -rc $@ $(OBJS)
+ ranlib $@
+]]>
+ </programlisting>
+ Elérhető forrás RPM csomag is a következő helyen: <ulink
+ url="&url.expat.rpm;">&url.expat.rpm;</ulink>, ha nem akarsz kínlódni
+ a fordítással ;)
+ </para>
+ <para>
+ Az Apache 1.3.7 vagy későbbi verziójával már együtt jár az expat könyvtár.
+ Ekkor a PHP-t csak egyszerűen a <option
+ role="configure">--with-xml</option> opcióval kell fordítani - minden
+ kiegészítő elérési útvonal nélkül - és ekkor az Apacheüba épített expat
+ könyvtárat használja majd.
+ </para>
+ <para>
+ Az UNIX rendszereken a <command>configure</command> parancsot kell a <option
+ role="configure">--with-xml</option> kapcsolóval. Az
+ <productname>expat</productname> könyvtárnak olyan helyen kell installálva
+ lennie, ahol a fordító el tudja érni. Ha a PHP-t modulként Apache 1.3.9
+ (ennek vagy későbbi verziójú) alá installálod, akkor a PHP automatikusan
+ az Apache beépített <productname>expat</productname> eljáráskönyvtárat
+ fogja használni. Szükség lehet <envar>CPPFLAGS</envar> és a
+ <envar>LDFLAGS</envar> környezeti változók beállítására a rendszeren,
+ mielőtt elindítod a configure parancsot, ha az expat-ot valamilyen
+ egzotikus helyre installáltad.
+ </para>
+ <para>
+ A PHP telepítése.... <emphasis>Tada!</emphasis> Ezt kell(ene) látnod!
+ </para>
+ </sect2>
+
+ <sect2 id="xml.about">
+ <title>Erről a bővítményről</title>
+ <para>
+ Ez a PHP bővítmény támogatást nyújt a James Clark által írt
+ <productname>expat</productname>-hoz a PHP-ben. Ezzel az eszkökézslettel
+ elemezhetsz, de nem érvényesíthetsz XML dokumentumokat. Háromféle forrás
+ <link linkend="xml.encoding">karakter kódolást</link>
+ támogat, amit a PHP is: <literal>US-ASCII</literal>,
+ <literal>ISO-8859-1</literal> és az<literal>UTF-8</literal>.
+ Az <literal>UTF-16</literal> nem támogatott.
+ </para>
+ <para>
+ Ezzel a bővítménnyel létrehozhatsz <link
+ linkend="function.xml-parser-create">XML elemzőket</link>
+ madj definiálhatsz <emphasis>"handler"-eket</emphasis> különféle XML
+ feladatokhoz. Mindegyik XML elemzőnek van néhány <link
+ linkend="function.xml-parser-set-option">paramétere</link> amit beállíthasz.
+ </para>
+ <para>
+ Az XML eseménykezelők:
+ <table>
+ <title>Támogatott XML kezelők (handler-ek)</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>PHP függvény a handler beállításához</entry>
+ <entry>Event description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>xml_set_element_handler</function></entry>
+ <entry>
+ Element events are issued whenever the XML parser
+ encounters start or end tags. There are separate handlers
+ for start tags and end tags.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <function>xml_set_character_data_handler</function>
+ </entry>
+ <entry>
+ Character data is roughly all the non-markup contents of
+ XML documents, including whitespace between tags. Note
+ that the XML parser does not add or remove any whitespace,
+ it is up to the application (you) to decide whether
+ whitespace is significant.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <function>xml_set_processing_instruction_handler</function>
+ </entry>
+ <entry>
+ PHP programmers should be familiar with processing
+ instructions (PIs) already. <?php ?> is a processing
+ instruction, where <replaceable>php</replaceable> is called
+ the "PI target". The handling of these are
+ application-specific, except that all PI targets starting
+ with "XML" are reserved.
+ </entry>
+ </row>
+ <row>
+ <entry><function>xml_set_default_handler</function></entry>
+ <entry>
+ What goes not to another handler goes to the default
+ handler. You will get things like the XML and document
+ type declarations in the default handler.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <function>xml_set_unparsed_entity_decl_handler</function>
+ </entry>
+ <entry>
+ This handler will be called for declaration of an unparsed
+ (NDATA) entity.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <function>xml_set_notation_decl_handler</function>
+ </entry>
+ <entry>
+ This handler is called for declaration of a notation.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <function>xml_set_external_entity_ref_handler</function>
+ </entry>
+ <entry>
+ This handler is called when the XML parser finds a
+ reference to an external parsed general entity. This can
+ be a reference to a file or URL, for example. See <link
+ linkend="example.xml-external-entity">the external entity
+ example</link> for a demonstration.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </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 XML parser with the
+ <function>xml_parser_get_option</function> and
+ <function>xml_parser_set_option</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>
+ <sect2 id="xml.encoding">
+ <title>Character Encoding</title>
+ <para>
+ PHP's XML extension supports the <ulink
+ url="&url.unicode;">Unicode</ulink> character set through
+ different <glossterm>character encoding</glossterm>s. There are
+ two types of character encodings, <glossterm>source
+ encoding</glossterm> and <glossterm>target encoding</glossterm>.
+ PHP's internal representation of the document is always encoded
+ with <literal>UTF-8</literal>.
+ </para>
+ <para>
+ Source encoding is done when an XML document is <link
+ linkend="function.xml-parse">parsed</link>. Upon <link
+ linkend="function.xml-parser-create">creating an XML
+ parser</link>, a source encoding can be specified (this encoding
+ can not be changed later in the XML parser's lifetime). The
+ supported source encodings are <literal>ISO-8859-1</literal>,
+ <literal>US-ASCII</literal> and <literal>UTF-8</literal>. The
+ former two are single-byte encodings, which means that each
+ character is represented by a single byte.
+ <literal>UTF-8</literal> can encode characters composed by a
+ variable number of bits (up to 21) in one to four bytes. The
+ default source encoding used by PHP is
+ <literal>ISO-8859-1</literal>.
+ </para>
+ <para>
+ Target encoding is done when PHP passes data to XML handler
+ functions. When an XML parser is created, the target encoding
+ is set to the same as the source encoding, but this may be
+ changed at any point. The target encoding will affect character
+ data as well as tag names and processing instruction targets.
+ </para>
+ <para>
+ If the XML parser encounters characters outside the range that
+ its source encoding is capable of representing, it will return
+ an error.
+ </para>
+ <para>
+ If PHP encounters characters in the parsed XML document that can
+ not be represented in the chosen target encoding, the problem
+ characters will be "demoted". Currently, this means that such
+ characters are replaced by a question mark.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xml.examples">
+ <title>Some Examples</title>
+ <para>
+ Here are some example PHP scripts parsing XML documents.
+ </para>
+ <sect2 id="example.xml-structure">
+ <title>XML Element Structure Example</title>
+ <para>
+ This first example displays the stucture of the start elements in
+ a document with indentation.
+ <example>
+ <title>Show XML Element Structure</title>
+ <programlisting role="php">
+<![CDATA[
+$file = "data.xml";
+$depth = array();
+
+function startElement($parser, $name, $attrs) {
+ global $depth;
+ for ($i = 0; $i < $depth[$parser]; $i++) {
+ print " ";
+ }
+ print "$name\n";
+ $depth[$parser]++;
+}
+
+function endElement($parser, $name) {
+ global $depth;
+ $depth[$parser]--;
+}
+
+$xml_parser = xml_parser_create();
+xml_set_element_handler($xml_parser, "startElement", "endElement");
+if (!($fp = fopen($file, "r"))) {
+ die("could not open XML input");
+}
+
+while ($data = fread($fp, 4096)) {
+ if (!xml_parse($xml_parser, $data, feof($fp))) {
+ die(sprintf("XML error: %s at line %d",
+ xml_error_string(xml_get_error_code($xml_parser)),
+ xml_get_current_line_number($xml_parser)));
+ }
+}
+xml_parser_free($xml_parser);
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </sect2>
+
+ <sect2 id="example.xml-map-tags">
+ <title>XML Tag Mapping Example</title>
+ <para>
+ <example>
+ <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 example will only work with a specific XML
+ document type.
+ <programlisting role="php">
+<![CDATA[
+$file = "data.xml";
+$map_array = array(
+ "BOLD" => "B",
+ "EMPHASIS" => "I",
+ "LITERAL" => "TT"
+);
+
+function startElement($parser, $name, $attrs) {
+ global $map_array;
+ if ($htmltag = $map_array[$name]) {
+ print "<$htmltag>";
+ }
+}
+
+function endElement($parser, $name) {
+ global $map_array;
+ if ($htmltag = $map_array[$name]) {
+ print "</$htmltag>";
+ }
+}
+
+function characterData($parser, $data) {
+ print $data;
+}
+
+$xml_parser = xml_parser_create();
+// use case-folding so we are sure to find the tag in $map_array
+xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true);
+xml_set_element_handler($xml_parser, "startElement", "endElement");
+xml_set_character_data_handler($xml_parser, "characterData");
+if (!($fp = fopen($file, "r"))) {
+ die("could not open XML input");
+}
+
+while ($data = fread($fp, 4096)) {
+ if (!xml_parse($xml_parser, $data, feof($fp))) {
+ die(sprintf("XML error: %s at line %d",
+ xml_error_string(xml_get_error_code($xml_parser)),
+ xml_get_current_line_number($xml_parser)));
+ }
+}
+xml_parser_free($xml_parser);
+]]>
+ </programlisting>
+ </para>
+ </example>
+ </para>
+ </sect2>
+
+ <sect2 id="example.xml-external-entity">
+ <title>XML External Entity Example</title>
+ <para>
+ 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>
+ <title>External Entity Example</title>
+ <programlisting role="php">
+<![CDATA[
+$file = "xmltest.xml";
+
+function trustedFile($file) {
+ // only trust local files owned by ourselves
+ if (!eregi("^([a-z]+)://", $file)
+ && fileowner($file) == getmyuid()) {
+ return true;
+ }
+ return false;
+}
+
+function startElement($parser, $name, $attribs) {
+ print "<<font color=\"#0000cc\">$name</font>";
+ if (sizeof($attribs)) {
+ while (list($k, $v) = each($attribs)) {
+ print " <font color=\"#009900\">$k</font>=\"<font
+ color=\"#990000\">$v</font>\"";
+ }
+ }
+ print ">";
+}
+
+function endElement($parser, $name) {
+ print "</<font color=\"#0000cc\">$name</font>>";
+}
+
+function characterData($parser, $data) {
+ print "<b>$data</b>";
+}
+
+function PIHandler($parser, $target, $data) {
+ switch (strtolower($target)) {
+ case "php":
+ global $parser_file;
+ // If the parsed document is "trusted", we say it is safe
+ // to execute PHP code inside it. If not, display the code
+ // instead.
+ if (trustedFile($parser_file[$parser])) {
+ eval($data);
+ } else {
+ printf("Untrusted PHP code: <i>%s</i>",
+ htmlspecialchars($data));
+ }
+ break;
+ }
+}
+
+function defaultHandler($parser, $data) {
+ if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") {
+ printf('<font color="#aa00aa">%s</font>',
+ htmlspecialchars($data));
+ } else {
+ printf('<font size="-1">%s</font>',
+ htmlspecialchars($data));
+ }
+}
+
+function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId,
+ $publicId) {
+ if ($systemId) {
+ if (!list($parser, $fp) = new_xml_parser($systemId)) {
+ printf("Could not open entity %s at %s\n", $openEntityNames,
+ $systemId);
+ return false;
+ }
+ while ($data = fread($fp, 4096)) {
+ if (!xml_parse($parser, $data, feof($fp))) {
+ printf("XML error: %s at line %d while parsing entity %s\n",
+ xml_error_string(xml_get_error_code($parser)),
+ xml_get_current_line_number($parser), $openEntityNames);
+ xml_parser_free($parser);
+ return false;
+ }
+ }
+ xml_parser_free($parser);
+ return true;
+ }
+ return false;
+}
+
+
+function new_xml_parser($file) {
+ global $parser_file;
+
+ $xml_parser = xml_parser_create();
+ xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1);
+ xml_set_element_handler($xml_parser, "startElement", "endElement");
+ xml_set_character_data_handler($xml_parser, "characterData");
+ xml_set_processing_instruction_handler($xml_parser, "PIHandler");
+ xml_set_default_handler($xml_parser, "defaultHandler");
+ xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler");
+
+ if (!($fp = @fopen($file, "r"))) {
+ return false;
+ }
+ if (!is_array($parser_file)) {
+ settype($parser_file, "array");
+ }
+ $parser_file[$xml_parser] = $file;
+ return array($xml_parser, $fp);
+}
+
+if (!(list($xml_parser, $fp) = new_xml_parser($file))) {
+ die("could not open XML input");
+}
+
+print "<pre>";
+while ($data = fread($fp, 4096)) {
+ if (!xml_parse($xml_parser, $data, feof($fp))) {
+ die(sprintf("XML error: %s at line %d\n",
+ xml_error_string(xml_get_error_code($xml_parser)),
+ xml_get_current_line_number($xml_parser)));
+ }
+}
+print "</pre>";
+print "parse complete\n";
+xml_parser_free($xml_parser);
+
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para id="example.xml-xmltest.xml">
+ <example>
+ <title>xmltest.xml</title>
+ <programlisting role="xml">
+<![CDATA[
+<?xml version='1.0'?>
+<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [
+<!ENTITY plainEntity "FOO entity">
+<!ENTITY systemEntity SYSTEM "xmltest2.xml">
+]>
+<chapter>
+ <TITLE>Title &plainEntity;</TITLE>
+ <para>
+ <informaltable>
+ <tgroup cols="3">
+ <tbody>
+ <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row>
+ <row><entry>a2</entry><entry>c2</entry></row>
+ <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ &systemEntity;
+ <sect1 id="about">
+ <title>About this Document</title>
+ <para>
+ <!-- this is a comment -->
+ <?php print 'Hi! This is PHP version '.phpversion(); ?>
+ </para>
+ </sect1>
+</chapter>
+]]>
+ </programlisting>
+ </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">
+<![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE foo [
+<!ENTITY testEnt "test entity">
+]>
+<foo>
+ <element attrib="value"/>
+ &testEnt;
+ <?php print "This is some more PHP code being executed."; ?>
+</foo>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </sect2>
+ </sect1>
+ </partintro>
+
+ <refentry id="function.xml-parser-create">
+ <refnamediv>
+ <refname>xml_parser_create</refname>
+ <refpurpose>create an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_parser_create</methodname>
+ <methodparam
+choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>encoding</parameter> (optional)</term>
+ <listitem>
+ <para>
+ Which character encoding the parser should use. The
+ following character encodings are supported:
+ <simplelist>
+ <member><literal>ISO-8859-1</literal> (default)</member>
+ <member><literal>US-ASCII</literal></member>
+ <member><literal>UTF-8</literal></member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ This function creates an XML parser and returns a handle for use
+ by other XML functions. Returns &false; on
+ failure.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-object">
+ <refnamediv>
+ <refname>xml_set_object</refname>
+ <refpurpose>Use XML Parser within an object</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>void</type><methodname>xml_set_object</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>object</type><parameter>&object</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ This function allows to use <parameter>parser</parameter> inside
+ <parameter>object</parameter>. All callback functions could be
+ set with <function>xml_set_element_handler</function> etc and
+ assumed to be methods of <parameter>object</parameter>.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+class xml {
+var $parser;
+
+function xml() {
+ $this->parser = xml_parser_create();
+ xml_set_object($this->parser,&$this);
+ xml_set_element_handler($this->parser,"tag_open","tag_close");
+ xml_set_character_data_handler($this->parser,"cdata");
+}
+
+function parse($data) {
+ xml_parse($this->parser,$data);
+}
+
+function tag_open($parser,$tag,$attributes) {
+ var_dump($parser,$tag,$attributes);
+}
+
+function cdata($parser,$cdata) {
+ var_dump($parser,$cdata);
+}
+
+function tag_close($parser,$tag) {
+ var_dump($parser,$tag);
+}
+
+} // end of class xml
+
+$xml_parser = new xml();
+$xml_parser->parse("<A ID=\"hallo\">PHP</A>");
+?>
+]]>
+ </programlisting>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-element-handler">
+ <refnamediv>
+ <refname>xml_set_element_handler</refname>
+ <refpurpose>set up start and end element handlers</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_element_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+
+<methodparam><type>string</type><parameter>startElementHandler</parameter></methodparam>
+
+<methodparam><type>string</type><parameter>endElementHandler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <para>
+ The function named by <parameter>startElementHandler</parameter>
+ must accept three parameters:
+ <methodsynopsis>
+ <methodname><replaceable>startElementHandler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>name</parameter></methodparam>
+ <methodparam><type>array</type><parameter>attribs</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </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>
+ <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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ The function named by <parameter>endElementHandler</parameter>
+ must accept two parameters:
+ <methodsynopsis>
+ <methodname><replaceable>endElementHandler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>name</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is disabled.
+ </para>
+ <para>
+ &true; is returned if the handlers are set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-character-data-handler">
+ <refnamediv>
+ <refname>xml_set_character_data_handler</refname>
+ <refpurpose>set up character data handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_character_data_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>handler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ two parameters:
+ <methodsynopsis>
+ <methodname><replaceable>handler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem>
+ <simpara>
+ The second parameter, <parameter>data</parameter>, contains
+ the character data as a string.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is
+ disabled.
+ </para>
+ <para>
+ &true; is returned if the handler is set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-processing-instruction-handler">
+ <refnamediv>
+ <refname>xml_set_processing_instruction_handler</refname>
+ <refpurpose>
+ Set up processing instruction (PI) handler
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_processing_instruction_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>handler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <para>
+ A processing instruction has the following format:
+ <informalexample>
+ <programlisting><?
+ <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>?></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>
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ three parameters:
+ <methodsynopsis>
+ <methodname><replaceable>handler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>target</parameter></methodparam>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ </methodsynopsis>
+ <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.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>target</parameter></term>
+ <listitem><simpara>
+ The second parameter, <parameter>target</parameter>, contains
+ the PI target.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem><simpara>
+ The third parameter, <parameter>data</parameter>, contains
+ the PI data.</simpara></listitem>
+ </varlistentry>
+ </variablelist></para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is disabled.
+ </para>
+ <para>
+ &true; is returned if the handler is set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-default-handler">
+ <refnamediv>
+ <refname>xml_set_default_handler</refname>
+ <refpurpose>set up default handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_default_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>handler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ two parameters:
+ <methodsynopsis>
+ <methodname><replaceable>handler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is disabled.
+ </para>
+ <para>
+ &true; is returned if the handler is set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-unparsed-entity-decl-handler">
+ <refnamediv>
+ <refname>xml_set_unparsed_entity_decl_handler</refname>
+ <refpurpose>
+ Set up unparsed entity declaration handler
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_unparsed_entity_decl_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>handler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <para>
+ This handler will be called if the XML parser encounters an
+ external entity declaration with an NDATA declaration, like the
+ following:
+ <programlisting role="xml">
+<!ENTITY <parameter>name</parameter> {<parameter>publicId</parameter> |
+<parameter>systemId</parameter>}
+ NDATA <parameter>notationName</parameter>>
+ </programlisting>
+ </para>
+ <para>
+ See <ulink url="&url.rec-xml;#sec-external-ent">section 4.2.2 of
+ the XML 1.0 spec</ulink> for the definition of notation declared
+ external entities.
+ </para>
+ <para> The function named by
+ <parameter>handler</parameter> must accept six parameters:
+ <methodsynopsis>
+ <methodname><replaceable>handler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>entityName</parameter></methodparam>
+ <methodparam><type>string</type><parameter>base</parameter></methodparam>
+ <methodparam><type>string</type><parameter>systemId</parameter></methodparam>
+ <methodparam><type>string</type><parameter>publicId</parameter></methodparam>
+
+<methodparam><type>string</type><parameter>notationName</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>entityName</parameter></term>
+ <listitem>
+ <simpara>
+ The name of the entity that is about to be defined.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>base</parameter></term>
+ <listitem><simpara>
+ This is the base for resolving the system identifier
+ (<parameter>systemId</parameter>) of the external
+ entity. Currently this parameter will always be set to
+ an empty string.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>systemId</parameter></term>
+ <listitem>
+ <simpara>
+ System identifier for the external entity.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>publicId</parameter></term>
+ <listitem>
+ <simpara>
+ Public identifier for the external entity.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>notationName</parameter></term>
+ <listitem>
+ <simpara>
+ Name of the notation of this entity (see
+ <function>xml_set_notation_decl_handler</function>).
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is disabled.
+ </para>
+ <para>
+ &true; is returned if the handler is set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-notation-decl-handler">
+ <refnamediv>
+ <refname>xml_set_notation_decl_handler</refname>
+ <refpurpose>set up notation declaration handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_notation_decl_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>handler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <para>
+ A notation declaration is part of the document's DTD and has the
+ following format: <programlisting role="xml"><!NOTATION
+ <parameter>name</parameter> {<parameter>systemId</parameter> |
+ <parameter>publicId</parameter>}></programlisting> See <ulink
+ url="&url.rec-xml;#Notations">section 4.7 of the XML 1.0
+ spec</ulink> for the definition of notation declarations.
+ </para>
+ <para>
+ The function named by <parameter>handler</parameter> must accept
+ five parameters:
+ <methodsynopsis>
+ <methodname><replaceable>handler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+
+<methodparam><type>string</type><parameter>notationName</parameter></methodparam>
+ <methodparam><type>string</type><parameter>base</parameter></methodparam>
+ <methodparam><type>string</type><parameter>systemId</parameter></methodparam>
+ <methodparam><type>string</type><parameter>publicId</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>notationName</parameter></term>
+ <listitem>
+ <simpara>
+ This is the notation's <parameter>name</parameter>, as per
+ the notation format described above.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>base</parameter>
+ </term>
+ <listitem>
+ <simpara>
+ This is the base for resolving the system identifier
+ (<parameter>systemId</parameter>) of the notation
+ declaration. Currently this parameter will always be set to
+ an empty string.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>systemId</parameter></term>
+ <listitem>
+ <simpara>
+ System identifier of the external notation
+ declaration.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>publicId</parameter>
+ </term>
+ <listitem>
+ <simpara>
+ Public identifier of the external notation
+ declaration.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is
+ disabled.
+ </para>
+ <para>
+ &true; is returned if the handler is set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-set-external-entity-ref-handler">
+ <refnamediv>
+ <refname>xml_set_external_entity_ref_handler</refname>
+ <refpurpose>set up external entity reference handler</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_external_entity_ref_handler</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>handler</parameter></methodparam>
+ </methodsynopsis>
+ <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>
+ <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_get_error_code</function> will return <systemitem
+ class="constant">XML_ERROR_EXTERNAL_ENTITY_HANDLING</systemitem>.
+ <methodsynopsis>
+ <type>int</type><methodname><replaceable>handler</replaceable></methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+
+<methodparam><type>string</type><parameter>openEntityNames</parameter></methodparam>
+ <methodparam><type>string</type><parameter>base</parameter></methodparam>
+ <methodparam><type>string</type><parameter>systemId</parameter></methodparam>
+ <methodparam><type>string</type><parameter>publicId</parameter></methodparam>
+ </methodsynopsis>
+ <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.
+ </simpara>
+ </listitem>
+ </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).
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>base</parameter></term>
+ <listitem>
+ <simpara>
+ This is the base for resolving the system identifier
+ (<parameter>systemid</parameter>) of the external entity.
+ Currently this parameter will always be set to an empty
+ string.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ If a handler function is set to an empty string, or
+ &false;, the handler in question is
+ disabled.
+ </para>
+ <para>
+ &true; is returned if the handler is set up, &false; if
+ <parameter>parser</parameter> is not a parser.
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parse">
+ <refnamediv>
+ <refname>xml_parse</refname>
+ <refpurpose>start parsing an XML document</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_parse</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ <methodparam
+choice="opt"><type>int</type><parameter>isFinal</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to use.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </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.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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>
+ <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_get_error_code</function>,
+ <function>xml_error_string</function>,
+ <function>xml_get_current_line_number</function>,
+ <function>xml_get_current_column_number</function> and
+ <function>xml_get_current_byte_index</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-get-error-code">
+ <refnamediv>
+ <refname>xml_get_error_code</refname>
+ <refpurpose>get XML parser error code</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_get_error_code</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to get error code from.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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-error-string">
+ <refnamediv>
+ <refname>xml_error_string</refname>
+ <refpurpose>get XML parser error string</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>string</type><methodname>xml_error_string</methodname>
+ <methodparam><type>int</type><parameter>code</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>code</parameter></term>
+ <listitem>
+ <simpara>
+ An error code from <function>xml_get_error_code</function>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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-get-current-line-number">
+ <refnamediv>
+ <refname>xml_get_current_line_number</refname>
+ <refpurpose>get current line number for an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_get_current_line_number</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to get line number from.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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-get-current-column-number">
+ <refnamediv>
+ <refname>xml_get_current_column_number</refname>
+ <refpurpose>
+ Get current column number for an XML parser
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_get_current_column_number</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to get column number from.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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_get_current_line_number</function>) the parser is
+ currently at.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-get-current-byte-index">
+ <refnamediv>
+ <refname>xml_get_current_byte_index</refname>
+ <refpurpose>get current byte index for an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_get_current_byte_index</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to get byte index from.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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-parse-into-struct">
+ <refnamediv>
+ <refname>xml_parse_into_struct</refname>
+ <refpurpose>Parse XML data into an array structure</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_parse_into_struct</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ <methodparam><type>array</type><parameter>&values</parameter></methodparam>
+ <methodparam><type>array</type><parameter>&index</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ This function parses an XML file into 2 parallel array
+ structures, one (<parameter>index</parameter>) containing pointers
+ to the location of the appropriate values in the
+ <parameter>values</parameter> array. These last two parameters
+ must be passed by reference.
+ </para>
+ <para>
+ Below is an example that illustrates the internal structure of
+ the arrays being generated by the function. We use a simple
+ <literal>note</literal> tag embeded inside a
+ <literal>para</literal> tag, and then we parse this an print out
+ the structures generated:
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+$simple = "<para><note>simple note</note></para>";
+$p = xml_parser_create();
+xml_parse_into_struct($p,$simple,$vals,$index);
+xml_parser_free($p);
+echo "Index array\n";
+print_r($index);
+echo "\nVals array\n";
+print_r($vals);
+]]>
+ </programlisting>
+ </informalexample>
+ When we run that code, the output will be:
+ <informalexample>
+ <screen>
+<![CDATA[
+Index array
+Array
+(
+ [PARA] => Array
+ (
+ [0] => 0
+ [1] => 2
+ )
+
+ [NOTE] => Array
+ (
+ [0] => 1
+ )
+
+)
+
+Vals array
+Array
+(
+ [0] => Array
+ (
+ [tag] => PARA
+ [type] => open
+ [level] => 1
+ )
+
+ [1] => Array
+ (
+ [tag] => NOTE
+ [type] => complete
+ [level] => 2
+ [value] => simple note
+ )
+
+ [2] => Array
+ (
+ [tag] => PARA
+ [type] => close
+ [level] => 1
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ </para>
+ <para>
+ Event-driven parsing (based on the expat library) can get
+ complicated when you have an XML document that is complex.
+ This function does not produce a DOM style object, but it
+ generates structures amenable of being transversed in a tree
+ fashion. Thus, we can create objects representing the data
+ in the XML file easily. Let's consider the following XML file
+ representing a small database of aminoacids information:
+ <example>
+ <title>moldb.xml - small database of molecular information</title>
+ <programlisting role="xml">
+<![CDATA[
+<?xml version="1.0"?>
+<moldb>
+
+ <molecule>
+ <name>Alanine</name>
+ <symbol>ala</symbol>
+ <code>A</code>
+ <type>hydrophobic</type>
+ </molecule>
+
+ <molecule>
+ <name>Lysine</name>
+ <symbol>lys</symbol>
+ <code>K</code>
+ <type>charged</type>
+ </molecule>
+
+</moldb>
+]]>
+ </programlisting>
+ </example>
+ And some code to parse the document and generate the appropriate
+ objects:
+ <example>
+ <title>
+ parsemoldb.php - parses moldb.xml into and array of
+ molecular objects
+ </title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+class AminoAcid {
+ var $name; // aa name
+ var $symbol; // three letter symbol
+ var $code; // one letter code
+ var $type; // hydrophobic, charged or neutral
+
+ function AminoAcid ($aa) {
+ foreach ($aa as $k=>$v)
+ $this->$k = $aa[$k];
+ }
+}
+
+function readDatabase($filename) {
+ // read the xml database of aminoacids
+ $data = implode("",file($filename));
+ $parser = xml_parser_create();
+ xml_parser_set_option($parser,XML_OPTION_CASE_FOLDING,0);
+ xml_parser_set_option($parser,XML_OPTION_SKIP_WHITE,1);
+ xml_parse_into_struct($parser,$data,$values,$tags);
+ xml_parser_free($parser);
+
+ // loop through the structures
+ foreach ($tags as $key=>$val) {
+ if ($key == "molecule") {
+ $molranges = $val;
+ // each contiguous pair of array entries are the
+ // lower and upper range for each molecule definition
+ for ($i=0; $i < count($molranges); $i+=2) {
+ $offset = $molranges[$i] + 1;
+ $len = $molranges[$i + 1] - $offset;
+ $tdb[] = parseMol(array_slice($values, $offset, $len));
+ }
+ } else {
+ continue;
+ }
+ }
+ return $tdb;
+}
+
+function parseMol($mvalues) {
+ for ($i=0; $i < count($mvalues); $i++)
+ $mol[$mvalues[$i]["tag"]] = $mvalues[$i]["value"];
+ return new AminoAcid($mol);
+}
+
+$db = readDatabase("moldb.xml");
+echo "** Database of AminoAcid objects:\n";
+print_r($db);
+
+?>
+]]>
+ </programlisting>
+ </example>
+ After executing <filename>parsemoldb.php</filename>, the variable
+ <varname>$db</varname> contains an array of
+ <classname>AminoAcid</classname> objects, and the output of the
+ script confirms that:
+ <informalexample>
+ <screen>
+<![CDATA[
+** Database of AminoAcid objects:
+Array
+(
+ [0] => aminoacid Object
+ (
+ [name] => Alanine
+ [symbol] => ala
+ [code] => A
+ [type] => hydrophobic
+ )
+
+ [1] => aminoacid Object
+ (
+ [name] => Lysine
+ [symbol] => lys
+ [code] => K
+ [type] => charged
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parser-free">
+ <refnamediv>
+ <refname>xml_parser_free</refname>
+ <refpurpose>Free an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>string</type><methodname>xml_parser_free</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to free.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ <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-parser-set-option">
+ <refnamediv>
+ <refname>xml_parser_set_option</refname>
+ <refpurpose>set options in an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_parser_set_option</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>int</type><parameter>option</parameter></methodparam>
+ <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to set an option in.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>option</parameter></term>
+ <listitem>
+ <simpara>
+ Which option to set. See below.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>value</parameter></term>
+ <listitem>
+ <simpara>
+ The option's new value.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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 XML parser. Enabled by default.
+ </entry>
+ </row>
+ <row>
+ <entry>XML_OPTION_TARGET_ENCODING</entry>
+ <entry>string</entry>
+ <entry>
+ Sets which <link linkend="xml.encoding">target
+ encoding</link> to use in this XML parser. By default, it
+ is set to the same as the source encoding used by
+ <function>xml_parser_create</function>. Supported target
+ encodings are <literal>ISO-8859-1</literal>,
+ <literal>US-ASCII</literal> and <literal>UTF-8</literal>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.xml-parser-get-option">
+ <refnamediv>
+ <refname>xml_parser_get_option</refname>
+ <refpurpose>get options from an XML parser</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>mixed</type><methodname>xml_parser_get_option</methodname>
+ <methodparam><type>int</type><parameter>parser</parameter></methodparam>
+ <methodparam><type>int</type><parameter>option</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>parser</parameter></term>
+ <listitem>
+ <simpara>
+ A reference to the XML parser to get an option
+ from.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>option</parameter></term>
+ <listitem>
+ <simpara>
+ Which option to fetch. See
+ <function>xml_parser_set_option</function> for a list of
+ options.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <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_parser_set_option</function> for the list of
+ options.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.utf8-decode">
+ <refnamediv>
+ <refname>utf8_decode</refname>
+ <refpurpose>
+ Converts a string with ISO-8859-1 characters encoded with UTF-8
+ to single-byte ISO-8859-1.
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>string</type><methodname>utf8_decode</methodname>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ This function decodes <parameter>data</parameter>, assumed to be
+ <literal>UTF-8</literal> encoded, to <literal>ISO-8859-1</literal>.
+ </para>
+ <para>
+ See <function>utf8_encode</function> for an explaination of UTF-8
+ encoding.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.utf8-encode">
+ <refnamediv>
+ <refname>utf8_encode</refname>
+ <refpurpose>encodes an ISO-8859-1 string to UTF-8</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>string</type><methodname>utf8_encode</methodname>
+ <methodparam><type>string</type><parameter>data</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ This function encodes the string <parameter>data</parameter> to
+ <literal>UTF-8</literal>, and returns the encoded version.
+ <literal>UTF-8</literal> is a standard mechanism used by
+ <acronym>Unicode</acronym>for encoding <glossterm>wide
+ character</glossterm> values into a byte stream.
+ <literal>UTF-8</literal> is transparent to plain
+ <abbrev>ASCII</abbrev> characters, is self-synchronized (meaning
+ it is possible for a program to figure out where in the
+ bytestream characters start) and can be used with normal string
+ comparison functions for sorting and such. PHP encodes
+ <literal>UTF-8</literal> characters in up to four bytes, like
+ this:
+ <table>
+ <title>UTF-8 encoding</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>bytes</entry>
+ <entry>bits</entry>
+ <entry>representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1</entry>
+ <entry>7</entry>
+ <entry>0bbbbbbb</entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>11</entry>
+ <entry>110bbbbb 10bbbbbb</entry>
+ </row>
+ <row>
+ <entry>3</entry>
+ <entry>16</entry>
+ <entry>1110bbbb 10bbbbbb 10bbbbbb</entry>
+ </row>
+ <row>
+ <entry>4</entry>
+ <entry>21</entry>
+ <entry>11110bbb 10bbbbbb 10bbbbbb 10bbbbbb</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ Each <replaceable>b</replaceable> represents a bit that can be
+ used to store character data.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id='function.xml-parser-create-ns'>
+ <refnamediv>
+ <refname>xml_parser_create_ns</refname>
+ <refpurpose>
+ Create an XML parser
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_parser_create_ns</methodname>
+ <methodparam
+choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
+ <methodparam
+choice="opt"><type>string</type><parameter>sep</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ &warn.undocumented.func;
+ </para>
+ </refsect1>
+ </refentry>
+
+
+
+ <refentry id='function.xml-set-end-namespace-decl-handler'>
+ <refnamediv>
+ <refname>xml_set_end_namespace_decl_handler</refname>
+ <refpurpose>
+ Set up character data handler
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_end_namespace_decl_handler</methodname>
+ <methodparam><type>int</type><parameter>pind</parameter></methodparam>
+ <methodparam><type>string</type><parameter>hdl</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ &warn.undocumented.func;
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+
+
+ <refentry id='function.xml-set-start-namespace-decl-handler'>
+ <refnamediv>
+ <refname>xml_set_start_namespace_decl_handler</refname>
+ <refpurpose>
+ Set up character data handler
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>xml_set_start_namespace_decl_handler</methodname>
+ <methodparam><type>int</type><parameter>pind</parameter></methodparam>
+ <methodparam><type>string</type><parameter>hdl</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ &warn.undocumented.func;
+ </para>
+ ¬e.func-callback;
+ </refsect1>
+ </refentry>
+
+
+ </reference>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
+
