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

<!-- $Revision$ -->

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

<!-- Reviewed: yes -->

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

<refnamediv>

<refname>xml_parse_into_struct</refname>

<refpurpose>Analiza una estructura 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>

Esta función analiza la cadena XML <parameter>data</parameter> y la coloca en dos arrays: el primero <parameter>index</parameter> contiene punteros a la posición de los valores correspondientes en el array <parameter>values</parameter>. Estos dos parámetros se pasan por referencia.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Una referencia a un analizador XML.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Un string que contiene los datos XML.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Un array que contiene los valores de los datos XML.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Un array que contiene los punteros a los valores apropiados en el parámetro $values.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

<function>xml_parse_into_struct</function> retorna 0 si ocurre un error y 1 en caso de éxito. Esto no es lo mismo que &false; y &true;, por lo que se debe tener precaución con los operadores como ===.

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

A continuación, se encuentra un ejemplo que ilustra la estructura de los dos arrays generados por la función. Se utiliza una etiqueta simple <literal>note</literal>, colocada dentro de otra etiqueta <literal>para</literal>. Se analiza todo y se muestra la estructura generada:

<example>

<title>Ejemplo con <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 "Array Index\n";

print_r($index);

echo "\nArray Vals\n";

print_r($vals);

?>

]]>

</programlisting>

<para>

Mostrará:

</para>

<screen>

<![CDATA[

Array Index

Array

(

[PARA] => Array

(

[0] => 0

[1] => 2

)

[NOTE] => Array

(

[0] => 1

)

)

Array Vals

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>

El análisis basado en eventos (como el de expat) puede resultar complejo cuando el documento XML es complejo. <function>xml_parse_into_struct</function> no genera objetos de tipo DOM, sino que genera estructuras que pueden ser recorridas de manera similar a un árbol. Consideremos el siguiente fichero, que representa una pequeña base de datos XML:

<example>

<title>moldb.xml - Pequeña base de datos molecular</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>

Y ahora, un código que analiza el documento y genera los objetos correspondientes:

<example>

<title>

parsemoldb.php: Analiza moldb.xml y crea un array de objetos moleculares

</title>

<programlisting role="php">

<![CDATA[

<?php

class AminoAcid {

var $name; // nombre aa

var $symbol; // símbolo de tres letras

var $code; // código de una letra

var $type; // hidrofóbico, cargado o neutro

function __construct ($aa) {

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

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

}

}

function readDatabase($filename)

{

// lee la base de datos xml de aminoácidos

$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);

// bucle a través de las estructuras

foreach ($tags as $key=>$val) {

if ($key == "molecule") {

$molranges = $val;

// cada par contiguo de entradas del array son los límites inferior y superior para cada definición de molécula

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 "** Base de objetos AminoAcid:\n";

print_r($db);

?>

]]>

</programlisting>

</example>

Tras la ejecución de <filename>parsemoldb.php</filename>, la variable <varname>$db</varname> contiene un array de objetos <classname>AminoAcid</classname>, y la salida lo confirma:

<informalexample>

<screen>

<![CDATA[

** Base de objetos AminoAcid:

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

-->