5.20.2 shlex オブジェクト

shlex インスタンスは以下のメソッドを持っています:

get_token( ): トークンを一つ返します。トークンが push_token() で使ってスタックに積まれていた場合、トークンをスタックからポップします。そうでない場合、トークンを一つ入力ストリームから読み出します。読み出し即時にファイル終了子に遭遇した場合、self.eof (非 POSIX モードでは空文字列 ('')、POSIX モードでは None) が返されます。

push_token( str): トークンスタックに引数文字列をスタックします。

read_token( ): 生 (raw) のトークンを読み出します。プッシュバックスタックを無視し、かつソースリクエストを解釈しません (通常これは便利なエントリポイントではありません。完全性のためにここで記述されています)。

sourcehook( filename)

shlex がソースリクエスト (下の source を参照してください) を検出した際、このメソッドはその後に続くトークンを引数として渡され、ファイル名と開かれたファイル類似オブジェクトからなるタプルを返すとされています。

通常、このメソッドはまず引数から何らかのクオートを剥ぎ取ります。処理後の引数が絶対パス名であった場合か、以前に有効になったソースリクエストが存在しない場合か、以前のソースが (sys.stdin のような) ストリームであった場合、この結果はそのままにされます。そうでない場合で、処理後の引数が相対パス名の場合、ソースインクルードスタックにある直前のファイル名からディレクトリ部分が取り出され、相対パスの前の部分に追加されます (この動作は C 言語プリプロセッサにおける #include "file.h" の扱いと同様です) 。

これらの操作の結果はファイル名として扱われ、タプルの最初の要素として返されます。同時にこのファイル名で open() を呼び出した結果が二つ目の要素になります (注意: インスタンス初期化のときとは引数の並びが逆になっています！)

このフックはディレクトリサーチパスや、ファイル拡張子の追加、その他の名前空間に関するハックを実装できるようにするために公開されています。 `close' フックに対応するものはありませんが、shlex インスタンスはソースリクエストされている入力ストリームが EOF を返した時には close() を呼び出します。

ソーススタックをより明示的に操作するには、push_source() および pop_source() メソッドを使ってください。

push_source( stream[, filename]): 入力ソースストリームを入力スタックにプッシュします。ファイル名引数が指定された場合、以後のエラーメッセージ中で利用することができます。sourcehook メソッドが内部で使用しているのと同じメソッドです。バージョン 2.1 で新たに追加された仕様です。

pop_source( ): 最後にプッシュされた入力ソースを入力スタックからポップします。字句解析器がスタック上の入力ストリームの EOF に到達した際に利用するメソッドと同じです。バージョン 2.1 で新たに追加された仕様です。

error_leader( [file[, line]]): このメソッドはエラーメッセージの論述部分を Unix C コンパイラエラーラベルの形式で生成します; この書式は '"%s", line %d: ' で、"%s" は現在のソースファイル名で置き換えられ、"%d" は現在の入力行番号で置き換えられます (オプションの引数を使ってこれらを上書きすることもできます)。
このやり方は、shlex のユーザに対して、Emacs やその他の Unix ツール群が解釈できる一般的な書式でのメッセージを生成することを推奨するために提供されています。

shlex サブクラスのインスタンスは、字句解析を制御したり、デバッグに使えるような public なインスタンス変数を持っています:

commenters: コメントの開始として認識される文字列です。コメントの開始から行末までのすべてのキャラクタ文字は無視されます。標準では単に "#" が入っています。

wordchars: 複数文字からなるトークンを構成するためにバッファに蓄積していくような文字からなる文字列です。標準では、全ての ASCII 英数字およびアンダースコアが入っています。

whitespace: 空白と見なされ、読み飛ばされる文字群です。空白はトークンの境界を作ります。標準では、スペース、タブ、改行 (linefeed) および復帰 (carriage-return) が入っています。

escape: エスケープ文字と見なされる文字群です。これは POSIX モードでのみ使われ、デフォルトでは "\" だけが入っています。バージョン 2.3 で新たに追加された仕様です。

quotes: 文字列引用符と見なされる文字群です。トークンを構成する際、同じクオートが再び出現するまで文字をバッファに蓄積します (すなわち、異なるクオート形式はシェル中で互いに保護し合う関係にあります)。標準では、ASCII 単引用符および二重引用符が入っています。

escapedquotes: quotes のうち、escape で定義されたエスケープ文字を解釈する文字群です。これは POSIX モードでのみ使われ、デフォルトでは """ だけが入っています。バージョン 2.3 で新たに追加された仕様です。

whitespace_split: この値が True であれば、トークンは空白文字でのみで分割されます。たとえば shlex がシェル引数と同じ方法で、コマンドラインを解析するのに便利です。バージョン 2.3 で新たに追加された仕様です。

infile: 現在の入力ファイル名です。クラスのインスタンス化時に初期設定されるか、その後のソースリクエストでスタックされます。エラーメッセージを構成する際にこの値を調べると便利なことがあります。

instream: shlex インスタンスが文字を読み出している入力ストリームです。

source: このメンバ変数は標準で None を取ります。この値に文字列を代入すると、その文字列は多くのシェルにおける "source" キーワードに似た、字句解析レベルでのインクルード要求として認識されます。すなわち、その直後に現れるトークンをファイル名として新たなストリームを開き、そのストリームを入力として、EOF に到達するまで読み込まれます。新たなストリームの EOF に到達した時点で close() が呼び出され、入力は元の入力ストリームに戻されます。ソースリクエストは任意のレベルの深さまでスタックしてかまいません。

debug: このメンバ変数が数値で、かつ1 またはそれ以上の値の場合、 shlex インスタンスは動作に関する冗長な進捗報告を出力します。この出力を使いたいなら、モジュールのソースコードを読めば詳細を学ぶことができます。

lineno: ソース行番号 (遭遇した改行の数に 1 を加えたもの) です。

token: トークンバッファです。例外を捕捉した際にこの値を調べると便利なことがあります。

eof: ファイルの終端を決定するのに使われるトークンです。非 POSIX モードでは空文字列 ('') 、POSIX モードでは None が入ります。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。