darvina Tue Apr 23 15:21:01 2002 EDT
Added files:
/phpdoc/it/reference/xml functions.xml reference.xml
Log:
Italian translation
Index: phpdoc/it/reference/xml/functions.xml
+++ phpdoc/it/reference/xml/functions.xml
&reference.xml.functions.utf8-decode;
&reference.xml.functions.utf8-encode;
&reference.xml.functions.xml-error-string;
&reference.xml.functions.xml-get-current-byte-index;
&reference.xml.functions.xml-get-current-column-number;
&reference.xml.functions.xml-get-current-line-number;
&reference.xml.functions.xml-get-error-code;
&reference.xml.functions.xml-parse;
&reference.xml.functions.xml-parse-into-struct;
&reference.xml.functions.xml-parser-create;
&reference.xml.functions.xml-parser-create-ns;
&reference.xml.functions.xml-parser-free;
&reference.xml.functions.xml-parser-get-option;
&reference.xml.functions.xml-parser-set-option;
&reference.xml.functions.xml-set-character-data-handler;
&reference.xml.functions.xml-set-default-handler;
&reference.xml.functions.xml-set-element-handler;
&reference.xml.functions.xml-set-end-namespace-decl-handler;
&reference.xml.functions.xml-set-external-entity-ref-handler;
&reference.xml.functions.xml-set-notation-decl-handler;
&reference.xml.functions.xml-set-object;
&reference.xml.functions.xml-set-processing-instruction-handler;
&reference.xml.functions.xml-set-start-namespace-decl-handler;
&reference.xml.functions.xml-set-unparsed-entity-decl-handler;
Index: phpdoc/it/reference/xml/reference.xml
+++ phpdoc/it/reference/xml/reference.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.3 Maintainer: darvina Status: ready -->
<reference id="ref.xml">
<title>Funzioni relative al parser XML</title>
<titleabbrev>XML</titleabbrev>
<partintro>
<section id="xml.partintro">
<title>Introduzione</title>
<section id="xml.intro">
<title>XML</title>
<para>
XML (eXtensible Markup Language) � un formato utilizzato per l'interscambio
di documenti strutturati sul Web. Questo � uno standard definito da
The World Wide Web consortium (W3C). Maggiori informazioni su XML e
le relative tecnologie possono essere reperite all'indirizzo <ulink
url="&url.xml;">&url.xml;</ulink>.
</para>
</section>
<section id="xml.install">
<title>Installazione</title>
<para>
Questa estensione utilizza il modulo <productname>expat</productname>, che pu�
essere reperito all'indirizzo <ulink url="&url.expat;">&url.expat;</ulink>. Il
Makefile fornito con expat, per default, non compila la libreria,
occorre utilizzare le seguenti istruzioni per il comando make:
<programlisting role="makefile">
<![CDATA[
libexpat.a: $(OBJS)
ar -rc $@ $(OBJS)
ranlib $@
]]>
</programlisting>
Il sorgente in formato package RPM pu� essere reperito all'indirizzo <ulink
url="&url.expat.rpm;">&url.expat.rpm;</ulink>.
</para>
<para>
Si noti che se si usa Apache 1.3.7 o successive, la libreria
expat � gi� presente. In questo caso configurare PHP utilizzando
<option role="configure">--with-xml</option> (senza specificare
percorsi addizionali) e automaticamente verr� utilizzata la libreria
expat presente in Apache.
</para>
<para>
Sui sistemi Unix eseguire <command>configure</command> con l'opzione
<option role="configure">--with-xml</option>. Il compilatore � in grado
di trovare sul sistema la libreria <productname>expat</productname>
installata. Se si compila il PHP come modulo per Apache, dalla
versione 1.3.9 e successive, il PHP automaticamente utilizzer�
la libreria <productname>expat</productname> presente in Apache.
Pu� essere necessario configurare le variabili d'ambiente
<envar>CPPFLAGS</envar> e
<envar>LDFLAGS</envar> prima di eseguire
<command>configure</command> se si ha installato expat in qualche posto
particolare.
</para>
<para>
Compila del PHP. <emphasis>Tada!</emphasis> Questo � quanto.
</para>
</section>
<section id="xml.about">
<title>Note su questa estensione</title>
<para>
Questa estensione di PHP implementa il supporto per il modulo
<productname>expat</productname> di James Clark in PHP. Questo strumento permette
il parsing, ma non la validazione, di documenti XML. Il modulo supporta
tre tipi di <link linkend="xml.encoding">codifica di caratteri</link>
gi� presenti in PHP: <literal>US-ASCII</literal>,
<literal>ISO-8859-1</literal> e <literal>UTF-8</literal>.
La codifica <literal>UTF-16</literal> non � supportata.
</para>
<para>
Questa estensione permette di <link
linkend="function.xml-parser-create">creare un parser XML</link>
e di definire dei <emphasis>gestori</emphasis> per i differenti
eventi di XML. Ciascun parser XML ha diversi <link
linkend="function.xml-parser-set-option">parametri</link>
configurabili.
</para>
<para>
I gestori di eventi XML definiti sono:
<table>
<title>Gestori XML supportati</title>
<tgroup cols="2">
<thead>
<row>
<entry>Funzione PHP per attivare il gestore</entry>
<entry>Descrizione dell'evento</entry>
</row>
</thead>
<tbody>
<row>
<entry><function>xml_set_element_handler</function></entry>
<entry>
L'evento 'Elemento' viene attivato quando il parser XML
incontra i tag di apertura e chiusura. Esistono gestori separati
per i tag di apertura e di chiusura.
</entry>
</row>
<row>
<entry>
<function>xml_set_character_data_handler</function>
</entry>
<entry>
Sono dati tutti i contenuti dei documenti XML che non siano
dei markup, compresi gli spazi tra i tag. Si noti che
il parser XML non aggiunge ne rimuove spazi, � compito
dell'applicazione decidere se gli spazi siano
significativi o meno.
</entry>
</row>
<row>
<entry>
<function>xml_set_processing_instruction_handler</function>
</entry>
<entry>
Ai programmatori PHP dovrebbe gi� essere familiare le istruzioni di processo
(PIs). <?php ?> � un istruzione di
processo dove <replaceable>php</replaceable> viene definito
"PI target". La gestione di questi � specifica dell'applicazione,
tranne che tutti i PI targets che iniziano con "XML",
questi sono riservati.
</entry>
</row>
<row>
<entry><function>xml_set_default_handler</function></entry>
<entry>
Tutto ci� che non rientra negli altri gestori ricade nel gestore
di default. In questo gestore si ha elementi come
la dichiarazione dei tipo documento.
</entry>
</row>
<row>
<entry>
<function>xml_set_unparsed_entity_decl_handler</function>
</entry>
<entry>
Questo gestore viene richiamato per la gestione di entit� non analizzate
(NDATA).
</entry>
</row>
<row>
<entry>
<function>xml_set_notation_decl_handler</function>
</entry>
<entry>
Questo gestore viene richiamato per la dichiarazione di una notazione.
</entry>
</row>
<row>
<entry>
<function>xml_set_external_entity_ref_handler</function>
</entry>
<entry>
Questo gestore viene richiamato quando il parser XML incontra un
riferimento ad una entit� esterna analizzata.
Questa pu� essere, ad esempio, un riferimento ad un file o ad un URL.
Vedere <link linkend="example.xml-external-entity">esempio di entit�
esterne</link> per una dimostrazione.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="xml.case-folding">
<title>Case Folding</title>
<para>
Le funzioni di gestione degli elementi possono ottenere i nomi dei propri
elementi
<glossterm>case-folded</glossterm>. Lo standard XML definisce il case-folding
come "un processo applicato ad una sequenza di caratteri,
nel quale quelli identificati come non-maiuscoli sono sostituiti
dai corrispettivi caratteri maiuscoli". In altre parole, in XML
il termine case-folding indica, semplicemente, la conversione a lettere
maiuscole.
</para>
<para>
Per default, i nomi di tutti gli elementi passati alle funzioni di
gestione sono case-folded. Questo comportamento pu� essere verificato e
controllato nel parser XML
rispettivamente con le funzioni
<function>xml_parser_get_option</function> e
<function>xml_parser_set_option</function>.
</para>
</section>
<section id="xml.error-codes">
<title>Codici di errore</title>
<para>
Vengono definite le seguenti costanti per i codici di errore XML
(come restituito da <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>
</section>
<section id="xml.encoding">
<title>Codifica dei caratteri</title>
<para>
L'estensione XML di PHP supporta il set di caratteri
<ulink url="&url.unicode;">Unicode</ulink> tramite
differenti <glossterm>codifiche di caratteri</glossterm>.
Esistono due tipi di codifiche di caratteri, <glossterm>source
encoding</glossterm> e <glossterm>target encoding</glossterm>.
Nella rappresentazione interna dei documenti il PHP utilizza sempre
la codifica <literal>UTF-8</literal>.
</para>
<para>
La codifica del sorgente viene eseguita quando un documento XML viene <link
linkend="function.xml-parse">analizzato</link>. Durante la <link
linkend="function.xml-parser-create">creazione di un parser
XML</link>, si pu� specificare la codifica del sorgente (questa codifica
non potr� essere variata in seguito nel corso della vita del parser XML).
Le codifiche supportate sono <literal>ISO-8859-1</literal>,
<literal>US-ASCII</literal> e <literal>UTF-8</literal>.
Le prime due sono codifiche a singolo byte, ci� significa che
ciascun carattere � rappresentato da un byte singolo,
mentre la codifica <literal>UTF-8</literal> pu� rappresentare caratteri
composti da un numero variabile di bit (fino a 21) usando da uno fino
a quattro byte. La codifica del sorgente utilizzata per default dal PHP �
<literal>ISO-8859-1</literal>.
</para>
<para>
La codifica per il destinatario viene eseguita quando il PHP passa i dati alle
funzioni di
gestione del XML. Quando viene creato un parser XML, la codifica
per il destinatario viene posta uguale alla codifica del sorgente, ma ci� pu�
essere variato. La codifica per il destinatario viene applicata ai caratteri dei
dati,
ai nomi delle tag e alle istruzioni di processamento.
</para>
<para>
Se il parser XML incontra caratteri esterni al range dei caratteri
rappresentabili dalla codifica, restituir� un
errore.
</para>
<para>
Se il PHP incontra nel documento analizzato dei caratteri che non
� in grado di rappresentare con la codifica scelta per il destinatario, "degrada"
il carattere problematico. Attaualmente ci� significa sostuire il
carattere in questione con un punto interrogativo.
</para>
</section>
</section>
<section id="xml.examples">
<title>Alcuni esempi</title>
<para>
Di seguito verranno illustrati alcuni esempi di script PHP per il parsing di
documenti XML.
</para>
<section id="example.xml-structure">
<title>Esempio della struttura degli elementi XML</title>
<para>
Il primo esempio visualizza, con indentazione, la struttura degli
elementi di apertura di un documento.
<example>
<title>Visualizza la struttura degli elementi XML</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>
</section>
<section id="example.xml-map-tags">
<title>Esempio di mappatura dei tag XML</title>
<para>
<example>
<title>Conversione da XML a HTML</title>
<para>
Il seguente esempio converte i tag di un documento XML in
tag HTML. Gli elementi non trovati nella matrice delle tag saranno ignorati.
Ovviamente questo esempio funziona solo con uno specifico tipo di
documento XML:
<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();
// Si utilizza il case-folding per essere certi di trovare le 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("Non si riesce ad aprire il documento XML");
}
while ($data = fread($fp, 4096)) {
if (!xml_parse($xml_parser, $data, feof($fp))) {
die(sprintf("Errore XML: %s alla linea %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>
</section>
<section id="example.xml-external-entity">
<title>Esempio di entit� XML esterna</title>
<para>
Questo esempio evidenzia il codice XML. Si illustrer� come utilizzare
il riferimento ad entit� esterne per includere ed analizzare altri
documenti, sar� illustrato anche come processare le PIs, ed il modo
per determinare l'affidabilit� del codice contenuto dalle PIs.
</para>
<para>
I documenti XML che possono essere usati per questo esempio sono
presenti dopo l'esempio (<filename>xmltest.xml</filename> e
<filename>xmltest2.xml</filename>.)
</para>
<para>
<example>
<title>Esempio di entit� esterna</title>
<programlisting role="php">
<![CDATA[
<?php
$file = "xmltest.xml";
function trustedFile($file) {
// si considera affidabili soltanto i file locali del proprio utente
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;
// Se il documento analizzato � "affidabile", si pu� dire che � sicura
// l'esecuzione del codice PHP presente in esso. In caso contrario si
visualizza
// il codice.
if (trustedFile($parser_file[$parser])) {
eval($data);
} else {
printf("Codice PHP inaffidabile: <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("Non si riesce ad aprire l'entit� %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("Non si riesce ad aprire il documento XML");
}
print "<pre>";
while ($data = fread($fp, 4096)) {
if (!xml_parse($xml_parser, $data, feof($fp))) {
die(sprintf("Errore XML: %s alla linea %d\n",
xml_error_string(xml_get_error_code($xml_parser)),
xml_get_current_line_number($xml_parser)));
}
}
print "</pre>";
print "parsing completato\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;
<section id="about">
<title>Circa questo documento</title>
<para>
<!-- questo � un commento -->
<?php print 'Ciao! Questa � la versione di PHP '.phpversion(); ?>
</para>
</section>
</chapter>
]]>
</programlisting>
</example>
</para>
<para id="example.xml-xmltest2.xml">
Questo file � stato richiamato da <filename>xmltest.xml</filename>:
<example>
<title>xmltest2.xml</title>
<programlisting role="xml">
<![CDATA[
<?xml version="1.0"?>
<!DOCTYPE foo [
<!ENTITY testEnt "Entit� di test">
]>
<foo>
<element attrib="value"/>
&testEnt;
<?php print "Questa � una ulteriore riga di codice PHP eseguito."; ?>
</foo>
]]>
</programlisting>
</example>
</para>
</section>
</section>
</partintro>
&reference.xml.functions;
</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
-->
