xml-parse-into-struct.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 886c5c639f2f33a01278d61c1d72ef39af880714 Maintainer: pastore Status: ready -->
<!-- CREDITS: darvina -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.xml-parse-into-struct">
 <refnamediv>
  <refname>xml_parse_into_struct</refname>
  <refpurpose>Analizza i dati XML in una struttura 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>
   Questa funzione analizza una stringa XML in 2 strutture array parallele,
   una (<parameter>index</parameter>) contiene i puntatori alla posizione dei
   valori opportuni nell'array <parameter>values</parameter>. Quest'ultimi
   due parametri devono essere passati per riferimento.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>parser</parameter></term>
     <listitem>
      <para>
       Un riferimento al parser XML.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data</parameter></term>
     <listitem>
      <para>
       Una stringa contenente i dati XML.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>values</parameter></term>
     <listitem>
      <para>
       Una array contenente i valori dei dati XML
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>index</parameter></term>
     <listitem>
      <para>
       Un array contenente i puntatori alla posizione degli opportuni valori in $values.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>xml_parse_into_struct</function> restituisce 0 per fallimento e 1 per
   successo. Questo non è lo stesso di &false; e &true;, fare attenzione con
   gli operatori come ===.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   Nell'esempio seguente si illustra la struttura interna degli
   array generati da questa funzione. Utilizziamo un semplice
   tag <literal>note</literal> incorporato all'interno di un
   tag <literal>para</literal>, e quindi lo si analizzerà e stamperemo
   le strutture generate:
   <example>
    <title>Esempio di uso <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);
xml_parser_free($p);
echo "Index array\n";
print_r($index);
echo "\nVals array\n";
print_r($vals);
?>
]]>
    </programlisting>
    <para>
     Eseguendo questo codice si avrà come output:
    </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>
   Un parsing event-driven (basato sulla libreria expat) può essere
   molto complicato se si deve trattare un documento XML complesso.
   Questa funzione non produce un oggetto in stile DOM, ma 
   genera una struttura che permette di essere gestita a modo di
   albero. Quindi si possono facilmente creare oggetti rappresentanti i dati
   del file XML. Si consideri il seguente file XML rappresentante
   un piccolo database di informazioni sugli aminoacidi.
   <example>
    <title>moldb.xml - piccolo database di informazioni sulle molecole</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>
   Un codice per analizzare il documento e generare gli oggetti
   appropriati:
   <example>
    <title>
     parsemoldb.php - analizza moldb.xml in un array di
     oggetti molecolari
    </title>
    <programlisting role="php">
<![CDATA[
<?php

class AminoAcid {
    var $name;  // nome aa
    var $symbol;    // simbolo di tre lettere
    var $code;  // codice di una lettera
    var $type;  // idrofobo, carico o neutro
    
    function AminoAcid ($aa) 
    {
        foreach ($aa as $k=>$v)
            $this->$k = $aa[$k];
    }
}

function readDatabase($filename) 
{
    // legge il database XML di amminoacidi
    $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);

    // cicla attraverso le strutture
    foreach ($tags as $key=>$val) {
        if ($key == "molecule") {
            $molranges = $val;
            // ciascuna coppia di elementi contigua dell'array è
            // l'intervallo inferiore o superiore per la definizione di ciascuna molecola
            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 degli oggetti Aminoacidi:\n";
print_r($db);

?>
]]>
    </programlisting>
   </example>
   Dopo l'esecuzione di <filename>parsemoldb.php</filename>, la variabile
   <varname>$db</varname> contiene un array di oggetti
   <classname>AminoAcid</classname>, e ciò viene confermato
   dall'output dello script:
   <informalexample>
    <screen>
<![CDATA[
** Database di oggetti Aminoacidi:
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
-->