"shlex" --- 単純な字句解析
**************************

**ソースコード:** Lib/shlex.py

======================================================================

"shlex" クラスは Unix シェルに似た、単純な構文に対する字句解析器を簡単
に書けるようにします。このクラスはしばしば、 Python アプリケーションの
ための実行制御ファイルのような小規模言語を書く上で便利です。

"shlex" モジュールは以下の関数を定義しています:

shlex.split(s, comments=False, posix=True)

   シェルに似た文法を使って、文字列 *s* を分割します。 *comments* が
   "False" (デフォルト値) の場合、受理した文字列内のコメントを解析しま
   せん ("shlex" インスタンスの "commenters" メンバの値を空文字列にし
   ます)。この関数はデフォルトでは POSIX モードで動作し、 *posix* 引数
   が偽の場合は非 POSIX モードで動作します。

   注釈:

     "split()" 関数は "shlex" クラスのインスタンスを利用するので、 *s*
     に "None" を渡すと標準入力から分割する文字列を読み込みます。

shlex.quote(s)

   文字列 *s* をシェルエスケープして返します。戻り値は、リストを使えな
   いようなケースで、シェルコマンドライン内で一つのトークンとして安全
   に利用出来る文字列です。

   以下のイディオムは安全ではないかもしれません:

   >>> filename = 'somefile; rm -rf ~'
   >>> command = 'ls -l {}'.format(filename)
   >>> print(command)  # executed by a shell: boom!
   ls -l somefile; rm -rf ~

   "quote()" がそのセキュリティホールをふさぎます:

   >>> from shlex import quote
   >>> command = 'ls -l {}'.format(quote(filename))
   >>> print(command)
   ls -l 'somefile; rm -rf ~'
   >>> remote_command = 'ssh home {}'.format(quote(command))
   >>> print(remote_command)
   ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''

   クォーティングは UNIX シェルならびに "split()" と互換です:

   >>> from shlex import split
   >>> remote_command = split(remote_command)
   >>> remote_command
   ['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
   >>> command = split(remote_command[-1])
   >>> command
   ['ls', '-l', 'somefile; rm -rf ~']

   バージョン 3.3 で追加.

"shlex" モジュールは以下のクラスを定義します。

class shlex.shlex(instream=None, infile=None, posix=False, punctuation_chars=False)

   A "shlex" instance or subclass instance is a lexical analyzer
   object.  The initialization argument, if present, specifies where
   to read characters from.  It must be a file-/stream-like object
   with "read()" and "readline()" methods, or a string.  If no
   argument is given, input will be taken from "sys.stdin". The second
   optional argument is a filename string, which sets the initial
   value of the "infile" attribute.  If the *instream* argument is
   omitted or equal to "sys.stdin", this second argument defaults to
   "stdin".  The *posix* argument defines the operational mode: when
   *posix* is not true (default), the "shlex" instance will operate in
   compatibility mode.  When operating in POSIX mode, "shlex" will try
   to be as close as possible to the POSIX shell parsing rules.  The
   *punctuation_chars* argument provides a way to make the behaviour
   even closer to how real shells parse.  This can take a number of
   values: the default value, "False", preserves the behaviour seen
   under Python 3.5 and earlier.  If set to "True", then parsing of
   the characters "();<>|&" is changed: any run of these characters
   (considered punctuation characters) is returned as a single token.
   If set to a non-empty string of characters, those characters will
   be used as the punctuation characters.  Any characters in the
   "wordchars" attribute that appear in *punctuation_chars* will be
   removed from "wordchars".  See Improved Compatibility with Shells
   for more information. *punctuation_chars* can be set only upon
   "shlex" instance creation and can't be modified later.

   バージョン 3.6 で変更: *punctuation_chars* 引数が追加されました。

参考:

  "configparser" モジュール
     Windows ".ini" ファイルに似た設定ファイルのパーザ。


shlex オブジェクト
==================

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

shlex.get_token()

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

shlex.push_token(str)

   トークンスタックに引数文字列をスタックします。

shlex.read_token()

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

shlex.sourcehook(filename)

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

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

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

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

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

shlex.push_source(newstream, newfile=None)

   入力ソースストリームを入力スタックにプッシュします。ファイル名引数
   が指定された場合、以後のエラーメッセージ中で利用することができます
   。 "sourcehook()" メソッドが内部で使用しているのと同じメソッドです
   。

shlex.pop_source()

   最後にプッシュされた入力ソースを入力スタックからポップします。字句
   解析器がスタック上の入力ストリームの EOF に到達した際に利用するメソ
   ッドと同じです。

shlex.error_leader(infile=None, lineno=None)

   このメソッドはエラーメッセージの論述部分を Unix C コンパイラエラー
   ラベルの形式で生成します; この書式は "'"%s", line %d: '" で、 "%s"
   は現在のソースファイル名で置き換えられ、 "%d" は現在の入力行番号で
   置き換えられます (オプションの引数を使ってこれらを上書きすることも
   できます)。

   このやり方は、 "shlex" のユーザに対して、Emacs やその他の Unix ツー
   ル群が解釈できる一般的な書式でのメッセージを生成することを推奨する
   ために提供されています。

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

shlex.commenters

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

shlex.wordchars

   The string of characters that will accumulate into multi-character
   tokens.  By default, includes all ASCII alphanumerics and
   underscore.  In POSIX mode, the accented characters in the Latin-1
   set are also included.  If "punctuation_chars" is not empty, the
   characters "~-./*?=", which can appear in filename specifications
   and command line parameters, will also be included in this
   attribute, and any characters which appear in "punctuation_chars"
   will be removed from "wordchars" if they are present there.

shlex.whitespace

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

shlex.escape

   エスケープ文字と見なされる文字群です。これは POSIX モードでのみ使わ
   れ、デフォルトでは "'\'" だけが入っています。

shlex.quotes

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

shlex.escapedquotes

   "quotes" のうち、 "escape" で定義されたエスケープ文字を解釈する文字
   群です。これは POSIX モードでのみ使われ、デフォルトでは "'"'" だけ
   が入っています。

shlex.whitespace_split

   If "True", tokens will only be split in whitespaces.  This is
   useful, for example, for parsing command lines with "shlex",
   getting tokens in a similar way to shell arguments.  If this
   attribute is "True", "punctuation_chars" will have no effect, and
   splitting will happen only on whitespaces.  When using
   "punctuation_chars", which is intended to provide parsing closer to
   that implemented by shells, it is advisable to leave
   "whitespace_split" as "False" (the default value).

shlex.infile

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

shlex.instream

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

shlex.source

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

shlex.debug

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

shlex.lineno

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

shlex.token

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

shlex.eof

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

shlex.punctuation_chars

   A read-only property. Characters that will be considered
   punctuation. Runs of punctuation characters will be returned as a
   single token. However, note that no semantic validity checking will
   be performed: for example, '>>>' could be returned as a token, even
   though it may not be recognised as such by shells.

   バージョン 3.6 で追加.


解析規則
========

非 POSIX モードで動作中の "shlex" は以下の規則に従おうとします。

* ワード内の引用符を認識しない ("Do"Not"Separate" は単一ワード
  "Do"Not"Separate" として解析されます)

* エスケープ文字を認識しない

* 引用符で囲まれた文字列は、引用符内の全ての文字リテラルを保持する

* 閉じ引用符でワードを区切る (""Do"Separate" は、 ""Do"" と "Separate"
  であると解析されます)

* "whitespace_split" が "False" の場合、wordchar、 whitespace または
  quote として宣言されていない全ての文字を、単一の文字トークンとして返
  す。 "True" の場合、 "shlex" は空白文字でのみ単語を区切る。

* 空文字列 ("''") で EOF を送出する

* 引用符に囲んであっても、空文字列を解析しない

POSIX モードで動作中の "shlex" は以下の解析規則に従おうとします。

* 引用符を取り除き、引用符で単語を分解しない (""Do"Not"Separate"" は単
  一ワード "DoNotSeparate" として解析されます)

* 引用符で囲まれないエスケープ文字群 ("'\'" など) は直後に続く文字のリ
  テラル値を保持する

* "escapedquotes" でない引用符文字 (""'"" など) で囲まれている全ての文
  字のリテラル値を保持する

* 引用符に囲まれた "escapedquotes" に含まれる文字 ("'"'" など) は、
  "escape" に含まれる文字を除き、全ての文字のリテラル値を保持する。エ
  スケープ文字群は使用中の引用符、または、そのエスケープ文字自身が直後
  にある場合のみ、特殊な機能を保持する。他の場合にはエスケープ文字は普
  通の文字とみなされる。

* "None" で EOF を送出する

* 引用符に囲まれた空文字列 ("''") を許す。


Improved Compatibility with Shells
==================================

バージョン 3.6 で追加.

The "shlex" class provides compatibility with the parsing performed by
common Unix shells like "bash", "dash", and "sh".  To take advantage
of this compatibility, specify the "punctuation_chars" argument in the
constructor.  This defaults to "False", which preserves pre-3.6
behaviour. However, if it is set to "True", then parsing of the
characters "();<>|&" is changed: any run of these characters is
returned as a single token.  While this is short of a full parser for
shells (which would be out of scope for the standard library, given
the multiplicity of shells out there), it does allow you to perform
processing of command lines more easily than you could otherwise.  To
illustrate, you can see the difference in the following snippet:

    >>> import shlex
    >>> text = "a && b; c && d || e; f >'abc'; (def \"ghi\")"
    >>> list(shlex.shlex(text))
    ['a', '&', '&', 'b', ';', 'c', '&', '&', 'd', '|', '|', 'e', ';', 'f', '>',
    "'abc'", ';', '(', 'def', '"ghi"', ')']
    >>> list(shlex.shlex(text, punctuation_chars=True))
    ['a', '&&', 'b', ';', 'c', '&&', 'd', '||', 'e', ';', 'f', '>', "'abc'",
    ';', '(', 'def', '"ghi"', ')']

Of course, tokens will be returned which are not valid for shells, and
you'll need to implement your own error checks on the returned tokens.

Instead of passing "True" as the value for the punctuation_chars
parameter, you can pass a string with specific characters, which will
be used to determine which characters constitute punctuation. For
example:

   >>> import shlex
   >>> s = shlex.shlex("a && b || c", punctuation_chars="|")
   >>> list(s)
   ['a', '&', '&', 'b', '||', 'c']

注釈:

  When "punctuation_chars" is specified, the "wordchars" attribute is
  augmented with the characters "~-./*?=".  That is because these
  characters can appear in file names (including wildcards) and
  command-line arguments (e.g. "--color=auto"). Hence:

     >>> import shlex
     >>> s = shlex.shlex('~/a && b-c --color=auto || d *.py?',
     ...                 punctuation_chars=True)
     >>> list(s)
     ['~/a', '&&', 'b-c', '--color=auto', '||', 'd', '*.py?']

For best effect, "punctuation_chars" should be set in conjunction with
"posix=True". (Note that "posix=False" is the default for "shlex".)
