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

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

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

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

The "shlex" module defines the following functions:

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

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

   バージョン 3.12 で変更: Passing "None" for *s* argument now raises
   an exception, rather than reading "sys.stdin".

shlex.join(split_command)

   Concatenate the tokens of the list *split_command* and return a
   string. This function is the inverse of "split()".

   >>> from shlex import join
   >>> print(join(['echo', '-n', 'Multiple words']))
   echo -n 'Multiple words'

   The returned value is shell-escaped to protect against injection
   vulnerabilities (see "quote()").

   Added in version 3.8.

shlex.quote(s)

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

   警告:

     The "shlex" module is **only designed for Unix shells**.The
     "quote()" function is not guaranteed to be correct on non-POSIX
     compliant shells or shells from other operating systems such as
     Windows. Executing commands quoted by this module on such shells
     can open up the possibility of a command injection
     vulnerability.Consider using functions that pass command
     arguments with lists such as "subprocess.run()" with
     "shell=False".

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

   >>> 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 ~']

   Added in version 3.3.

The "shlex" module defines the following class:

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" は現在の入力行番号で
   置き換えられます (オプションの引数を使ってこれらを上書きすることも
   できます)。

   This convenience is provided to encourage "shlex" users to generate
   error messages in the standard, parseable format understood by
   Emacs and other Unix tools.

"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. If
   "whitespace_split" is set to "True", this will have no effect.

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.  When used in
   combination with "punctuation_chars", tokens will be split on
   whitespace in addition to those characters.

   バージョン 3.8 で変更: The "punctuation_chars" attribute was made
   compatible with the "whitespace_split" attribute.

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.

   Added in version 3.6.


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

When operating in non-POSIX mode, "shlex" will try to obey the
following rules.

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

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

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

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

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

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

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

When operating in POSIX mode, "shlex" will try to obey the following
parsing rules.

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

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

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

* Enclosing characters in quotes which are part of "escapedquotes"
  (e.g. "'"'") preserves the literal value of all characters within
  the quotes, with the exception of the characters mentioned in
  "escape".  The escape characters retain their special meaning only
  when followed by the quote in use, or the escape character itself.
  Otherwise the escape character will be considered a normal
  character.

* "None" で EOF を送出する

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


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

Added in version 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\")"
   >>> s = shlex.shlex(text, posix=True)
   >>> s.whitespace_split = True
   >>> list(s)
   ['a', '&&', 'b;', 'c', '&&', 'd', '||', 'e;', 'f', '>abc;', '(def', 'ghi)']
   >>> s = shlex.shlex(text, posix=True, punctuation_chars=True)
   >>> s.whitespace_split = True
   >>> list(s)
   ['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?']

  However, to match the shell as closely as possible, it is
  recommended to always use "posix" and "whitespace_split" when using
  "punctuation_chars", which will negate "wordchars" entirely.

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