12.68 text.fill - テキストの再詰め込み

Module: text.fill ¶

このモジュールは、指定の幅にテキストを詰め込む(フィル)ように改行を適宜挿入して表示します。 Emacsのfill-paragraphのような機能です。

Function: display-filled-text text :key port indent hanging width start-column lead-in ¶

{text.fill} textを、行の幅がなるべくwidthに収まるように改行を挿入しながら portに出力します。 portが省略された場合は現在の出力ポートが使われます。

2つの連続する改行文字(あるいは、ひとつの空行)はパラグラフ境界を示します。 まずtextがパラグラフに分割され、それから各パラグラフがフィルされます。 他の改行文字は空白と同じ扱いになります。

いくつかのキーワード引数で出力フォーマットを制御できます。 width引数はフィルされたテキスト全体の幅を指定します。テキストはこの幅を 越えないように出力されます。 但し、分割できない長い塊があった場合はこの幅を越えることがあります。 hangingはパラグラフの最初の行のハンギングインデントを、indentは2行目以降の インデントを指定します。これらのインデントはwidthの一部にカウントされます。 次にこれらの値の関係を示します:

  width
<------------------------------------------------------------------->
  hanging
<------>
         Lorem ipsum dolor sit amet, consectetur adipiscing elit,
   sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
   nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
   in reprehenderit in voluptate velit esse cillum dolore eu fugiat
   nulla pariatur. Excepteur sint occaecat cupidatat non proident,
   sunt in culpa qui officia deserunt mollit anim id est laborum.
<->
  indent

width、indent、hangingは与えられたなら 正確な非負整数でなければなりません。省略されるか#fの場合、 widthは65、indentは0、hangingはindentと同じになります。

この手続きを、行の途中 (既にportにいくらか出力されてから改行されていない状態) で呼び出した場合、この手続きはportの現在のカラム位置を考慮に入れるので 次のようになります。

  width
<--------------------------------------------------------------------->
             start column
                |   hanging
                v<---->
                        Lorem ipsum dolor sit amet, consectetur
          adipiscing elit, sed do eiusmod tempor incididunt ut labore
          et dolore magna aliqua.  Ut enim ad minim veniam, quis
          nostrud exercitation ullamco laboris nisi ut aliquip ex ea
          commodo consequat. Duis aute irure dolor in reprehenderit in
          voluptate velit esse cillum dolore eu fugiat nulla pariatur.
          Excepteur sint occaecat cupidatat non proident, sunt in culpa
          qui officia deserunt mollit anim id est laborum.
<-------->
   indent

start-column引数は開始カラム位置を強制的に指定するものです。 与える場合は正確な非負整数でなければなりません。 この機能は最初のパラグラフのみに適用されます。 二番目以降のパラグラフはstart-columnが0であるかのようにフォーマットされます。

最後のパラグラフの最後の行の後に改行文字は出力されません。 呼び出し側がこの行の後にさらに続けて出力することもできるようにするためです。

行の長さは、East Asian Widthを使って計算されます (東アジア文字幅プロパティ参照)。実際に表示される行幅は フォントの設定に影響されますが、それなりの出力は得られます。

最後に、lead-in引数が与えられて#fでなければ、 それは文字列でなければならず、textやインデントの前に出力されます。 そして、もしlead-in出力後のカラムがhanging-1カラムより少なければ、 textは同じ行に出力されます:

     hanging
<------------------>
THIS IS LEAD-IN.    Lorem ipsum dolor sit amet, consectetur
             adipiscing elit, sed do eiusmod tempor incididunt ut labore
             et dolore magna aliqua.
<----------->
    indent

lead-inの幅がhanging以上であれば、textは次の行から 出力されます。

     hanging
<------------------>
THIS IS LEAD-IN LONGER THAN HANGING.
                    Lorem ipsum dolor sit amet, consectetur
             adipiscing elit, sed do eiusmod tempor incididunt ut labore
             et dolore magna aliqua.
<----------->
    indent

textが複数パラグラフからなる場合でも、lead-inは最初に一度だけ 出力されます。

This is handy when you display definition-list like document, e.g. command-line option description. これは定義リスト的なドキュメントを表示する時に便利です。 例えばコマンドラインオプションのヘルプ等。

Function: text->filled-stree text :key indent hanging width start-column lead-in ¶

{text.fill} これはdisplay-filled-textに呼ばれる低レベルルーチンで、 文字列のツリーを返します(text.tree - 怠惰なテキスト構築参照)。 パラグラフをフィルした後で他のテキストをその周囲に付け足したい場合などに、 中間文字列を作らずに済みます。

キーワード引数の意味はdisplay-filled-textと同じです。 但しstart-columnが省略された場合は0とみなされます。