5.20.1 Oggetti Cmd

Un'istanza di Cmd possiede i seguenti metodi:

cmdloop( [intro])

Mostra ripetutamente un prompt, accetta l'input, analizza la parte iniziale dell'input ricevuto e richiama i metodi d'azione, passando loro il resto della riga come argomento.

L'argomento facoltativo è un titolo o una stringa di introduzione che viene mostrata prima del primo prompt (questo sovrascrive il membro di classe intro).

Se viene caricato il modulo readline, l'input erediterà automaticamente la gestione dello storico tipica delle shell simili alla bash (per es.: Control-P mostra il comando precedente, Control-N quello successivo, Control-F muove il cursore a destra in maniera non distruttiva, Control-B muove il cursore a sinistra in maniera non ditruttiva, etc.).

In fondo all'input viene inserita la fine del file tramite la stringa 'EOF'.

Un'istanza dell'interprete individuerà un comando di nome "foo"se e solo se possiede un metodo di nome do_foo(). Come caso speciale, viene inviata al metodo do_help() una riga che inizia con il carattere "?". Come altro caso speciale, viene inviato al metodo do_shell()(sempre che sia stato definito) una riga che inizia con il carattere "!".

Se il completamento è abilitato, verrà eseguito automaticamente il completamento dei comandi, e in particolare avverrà chiamando la funzione complete_foo() con gli argomenti text, line, begidx ed endidx. text è il prefisso della stringa che stiamo cercando di completare: tutte le corrispondenze devono iniziare con text. line è la riga di input corrente senza lo spazio bianco iniziale, mentre begidx ed endidx sono gli indici iniziale e finale del testo prefissato, che possono essere usati per ottenere diversi tipi di completamento in base alla posizione occupata dal testo all'interno della stringa che si vuole ottenere.

Tutte le sotto classi di Cmd ereditano un metodo predefinito do_help(). Questo, chiamato con un argomento 'bar', invoca il corrispondente metodo help_bar(). Senza argomenti, do_help() elenca tutte le possibili richieste di aiuto (cioè, tutti i comandi con il metodo help_*() corrispondente), oltre a tutti i comandi non documentati.

onecmd( str): Interpreta l'argomento come se fosse stato digitato in risposta al prompt. Può essere sovrascritto, ma normalmente non dovrebbe essere necessario; si considerino in proposito i metodi precmd() e postcmd() per delle tipologie utili di esecuzione. Il valore restituito è un'opzione che indica se l'interpretazione dei comandi si debba o meno fermare.

emptyline( ): Questo metodo viene chiamato quando viene passata una riga vuota in risposta al prompt. Se questo metodo non viene sovrascritto, ripete l'ultimo comando non vuoto appena inserito.

default( line): Questo metodo viene chiamato quando il comando su una riga di input non viene riconosciuto. Se questo metodo non viene sovrascritto, stampa un messaggio di errore ed esce.

completedefault( text, line, begidx, endidx): Questo metodo viene chiamato per completare una riga di input quando non esiste un metodo complete_*() specifico. Di predefinito restituisce una lista vuota.

precmd( line): Questo metodo di aggancio viene eseguito appena prima di interpretare la riga line, ma subito dopo che il prompt è stato generato ed emesso. In Cmd è un metodo inattivo; esiste per essere sovrascritto dalle sotto classi. Il valore restituito viene usato come comando da inviare al metodo onecmd(); l'implementazione di precmd() può riscrivere il comando o semplicemente restituire la riga line senza cambiamenti.

postcmd( stop, line): Questo metodo di aggancio viene eseguito subito dopo il termine dell'esecuzione di un comando. In Cmd è inattivo; esiste per essere sovrascritto dalle sotto classi. line è la riga di comando che è stata eseguita, e stop è un'opzione che indica se l'esecuzione debba terminare dopo la chiamata a postcmd(); questo sarà il valore restituito dal metodo onecmd(). Il valore restituito da questo metodo verrà usato come nuovo valore dell'opzione interna corrispondente a stop; l'interpretazione andrà avanti nel caso venga restituito un valore false.

preloop( ): Questo metodo di aggancio viene eseguito una sola volta al momento della chiamata a cmdloop(). È un metodo inattivo in Cmd; esiste per essere sovrascritto dalle sotto classi.

postloop( ): Questo metodo di aggancio viene eseguito una sola volta quando cmdloop() sta per terminare. È un metodo inattivo in Cmd; esiste per essere sovrascritto dalle sotto classi.

Le istanze delle sotto classi di Cmd possiedono alcune variabili d'istanza pubbliche:

prompt: Il prompt mostrato per sollecitare l'input.

identchars: La stringa di caratteri valida come prefisso dei comandi.

lastcmd: L'ultimo comando non vuoto inserito.

intro: La stringa da mostrare come avviso o messaggio introduttivo. Può essere sovrascritta passando un argomento al metodo cmdloop().

doc_header: L'intestazione da mostrare se l'aiuto visualizzato possiede una sezione per i comandi documentati.

misc_header: L'intestazione da mostrare se l'aiuto visualizzato possiede una sezione per le voci relative a comandi particolari (cioè, esistono metodi help_*() senza i relativi metodi do_*()).

undoc_header: L'intestazione da mostrare se l'aiuto visualizzato possiede una sezione per i comandi non documentati (cioè, esistono metodi do_*() senza i corrispondenti metodi help_*()).

ruler: Il carattere usato per disegnare le linee separatrici sotto le intestazioni dei messaggi d'aiuto. Se vuoto, non viene disegnata nessuna linea. Il valore predefinito e il carattere "=".

use_rawinput: È un'opzione che ha come valore predefinito vero. Se è vera, cmdloop() utilizza raw_input() per mostrare il prompt e leggere il comando successivo; se invece è falsa, vengono utilizzati sys.stdout.write() e sys.stdin.readline(). (Ciò significa che importando readline, su sistemi che lo supportano, l'interprete riconoscerà automaticamente i comandi per la gestione dello storico e il modo di gestire il testo tipici di Emacs).

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