"textwrap" --- Text wrapping and filling
****************************************

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

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

"textwrap" モジュールは、実際の処理を行う  "TextWrapper" とともに、い
くつかの便利な関数を提供しています。1つか2つの文字列を wrap あるいは
fill するだけの場合は便利関数で十分ですが、多くの処理を行う場合は効率
のために "TextWrapper" のインスタンスを使うべきでしょう。

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

   *text* (文字列)内の段落を一つだけ折り返しを行います。したがって、す
   べての行が高々 *width* 文字の長さになります。最後に改行が付かない出
   力行のリストを返します。

   オプションのキーワード引数は、以下で説明する "TextWrapper" のインス
   タンス属性に対応しています。

   "wrap()" の動作についての詳細は "TextWrapper.wrap()" メソッドを参照
   してください。

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

   *text* 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含
   む一つの文字列を返します。 "fill()" はこれの省略表現です

      "\n".join(wrap(text, ...))

   特に、 "fill()" は "wrap()" とまったく同じ名前のキーワード引数を受
   け取ります。

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

   与えられた *text* を折りたたみ、切り詰めて、与えられた *width* に収
   まるようにします。

   最初に、*text* 内の空白が折りたたまれます (すべての空白を、1 文字の
   空白文字で置き換えます)。結果が *width* 内に収まった場合、その結果
   が返されます。width に収まらない場合、残りの文字数と  *placeholder*
   との和が  *width* 内に収まるように、末尾から単語が切り捨てられます:

      >>> textwrap.shorten("Hello  world!", width=12)
      'Hello world!'
      >>> textwrap.shorten("Hello  world!", width=11)
      'Hello [...]'
      >>> textwrap.shorten("Hello world", width=10, placeholder="...")
      'Hello...'

   オプションのキーワード引数は、以下で説明する "TextWrapper" インスタ
   ンスの属性に対応します。文字列が "TextWrapper" の "fill()" 関数に渡
   される前に、空白が折りたたまれます。そのため、"tabsize"、
   "expand_tabs"、"drop_whitespace"、"replace_whitespace" の値を変更し
   ても、意味がありません。

   Added in version 3.4.

textwrap.dedent(text)

   *text* の各行に対し、共通して現れる先頭の空白を削除します。

   この関数は通常、三重引用符で囲われた文字列をスクリーン/その他の左端
   にそろえ、なおかつソースコード中ではインデントされた形式を損なわな
   いようにするために使われます。

   タブとスペースはともにホワイトスペースとして扱われますが、同じでは
   ないことに注意してください:  ""  hello"" という行と ""\thello""  は
   、同じ先頭の空白文字をもっていないとみなされます。

   空白文字しか含まない行は入力の際に無視され、出力の際に単一の改行文
   字に正規化されます。

   例えば:

      def test():
          # end first line with \ to avoid the empty line!
          s = '''\
          hello
            world
          '''
          print(repr(s))          # prints '    hello\n      world\n    '
          print(repr(dedent(s)))  # prints 'hello\n  world\n'

textwrap.indent(text, prefix, predicate=None)

   *text* の中の選択された行の先頭に *prefix* を追加します。

   行の分割は "text.splitlines(True)" で行います。

   デフォルトでは、(改行文字を含む)空白文字だけの行を除いてすべての行
   に *prefix* を追加します。

   例えば:

      >>> s = 'hello\n\n \nworld'
      >>> indent(s, '  ')
      '  hello\n\n \n  world'

   省略可能な *predicate* 引数を使って、どの行をインデントするかを制御
   することができます。例えば、空行や空白文字のみの行にも *prefix* を
   追加するのは簡単です:

      >>> print(indent(s, '+ ', lambda line: True))
      + hello
      +
      +
      + world

   Added in version 3.3.

"wrap()"、"fill()"、"shorten()" は "TextWrapper" インスタンスを作成し
、その一つのメソッドを呼び出すことで機能します。そのインスタンスは再利
用されません。したがって、"wrap()" や "fill()" を使用して多くのテキス
ト文字列を処理するアプリケーションについては、独自の "TextWrapper" オ
ブジェクトを作成する方が効率が良い方法でしょう。

テキストはなるべく空白か、ハイフンを含む語のハイフンの直後で折り返され
ます。 "TextWrapper.break_long_words" が偽に設定されていなければ、必要
な場合に長い語が分解されます。

class textwrap.TextWrapper(**kwargs)

   "TextWrapper" コンストラクタはたくさんのオプションのキーワード引数
   を受け取ります。それぞれのキーワード引数は一つのインスタンス属性に
   対応します。したがって、例えば

      wrapper = TextWrapper(initial_indent="* ")

   はこれと同じです

      wrapper = TextWrapper()
      wrapper.initial_indent = "* "

   You can reuse the same "TextWrapper" object many times, and you can
   change any of its options through direct assignment to instance
   attributes between uses.

   "TextWrapper" インスタンス属性(とコンストラクタのキーワード引数)は
   以下の通りです:

   width

      (デフォルト: "70") 折り返しが行われる行の最大の長さ。入力行に
      "width" より長い単一の語が無い限り、 "TextWrapper" は "width" 文
      字より長い出力行が無いことを保証します。

   expand_tabs

      (デフォルト: "True") もし真ならば、そのときは *text* 内のすべて
      のタブ文字は *text* の "expandtabs()" メソッドを用いて空白に展開
      されます。

   tabsize

      (デフォルト: "8") "expand_tabs" が真の場合、 *text* の中のすべて
      のTAB文字は tabsize と現在のカラムに応じて、ゼロ以上のスペースに
      展開されます。

      Added in version 3.3.

   replace_whitespace

      (デフォルト: "True") 真の場合、 "wrap()" メソッドはタブの展開の
      後、 wrap 処理の前に各種空白文字をスペース1文字に置換します。置
      換される空白文字は: TAB, 改行, 垂直TAB, FF, CR ("'\t\n\v\f\r'")
      です。

      注釈:

        "expand_tabs" が偽で "replace_whitespace" が真ならば、各タブ文
        字は1つの空白に置き換えられます。それはタブ展開と同じでは *あ
        りません* 。

      注釈:

        "replace_whitespace" が偽の場合、改行が行の途中で現れることで
        出力がおかしくなることがあります。このため、テキストを
        ("str.splitlines()" などを使って)段落ごとに分けて別々に wrap
        する必要があります。

   drop_whitespace

      (デフォルト: "True") 真の場合、(wrap 処理のあとインデント処理の
      前に) 各行の最初と最後の空白文字を削除します。ただし、段落の最初
      の空白については、次の文字が空白文字でない場合は削除されません。
      削除される空白文字が行全体に及ぶ場合は、行自体を削除します。

   initial_indent

      (default: "''")  wrap の出力の最初の行の先頭に付与する文字列。最
      初の行の長さに加算されます。空文字列の場合インデントされません。

   subsequent_indent

      (デフォルト: "''") 一行目以外の折り返しが行われる出力のすべての
      行の先頭に付けられる文字列。一行目以外の各行の折り返しまでの長さ
      にカウントされます。

   fix_sentence_endings

      (デフォルト: "False") もし真ならば、 "TextWrapper" は文の終わり
      を見つけようとし、確実に文がちょうど二つの空白で常に区切られてい
      るようにします。これは一般的に固定スペースフォントのテキストに対
      して望ましいです。しかし、文の検出アルゴリズムは完全ではありませ
      ん: 文の終わりには、後ろに空白がある "'.'", "'!'" または "'?'"
      の中の一つ、ことによると "'"'" あるいは ""'"" が付随する小文字が
      あると仮定しています。このアルゴリズムに伴う一つの問題は下記の
      "Dr."と

         [...] Dr. Frankenstein's monster [...]

      下記の"Spot."の間の差異を検出できないことです

         [...] See Spot. See Spot run [...]

      "fix_sentence_endings" はデフォルトで偽です。

      文検出アルゴリズムは"小文字"の定義のために "string.lowercase" に
      依存し、同一行の文を区切るためにピリオドの後に二つの空白を使う慣
      習に依存しているため、英文テキストに限定されたものです。

   break_long_words

      (デフォルト: "True") もし真ならば、そのとき "width" より長い行が
      確実にないようにするために、 "width" より長い語は切られます。偽
      ならば、長い語は切られないでしょう。そして、 "width" より長い行
      があるかもしれません。 ("width" を超える分を最小にするために、長
      い語は単独で一行に置かれるでしょう。)

   break_on_hyphens

      (デフォルト: "True") 真の場合、英語で一般的なように、ラップ処理
      は空白か合成語に含まれるハイフンの直後で行われます。偽の場合、空
      白だけが改行に適した位置として判断されます。ただし、本当に語の途
      中で改行が行われないようにするためには、 "break_long_words" 属性
      を真に設定する必要があります。過去のバージョンでのデフォルトの振
      る舞いは、常にハイフンの直後での改行を許していました。

   max_lines

      (デフォルト "None") "None" 以外の場合、出力は行数 *max_lines* を
      超えないようにされ、切り詰める際には出力の最後の行を
      *placeholder* に置き換えます。

      Added in version 3.4.

   placeholder

      (デフォルト: "' [...]'") 切り詰める場合に出力の最後の行に置く文
      字列です。

      Added in version 3.4.

   "TextWrapper" はモジュールレベルの簡易関数に類似したいくつかの公開
   メソッドも提供します:

   wrap(text)

      1段落の文字列 *text* を、各行が "width" 文字以下になるように
      wrap します。 wrap のすべてのオプションは "TextWrapper" インスタ
      ンスの属性から取得します。結果の、行末に改行のない行のリストを返
      します。出力の内容が空になる場合は、返すリストも空になります。

   fill(text)

      *text* 内の段落を一つだけ折り返しを行い、折り返しが行われた段落
      を含む一つの文字列を返します。
