12.1.1 L'interfaccia formatter

Le interfacce per creare i formattatori dipendono dalla specifica classe di formattatori che sta per essere istanziata. Le interfacce descritte di seguito sono quelle che tutti i formattatori devono supportare una volta inizializzati.

Un elemento dato è definito a livello di modulo:

AS_IS: Valore che può essere utilizzato nella specifica dei font passati al metodo push_font() descritto di seguito o come nuovo valore di ogni altro metodo push_property(). Eseguire un push del valore AS_IS permette al corrispondente metodo pop_property() di essere invocato senza dover rintracciare l'eventuale cambiamento della proprietà.

I seguenti attributi sono definiti per le istanze degli oggetti formatter:

writer: Istanza che scrive, con la quale iteragisce il formattatore.

end_paragraph( blanklines): Chiude ogni paragrafo aperto ed inserisce almeno una blanklines (NdT: riga vuota) prima del prossimo paragrafo.

add_line_break( ): Aggiunge un'interruzione di riga se non ne esiste ancora una. Questo non interrompe il paragrafo logico.

add_hor_rule( *args, **kw): Inserisce un separatore orizzontale (NdT: horizontal rule). Un separatore viene inserito se ci sono dei dati nel paragrafo corrente, ma non viene interrotto il paragrafo logico. Gli argomenti e le chiavi vengono passate al metodo send_line_break() dello scrittore.

add_flowing_data( data): Fornisce data, che deve essere formattato collassando i caratteri di spaziatura. I caratteri di spaziatura delle chiamate precedenti e successive a add_flowing_data() vengono considerati come se il collassamento sia stato effettuato. Si suppone che i dati passati a questo metodo siano divisi in base alle parole dal dispositivo di output. Notare che ogni divisione sulle parole deve ancora essere effettuata dall'oggetto scrittore, questo perché si deve fare affidamento sulle informazioni su dispositivi e font.

add_literal_data( data): Fornisce data, che deve essere passato allo scrittore senza alterazioni. I caratteri di spaziatura, incluso i caratteri di fine riga e tabulazione, vengono considerati legali per il valore di data.

add_label_data( format, counter): Inserisce un'etichetta che deve essere posizionata a sinistra del margine corrente. Questo può essere utilizzato per costruire liste o liste numerate. Se il valore di format è una stringa, viene interpretato come il formato specifico per counter, che deve essere un intero. Il risultato di questa formattazione diventa il valore dell'etichetta; se format non è una stringa, viene utilizzato direttamente come valore dell'etichetta. Il valore dell'etichetta viene passata come unico argomento del metodo send_label_data() dello scrittore. L'interpretazione di etichette con valore non corrispondente a stringhe dipende dallo scrittore associato.
Le specifiche di formattazione sono stringhe che, in combinazione con un contatore counter dei valori, vengono utilizzate per elaborare il valore dell'etichetta. Ogni carattere nella stringa di formattazione viene copiato nel valore dell'etichetta, con qualche carattere riconosciuto per indicare una trasformazione sul valore di counter. In modo specifico, il carattere "1" rappresenta il valore del contatore come numero arabo, i caratteri "A" e "a" corrispondono alla rappresentazione alfabetica del valore del contatore in maiuscolo o miniscolo, rispettivamente, e "I" ed "i" rappresentano il valore del contatore in numeri romani, in maiuscolo o miniscolo. Notare che le trasformazioni alfabetiche e romane richiedono che il valore del contatore siano maggiori di zero.

flush_softspace( ): Invia ogni carattere di spaziatura in sospeso bufferizzato da una precedente chiamata a add_flowing_data() all'oggetto scrittore associato. Questo deve essere chiamato prima di ogni manipolazione diretta dell'oggetto scrittore.

push_alignment( align): Esegue una push (NdT. inserimento) di una nuova impostazione di allineamento nello stack degli allineamenti. Questo può essere AS_IS se non si desidera nessun cambiamento. Se il valore dell'allineamento viene modificato dalla precedente impostazione, il metodo new_alignment() dello scrittore viene chiamato con il valore di align.

pop_alignment( ): Ripristina l'allineamento precedente.

push_font( (size, italic, bold, teletype)): Cambia alcune o tutte le proprietà dei font di un oggetto scrittore. Le proprietà che non sono impostate ad AS_IS vengono impostate al valore passato, mentre le altre vengono mantenute alle impostazioni attuali. Il metodo new_font() dello scrittore viene chiamato con la specifica del font completamente risolta.

pop_font( ): Ripristina i font precedenti.

push_margin( margin): Incrementa il numero di indentazione del margine sinistro di uno, associando il tag del margine logico, margin, alla nuova indentazione. Il livello iniziale del margine è 0. I cambiamenti del valore del tag logico devono essere dei valori veri; valori falsi diversi da AS_IS non sono sufficienti per cambiare il margine.

pop_margin( ): Ripristina il precedente margine.

push_style( *styles): Esegue una push di qualunque numero di specifiche arbitrarie di stili. Tutti gli stili vengono inseriti nello stack in ordine. Una tupla rappresentante l'intero stack, incluso il valore AS_IS, viene passata al metodo new_styles() dello scrittore.

pop_style( [n = 1]): Estrae l'ultima n-esima specificazione di stile passata a push_style(). Una tupla rappresentante lo stack rivisto, incluso il valore AS_IS, viene passata al metodo new_styles() dello scrittore.

set_spacing( spacing): Imposta lo stile di spaziatura per lo scrittore.

assert_line_data( [flag = 1]): Informa il formatter che i dati sono stati aggiunti al paragrafo corrente fuori banda. Questo deve essere utilizzato quando lo scrittore è stato manipolato direttamente. L'argomento facoltativo flag può essere impostato a falso se la manipolazione dello scrittore produce un'interruzione di riga alla fine dell'output.

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