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