5.21.1 Oggetti shlex

Un'istanza di shlex possiede i seguenti metodi:

get_token( ): Restituisce un token. Se i token sono stati inseriti nello stack usando push_token(), questo metodo estrae l'ultimo elemento inserito nello stack. Altrimenti lo legge dal flusso dell'input. Se in fase di lettura viene incontrato un carattere di fine file, restituisce self.eof (una stringa vuota ('') in modalità non POSIX, e None in modalità POSIX).

push_token( str): Inserisce l'argomento in cima allo stack.

read_token( ): Legge un token indipendentemente dalla sua posizione nello stack e non interpreta le richieste della sorgente. (Questo metodo di solito non è molto utile, viene qui documentato solo per ragioni di completezza).

sourcehook( filename)

Quando shlex rileva una richiesta da una sorgente (vedete source sotto), questo metodo viene richiamato con il token successivo come argomento, e restituisce una tupla consistente di un nome di file ed un oggetto simile a file aperto.

Normalmente, questo metodo toglie subito tutte le virgolette dall'argomento. Se il risultato è un percorso assoluto, o non c'è stata una precedente richiesta di una sorgente, o la sorgente precedente era un flusso (ad esempio sys.stdin), il risultato rimane inalterato. Altrimenti, se il risultato è un percorso relativo, viene prefissato con la parte che si riferisce alla directory nel nome del file che si trova immediatamente prima nello stack di inclusione della sorgente (questo comportamento è simile a quello del preprocessore C quando deve gestire #include "file.h").

Il risultato delle varie manipolazioni viene trattato come un nome di file e restituito come primo componente della tupla, con open() chiamato su di esso per ottenere il secondo componente (Notate: questo è l'inverso dell'ordine degli argomenti nell'inizializzazione dell'istanza!).

Questo aggancio è stato presentato in modo che possiate usarlo per implementare percorsi di ricerca nelle directory, aggiungere estensioni di file ed altre manipolazioni sul namespace. Non c'è un corrispondente aggancio `close', ma un'istanza di shlex richiamerà il metodo close() del flusso in input sorgente quando esso restituirà EOF.

Per avere un controllo più esplicito dello stack delle sorgenti, usate i metodi push_source() e pop_source().

push_source( stream[, filename]): Inserisce un flusso sorgente di input in cima allo stack dell'input. Se viene specificato l'argomento filename, esso verrà utilizzato per i messaggi di errore. Questo è lo stesso metodo usato internamente dal metodo sourcehook. Nuovo nella versione 2.1.

pop_source( ): Estrae la sorgente di input dalla cima dello stack di input. Questo è lo stesso metodo usato internamente dall'analizzatore quando incontra un EOF su un flusso di input nello stack. Nuovo nella versione 2.1.

error_leader( [file[, line]]): Questo metodo genera un messaggio di errore nel formato del compilatore C Unix; il formato è '"%s", line %d: ', dove "%s" viene rimpiazzato dal nome del file sorgente corrente e "%d" con il numero della riga di input corrente (gli argomenti facoltativi possono essere utilizzati per sovrascrivere questo comportamento predefinito).
Questa utilità viene fornita allo scopo di incoraggiare gli utenti di shlex a generare messaggi di errore nel formato standard riconosciuto da Emacs e da altri strumenti Unix.

Le istanze delle sotto classi di shlex possiedono alcune variabili d'istanza pubbliche che permettono di controllare l'analisi lessicale oppure utilizzabili per il debugging:

commenters: La stringa dei caratteri che vengono considerati come inizio di commento. Tutti i caratteri da quello iniziale alla fine della riga vengono ignorati. Il predefinito è solamente il carattere "#".

wordchars: La stringa dei caratteri che verranno accumulati nei token multi-carattere. Di predefinito include tutti i caratteri ASCII alfanumerici ed il trattino basso.

whitespace: I caratteri che verranno considerati spazi vuoti e quindi saltati. Gli spazi vuoti delimitano i token. Di predefinito vengono inclusi lo spazio vuoto, la tabulazione, il codice di controllo dell'avanzamento di riga e quello di ritorno carrello.

escape: I caratteri che verranno considerati caratteri di protezione. Questi potranno essere usati solamente in modalità POSIX, ed di predefinito viene incluso solo "\". Nuovo nella versione 2.3.

quotes: Caratteri che verranno considerati come quotatori di stringa. Il token si accumula finché non viene incontrato il medesimo carattere di quotatura (quindi, caratteri differenti di quotatura si proteggono tra loro come nella shell). Di predefinito, include i caratteri di virgolette ASCIIsingole e doppie.

escapedquotes: I caratteri in quotes che interpreteranno i caratteri di protezione definiti in escape. Questo viene utilizzato solamente in modalità POSIXPOSIX e di predefinito include solamente """. Nuovo nella versione 2.3.

whitespace_split: Se True, i token verranno suddivisi solamente quando incontrano spazi vuoti. Questo è utile, per esempio, per esaminare le righe di comando con shlex, ottenendo i token in modo simile agli argomenti passati alla shell. Nuovo nella versione 2.3.

infile: Il nome del file di input corrente, come inizialmente impostato nel momento di istanziazione della classe o inserito nello stack da richieste successive. Può essere utile controllarlo quando si costruiscono messaggi di errore.

instream: Il flusso di input da cui questa istanza shlex sta leggendo i caratteri.

source: Il valore predefinito per questo membro è None. Se viene assegnata ad esso una stringa, quella stringa verrà riconosciuta come una richiesta di inclusione a livello lessicale allo stesso modo della parola chiave "source" in varie shell. Quindi, il token che segue immediatamente verrà aperto come un nome di file e l'input catturato da quel flusso fino ad EOF, momento in cui il metodo close() di quel flusso verrà chiamato ed la sorgente di input diventerà nuovamente il flusso originario di input. Richieste di sorgente possono essere accumulate a qualunque numero di livelli di profondità.

debug: Se questo membro è numerico e vale 1 o più, un'istanza shlex stamperà in modo prolisso e progressivo l'output riguardo al suo andamento. Se c'è la necessità di utilizzarlo, potete trovare i dettagli leggendo il codice sorgente del modulo.

lineno: Numero di riga della sorgente (conteggio dei caratteri di fine riga trovati finora più uno).

token: Il token buffer. Può essere utile esaminarlo quando si catturano le eccezioni.

eof: Il token usato per determinare la fine del file. Verrà impostato alla stringa vuota (''), in modalità non POSIX, e None in modalità POSIX. Nuovo nella versione 2.3.

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