xml-parse-into-struct.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 886c5c639f2f33a01278d61c1d72ef39af880714 Maintainer: yago Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.xml-parse-into-struct">
 <refnamediv>
  <refname>xml_parse_into_struct</refname>
  <refpurpose>Interpreta datos XML en una estructura de array</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>xml_parse_into_struct</methodname>
   <methodparam><type>resource</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></methodparam>
  </methodsynopsis>
  <para>
   Esta función interpreta una cadena XML en dos estructuras paralelas de array, una
   (<parameter>index</parameter>) que contiene punteros a la ubicación de los
   valores adecuados en el array <parameter>values</parameter>. Estos dos últimos
   parámetros deben ser pasados por referencia.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>parser</parameter></term>
     <listitem>
      <para>
       Una referencia para el interprete de XML.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data</parameter></term>
     <listitem>
      <para>
       Una cadena 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 apuntadores hacia la ubicación de los valores apropiados en $values.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>xml_parse_into_struct</function> retorna 0 cuando falla y 1 si es
   exitoso. Esto no es lo mismo que &false; y &true;, tener cuidado con
   operadores tales como ===.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   A continuación se muestra un ejemplo que ilustra la estructura interna de
   los arrays que se generan por la función. Se usa una etiqueta simple
   <literal>note</literal> incrustada dentro de una etiqueta
   <literal>para</literal> y entonces esto se interpreta y se muestran
   las estructuras generadas:
   <example>
    <title>Ejemplo de <function>xml_parse_into_struct</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$simple = "<para><note>Nota Simple</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>
    <para>
     Cuando se ejecuta este código, la salida será:
    </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>
   El análisis por eventos (basado en la biblioteca expat) puede ser más 
   complicado cuando se tiene un documento XML que es complejo.
   Esta función no produce un objeto de estilo DOM, pero
   genera estructuras susceptibles de ser transversionadas en forma
   de árbol. Por lo tanto, se pueden crear objetos que representan los datos
   en el archivo XML con facilidad. Considere el siguiente archivo XML
   que representa una pequeña base de datos con información de aminoácidos:
   <example>
    <title>moldb.xml - pequeña base de datos de información 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 algo de código para interpretar el documento y generar los objetos
   adecuados:
   <example>
    <title>
     parsemoldb.php - interpreta moldb.xml dentro de 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 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);

    // repetir a través de las extructuras
    foreach ($tags as $key=>$val) {
        if ($key == "molecule") {
            $molranges = $val;
            // cada par contiguo de netradas de array son los 
            // rangos altos y bajos 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 "** Database of AminoAcid objects:\n";
print_r($db);

?>
]]>
    </programlisting>
   </example>
   Después de ejecutar <filename>parsemoldb.php</filename>, la variable
   <varname>$db</varname> contiene un array de
   objetos de <classname>AminoAcid</classname> y la salida del
   script confirma que:
   <informalexample>
    <screen>
<![CDATA[
** Base de datos de objetos AminoÁcidos:
Array
(
    [0] => Objeto aminoácido
        (
            [name] => Alanine
            [symbol] => ala
            [code] => A
            [type] => hydrophobic
        )

    [1] => Objeto aminoácido
        (
            [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
-->