<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: b47e4bea197126359815c5e43403c4b77a0aaaa7 Maintainer: class007 Status: ready -->

<!-- CREDITS: mowangjuanzi, Luffy -->

<refentry xml:id="function.xml-parse-into-struct" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>xml_parse_into_struct</refname>

<refpurpose>解析 XML 数据到数组中</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>int</type><type>false</type></type><methodname>xml_parse_into_struct</methodname>

<methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>

<methodparam><type>string</type><parameter>data</parameter></methodparam>

<methodparam><type>array</type><parameter role="reference">values</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter role="reference">index</parameter><initializer>&null;</initializer></methodparam>

</methodsynopsis>

<para>

该函数解析 XML 字符串到两个对应的数组中，一个（<parameter>index</parameter>）含有指向 <parameter>values</parameter>

数组中对应值的指针。最后两个参数必须通过引用传递。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>parser</parameter></term>

<listitem>

<para>

引用的 XML 解析器。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>data</parameter></term>

<listitem>

<para>

包含 XML 数据的字符串。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>values</parameter></term>

<listitem>

<para>

包含 XML 数据值的数组

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>index</parameter></term>

<listitem>

<para>

包含指向 $values 中适当值位置的指针的数组。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

<function>xml_parse_into_struct</function> 失败时返回 0，成功返回 1。这和 &false; 与 &true; 不同，使用运算符（比如 ===）时要小心。

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

&xml.changelog.parser-param;

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

下面的示例说明了函数生成的数组的内部结构。使用嵌入在 <literal>para</literal> 标签中的简单 <literal>note</literal> 标签，然后解析并打印出生成的结构：

<example>

<title><function>xml_parse_into_struct</function> 示例</title>

<programlisting role="php">

<![CDATA[

<?php

$simple = "<para><note>simple note</note></para>";

$p = xml_parser_create();

xml_parse_into_struct($p, $simple, $vals, $index);

echo "Index array\n";

print_r($index);

echo "\nVals array\n";

print_r($vals);

?>

]]>

</programlisting>

<para>

运行以上代码，输出将是：

</para>

<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>

</example>

</para>

<para>

当 XML 文档很复杂时，事件驱动的解析（基于 expat 库）会变得复杂。此函数不会生成 DOM 风格对象，但会生成适合以树形方式遍历的结构。因此，可以轻松地创建表示 XML 文件中数据的对象。考虑以下表示氨基酸信息小型数据库的 XML 文件：

<example>

<title>moldb.xml - 分子信息的小型数据库</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>

还有一些代码用来解析文档并生成相应对象：

<example>

<title>

parsemoldb.php - 将 moldb.xml 解析到分子（molecular）对象的数组中

</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 __construct ($aa)

{

foreach ($aa as $k=>$v)

$this->$k = $aa[$k];

}

}

function readDatabase($filename)

{

// read the XML database of aminoacids

$data = file_get_contents($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);

unset($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>

在执行完 <filename>parsemoldb.php</filename> 后，变量 <varname>$db</varname> 将包含有由 <classname>AminoAcid</classname> 对象组成的数组，该脚本的输出如下：

<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>

<!-- 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:"~/.phpdoc/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

-->