13.2 `sgmllib` -- Simple SGML parser

Questo modulo definisce la classe SGMLParser che serve da base per analizzare file di testo formattati in SGML (Standard Generalized Mark-up Language). Infatti non fornisce un completo parser SGML - è solamente un parser SGML fino a che viene usato da HTML, ed il modulo esiste solamente come base per il modulo htmllib. Un altro parser HTML che supporta XHTML ed offre un'interfaccia leggermente differente è disponibile nel modulo HTMLParser.

class SGMLParser( )

La classe SGMLParser si istanzia senza argomenti. Il parser è progettato per riconoscere i seguenti costrutti:

Tag di apertura e chiusura, rispettivamente nella forma "<tag attr="value" ...>" e "</tag>", rispettivamente.
Riferimenti a codici di controllo numerici nella forma "&#name;".
Riferimenti ad entità nella forma "&name;".
Commenti SGML nella forma "". Notare che codici di controllo relativi a spazi, tabulazioni e fine riga sono permessi se inseriti tra ">" ed immediatamente preceduti da "--".

Le istanze di SGMLParser hanno la seguente interfaccia a metodi:

reset( ): Reinizializza l'istanza. Tutti i dati non analizzati andranno persi. Questo metodo viene chiamato implicitamente al momento dell'istanziazione.

setnomoretags( ): Ferma l'analisi dei tag. Tratta tutti i dati seguenti come input letterali (CDATA). Questo metodo è fornito solo perché così può essere implementato il tag HTML <PLAINTEXT>.

setliteral( ): Entra in modalità stringa costante (modalità CDATA).

feed( data): Invia dei dati al parser. Viene analizzato finché consiste di elementi completi; i dati incompleti vengono bufferizzati fino a che non saranno inviati altri dati o non sia chiamato il metodo close().

close( ): Forza l'analisi di tutti i dati bufferizzati come se fossero seguiti da un carattere di marcatura fine del file. Questo metodo può essere ridefinito tramite una classe derivata, per definire ulteriori analisi alla fine dell'input, ma la versione ridefinita dovrebbe sempre chiamare il metodo close().

get_starttag_text( ): Restituisce il testo dell'ultimo tag di apertura analizzato. Normalmente questo non dovrebbe essere necessario per una analisi, ma potrebbe essere utile da distribuire con HTML ``così come sviluppato'' o per rigenerare l'input con cambiamenti minimali (spazi tra gli attributi preservati, etc. etc.).

handle_starttag( tag, method, attributes): Questo metodo viene invocato per gestire l'apertura di un tag per il quale sia stato definito il metodo start_tag() o il do_tag(). L'argomento tag è il nome del tag convertito in caratteri minuscoli, e l'argomento method è il metodo associato che dovrebbe essere usato per supportare l'interpretazione semantica del tag di apertura. L'argomento attributes è una lista di coppie (nome, valore) che contengono gli attributi trovati tra le parentesi angolari <> del tag. Il nome viene convertito in caratteri minuscoli mentre le virgolette doppie ed i backslash vengono interpretati. Per esempio per il tag <A HREF="http://www.cwi.nl/">, questo metodo verrà chiamato con "handle_starttag('a', [('href', 'http://www.cwi.nl/')])". L'implementazione base semplicemente chiama method con attributes come unico argomento.

handle_endtag( tag, method): Questo metodo viene invocato per gestire la chiusura di un tag per il quale un metodo end_tag() sia stato definito. L'argomento tag è il nome del tag in caratteri minuscoli e l'argomento method è il metodo associato che dovrebbe essere utilizzato per supportare l'interpretazione semantica della chiusura del tag. Se non è stato definito alcun metodo end_tag() per l'elemento che è stato chiuso, questo gestore non viene invocato. L'implementazione base chiama semplicemente method.

handle_data( data): Questo metodo viene invocato per analizzare dati arbitrari. È progettato per essere sovrascritto da una classe derivata; l'implementazione nella classe base non fa nulla.

handle_charref( ref): Questo metodo viene chiamato per analizzare un riferimento a caratteri nella forma "&#ref;". Nell'implementazione base, ref deve essere un numero decimale compreso tra 0 e 255. Il metodo converte il carattere in ASCII e chiama il metodo handle_data() con il carattere come argomento. Se ref non è valido o è fuori dai valori consentiti, viene chiamato il metodo unknown_charref(ref) che gestisce l'errore. Una sotto classe deve sovrascrivere questo metodo per fornire il supporto per le entità a caratteri viste sopra.

handle_entityref( ref): Questo metodo viene invocato per analizzare un riferimento generico ad entità nella forma "&ref;" dove ref è un riferimento generico ad entità. Cerca ref nella variabile d'istanza (o classe) entitydefs che dovrebbe essere una mappatura dai nomi di entità alle corrispondenti traduzioni. Se viene trovata una traduzione, il metodo invoca handle_data() con la traduzione; altrimenti, chiama il metodo unknown_entityref(ref). La variabile predefinita entitydefs definisce le traduzioni per &, &apos, >, < e ".

handle_comment( comment): Questo metodo viene chiamato quando si incontra un commento. L'argomento comment è una stringa che contiene il testo compreso tra "", delimitatori esclusi. Per esempio il commento "" fa in modo che il metodo venga chiamato con 'text' come argomento. Il metodo predefinito non fa niente.

handle_decl( data): Questo metodo viene chiamato quando il parser legge una dichiarazione SGML. In pratica, la dichiarazione DOCTYPE è l'unica che viene osservata in documenti HTML, ma il parser non discrimina dichiarazioni differenti (o errate). Sottosezioni all'interno di dichiarazioni DOCTYPE non vengono supportate. Il parametro data consiste nell'intero contenuto della dichiarazione nel marcatore <!...>. L'implementazione predefinita non fa niente.

report_unbalanced( tag): Questo metodo viene chiamato incontrando un tag di chiusura a cui manca il corrispettivo tag di apertura.

unknown_starttag( tag, attributes): Questo metodo viene chiamato incontrando un tag di apertura sconosciuto. È stato progettato per essere sovrascritto da una classe derivata; l'implementazione della classe base non fa niente.

unknown_endtag( tag): Questo metodo viene chiamato incontrando un tag di chiusura sconosciuto. È stato progettato per essere sovrascritto da una classe derivata; l'implementazione della classe base non fa niente.

unknown_charref( ref): Questo metodo viene invocato per elaborare riferimenti irrisolvibili a caratteri numerici. Vedere handle_charref() per determinare cosa viene gestito in modo predefinito. È stato progettato per essere sovrascritto da una classe derivata; l'implementazione della classe base non fa niente.

unknown_entityref( ref): Questo metodo viene chiamato per processare un riferimento ad un'entità sconosciuta. È stato progettato per essere sovrascritto da una classe derivata; l'implementazione della classe base non fa niente.

Oltre a poter estendere o sovrascrivere i metodi elencati sopra, le classi derivate possono anche definire metodi della seguente forma, per definire come comportarsi con tag specifici. In nomi dei tag nel flusso in input non sono sensibili alle differenze tra maiuscole e minuscole; i tag che si trovano nei nomi dei metodi invece devono essere scritti minuscoli:

start_tag( attributes): Questo metodo viene chiamato per processare un tag di apertura chiamato tag. Ha la preferenza rispetto al metodo do_tag(). L'argomento attributes ha lo stesso significato dell'omonimo argomento descritto sopra per handle_starttag().

do_tag( attributes): Questo metodo viene chiamato per processare un tag di apertura chiamato tag che non presenta un tag di chiusura. L'argomento attributes ha lo stesso significato dell'omonimo argomento descritto sopra per handle_starttag().

end_tag( ): Questo metodo è richiamato per processare un tag di chiusura chiamato tag.

Notare che il parser mantiene uno stack di elementi aperti per i quali non è ancora stato trovato un tag di chiusura. Solo i tag elaborati da start_tag() vengono messi in questo stack, la definizione del metodo end_tag() è facoltativa per questi tag. Per i tag elaborati dal metodo do_tag() o da unknown_tag(), non deve essere definito nessun metodo end_tag(), se fosse definito non verrebbe comunque usato. Se entrambi i metodi start_tag() e do_tag() vengono definiti per uno stesso tag, il metodo start_tag() ha la precedenza.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

13.2 sgmllib -- Simple SGML parser

13.2 `sgmllib` -- Simple SGML parser