NAME

perlform - Perl のフォーマット

DESCRIPTION

Perl は、あなたが単純なレポートやチャートを作るのを助けてくれるような機構を持っています。これを容易にするために、Perl は出力するページを見栄えよくするためのプログラムの作成を助けてくれます。現在のページにおいて何行出力したとか、ページヘッダを出力するタイミングなどのことを保持しつづけることができます。キーワードは FORTRAN から借りました: format() が宣言のためのもので、 write() が実行のためのものです。 perlfunc 中のそれぞれのエントリを参照してください。幸運にも、そのレイアウトは非常に読みやすく、 BASIC の PRINT USING 文のようなものです。貧者のための nroff(1) と考えてください。

パッケージやサブルーチンと同様に、フォーマットも実行されるのではなく宣言されるものなので、プログラムの任意の場所に置くことができます。 (ただし、通常は全てまとめておくのが良いでしょう。) これらは、Perl の他のすべての「型」とは分離された名前空間を持っています。これはつまり、"Foo" という名前の関数を持っているとき、それは "Foo" と名前が付けられているフォーマットとは違うものなのだということです。しかしながら、与えられたファイルハンドルに結び付けられたフォーマットのデフォルトの名前は、そのファイルハンドルと同じ名前になります。したがって、STDOUT のデフォルトのフォーマットの名前は "STDOUT" であり、 TEMP というファイルハンドルに対するデフォルトフォーマットの名前は "TEMP" となります。これらは同じもののように見えます。そうではありません。

出力レコードフォーマットは以下のように宣言されます:

    format NAME =
    FORMLIST
    .

名前が省略された場合、フォーマット "STDOUT" が定義されます。 1 桁目に単一の "." を置くと、フォーマットを終了します。 FORMLIST は、それぞれが以下の 3 つのいずれかである行の並びから構成されます。

第 1 カラムに `#' が置かれることによって示されるコメント。
出力行のフォーマットを与える「ピクチャー」行。
直前のピクチャー行に値を押し込むための引数行。

ピクチャー行は、リテラルなテキストが混ざった出力フィールド定義を含みます。これらの行はどのような変数展開も行われません。フィールド定義は文字の集合で行われ、フィールドの開始と、希望する幅への拡張を行います。以下はフィールド定義のための文字の完全な集合です:

   @    start of regular field
   ^    start of special field
   <    pad character for left justification
   |    pad character for centering
   >    pad character for right justification
   #    pad character for a right-justified numeric field
   0    instead of first #: pad number with leading zeroes
   .    decimal point within a numeric field
   ...  terminate a text field, show "..." as truncation evidence
   @*   variable width field for a multi-line value
   ^*   variable width field for next line of a multi-line value
   ~    suppress line with all fields empty
   ~~   repeat line until all fields are exhausted

ピクチャー行の書くフィールドは "@" (at) か "^" (caret) で開始され、それぞれ「通常」か「特殊」フィールドを呼び出すことを示します。パッド文字の選択はフィールドがテキストか数値化によって決定されます。チルダ演算子はフィールドの一部ではありません。様々な可能性に冠する詳細について見ていきましょう。

テキストフィールド

フィールドの長さは、左寄せ、右寄せ、センタリングをそれぞれ指定する "<", ">", "|" といった文字で埋められた非数値フィールドで与えられます。通常のフィールドでは、値(最初の改行まで)が取られ、選択された行揃えと余分な文字の切り詰めに従って表示されます。テキストフィールドが "..." で終わっている場合、もし値が切り詰められると 3 つのドットが表示されます。特殊テキストフィールドは基本的に複数行テキストブロック詰め込みに使われます; 詳細については "Using Fill Mode" を参照してください。

   Example:
      format STDOUT =
      @<<<<<<   @||||||   @>>>>>>
      "left",   "middle", "right"
      .
   Output:
      left      middle    right

数値フィールド

パッディング文字として "#" を使うと、数値フィールドを右詰めすることを指定します。オプションの "." は小数点の位置を定義します。最初の "#" の代わりに "0" (zero) を使うと、フォーマットされた数値はもし必要であれば 0 でパッディングします。値が未定義の場合、特殊数値フィールドは空になります。もし結果の値がフィールドで指定された幅を超えた場合、オーバーフローしたことを示すために "#" で埋められます。

   Example:
      format STDOUT =
      @###   @.###   @##.###  @###   @###   ^####
       42,   3.1415,  undef,    0, 10000,   undef
      .
   Output:
        42   3.142     0.000     0   ####

可変長複数行テキストのための @* フィールド

フィールド "@*" は複数行で切り詰められない値を表示するために使われます; これはそれ自身 1 行で表示されるべきです(しかし必要ではありません)。最後の改行は切り落とされますが、その他の全ての文字はそのまま出力されます。

「1 回に 1 行」の可変長テキストのための ^* フィールド

"@*" と同様、これは可変長幅フィールドです。指定する値はスカラ値でなければなりません。 Perl はテキストの最初の行(最初の "\n" まで)をフィールドにいれ、それから次にこの変数が参照されたときに次のテキストが表示されるように、文字列の前の部分は切り落とされます。変数は復元 されません 。

   Example:
      $text = "line 1\nline 2\nline 3";
      format STDOUT =
      Text: ^*
            $text
      ~~    ^*
            $text
      .
   Output:
      Text: line 1
            line 2
            line 3

値の指定

引き続くフォーマット行で指定された値は、ピクチャーフィールドと同じ順序になります。値を提供する式はカンマで分けられていなければなりません。式は、行の処理が行われるより前にリストコンテキストで評価されます; ですから、一つのリスト式が複数行の要素を生成することもできます。この式はそれが中かっこで囲まれている場合には、2 行以上に広げられることもできます。その場合、開きかっこは一行目の最初のトークンでなければなりません。ある式が小数部を持った数値として評価され、数値指定に対応するピクチャーは出力に現れます(つまり、埋め込みの "." 以外の 複数の "#" を除く全てのピクチャーです); そして、小数点のために使われる文字は、 use locale が有効ならカレントの LC_NUMERIC ロケールによって決定されます。これはたとえば、実行時にドイツ語ロケールが指定されている環境の場合には、デフォルトの "." ではなく "," が使われるということです。詳しい情報は perllocale と "WARNINGS"" in " を参照してください。

詰め込みモードを使う

テキストフィールドでは、キャレットが詰め込みモードを有効にします。指定する値は任意の式ではなく、テキスト文字列を保持しているスカラ変数の名前でなくてはなりません。 Perl は次の位置のテキストをフィールドに出力してから文字列の先頭をたたき落とす(chop)ので、次にその変数を参照したときには残りの文字列を出力できるのです。 (これはつまり、その変数自身が write() の実行中に変更されてしまうということであり、元には戻らないということです。) テキストの次の位置は粗い行分割アルゴリズムによって決定されます。強制的に行分割を行うために復帰文字 (\r) が使えます。 $: という変数(English モジュールを使っていれば $FORMAT_LINE_BREAK_CHARACTERS)の内容を変更することによって、そこで改行することのできる文字を設定できます。

通常は、同じスカラ変数に結び付けられた縦方向に積み重ねられたフィールドの並びを使ってテキストのブロックを出力することができます。最後のフィールドの終端に "..." を置くと、それは出力対象のテキストが長すぎて全体を出力できないときに出力に付加されます。

全てのフィールドが空の行を抑制する

キャレットを使ったフィールドは、全てのフィールドが空白の行を生成することができます。行の任意の場所に "~"(チルダ) を置くことによって空行を抑制することができます。チルダは出力では空白に変換されます。

フォーマット行を繰り返す

行のどこかに 2 つの連続したチルダ文字 "~~" を置くと、その行はその行にある全てのフィールドが出力されるまで(つまり未定義になるまで)くり返されます。特殊(キャレット)テキストフィールドでは、これは遅かれ早かれ起こりますが、変化のあるテキストフィールドを使う場合、指定する式は同じ値を毎回永遠に返さないようにした方がよいでしょう! (これが起きる単純な例は shift(@f) です。) このような行に通常の数値フィールドを使ってはいけません; なぜなら決して空にならないからです。

ページ先頭の処理

ページの先頭の処理は、デフォルトではカレントのファイルハンドルに "_TOP" を付けた名前のフォーマットによって取り扱われます。これは、各ページの先頭で呼び出されます。 "write" in perlfunc を参照してください。

例:

 # a report on the /etc/passwd file
 format STDOUT_TOP =
                         Passwd File
 Name                Login    Office   Uid   Gid Home
 ------------------------------------------------------------------
 .
 format STDOUT =
 @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
 $name,              $login,  $office,$uid,$gid, $home
 .

 # a report from a bug report form
 format STDOUT_TOP =
                         Bug Reports
 @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
 $system,                      $%,         $date
 ------------------------------------------------------------------
 .
 format STDOUT =
 Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
          $subject
 Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
        $index,                       $description
 Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
           $priority,        $date,   $description
 From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
       $from,                         $description
 Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
              $programmer,            $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
                                      $description
 .

同じ出力チャネルにおいて print() と write() を混ぜて使うことは可能ですが、 $- ($FORMAT_LINES_LEFT) を自分で扱う必要があるでしょう。

フォーマット変数

カレントのフォーマット名は $~ ($FORMAT_NAME) という変数に格納され、カレントの先頭のフォーマットの名前は $^ ($FORMAT_TOP_NAME) に格納されています。カレントの出力ページ数は $% ($FORMAT_PAGE_NUMBER) にあり、ページ当たりの行数は $= ($FORMAT_LINES_PER_PAGE) にあります。そのハンドルが出力時に自動フラッシュするかどうかは $| ($OUTPUT_AUTOFLUSH) にあります。各ページの先頭の前(1 ページ目を除く)に出力される文字列は $^L ($FORMAT_FORMFEED) に格納されています。これらの変数はファイルハンドルごとに設定されるものなので、異なるファイルハンドルに効果を及ぼすには、そのファイルハンドルへ select() を行う必要があります:

    select((select(OUTF),
            $~ = "My_Other_Format",
            $^ = "My_Top_Format"
           )[0]);

ちょっと見づらいですね。でもこれは一般的なイディオムなんです; ですからこれを見たときにもそんなに驚かないでください。少なくとも、以前のファイルハンドルを保持するために一時変数を使うことができます: (一般的にはこちらのほうが良いやりかたです; なぜなら、読みやすくなるばかりでなく、式の途中でデバッガのシングルステップが使えるからです):

    $ofh = select(OUTF);
    $~ = "My_Other_Format";
    $^ = "My_Top_Format";
    select($ofh);

English モジュールを使っていれば、変数名もわかりやすいものにできます:

    use English;
    $ofh = select(OUTF);
    $FORMAT_NAME     = "My_Other_Format";
    $FORMAT_TOP_NAME = "My_Top_Format";
    select($ofh);

しかし、これでもまだ妙な select() があります。 FileHandle モジュールを使いましょう。そうすれば、これらの特殊変数の代わりに小文字のメソッド名を使ってアクセスできるようになります。

    use FileHandle;
    format_name     OUTF "My_Other_Format";
    format_top_name OUTF "My_Top_Format";

ずいぶん良くなりましたね!

注意

値の行には任意の式(^ フィールドではなく @ フィールドで)を含めることができるので、sprintf() や自分で作ったようなその他の関数を使ってより整った処理を行うことができます。例えば:

    format Ident =
        @<<<<<<<<<<<<<<<
        &commify($n)
    .

本当のキャレットやアットマークをフィールドに挿入するは以下のようにします:

    format Ident =
    I have an @ here.
            "@"
    .

行全体を中央寄せするには以下のようにします:

    format Ident =
    @|||||||||||||||||||||||||||||||||||||||||||||||
            "Some text line"
    .

「ページの幅に関係なくフィールドをページの右端に浮かせておく」ような組み込みの方法はありません。フィールドがどこに置かれるのかを指定する必要があります。本当にお薦めはできないのですが、カレントのカラムの数に基づいてその場でフォーマットを生成することが可能なので、そうしてから eval() するという手が使えます:

    $format  = "format STDOUT = \n"
             . '^' . '<' x $cols . "\n"
             . '$entry' . "\n"
             . "\t^" . "<" x ($cols-8) . "~~\n"
             . '$entry' . "\n"
             . ".\n";
    print $format if $Debugging;
    eval $format;
    die $@ if $@;

これは以下のようなフォーマットを生成するでしょう:

 format STDOUT =
 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 $entry
         ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
 $entry
 .

以下の例は、fmt(1) のようなことをするちょっとしたプログラムです:

 format =
 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
 $_

 .

 $/ = '';
 while (<>) {
     s/\s*\n\s*/ /g;
     write;
 }

フッタ

$FORMAT_TOP_NAME はカレントのヘッダフォーマットの名前を保持していているのですが、フッタに対して同じことを自動的に行う適切な仕掛けはありません。評価を行ってみるまではフォーマットがどれくらい大きなものになるのか知ることができないということが、大きな問題です。これは TODO リストにあります。

一つの戦略: あなたが固定サイズのフッタを使うのであれば、write() する前に $FORMAT_LINES_LEFT をチェックすればフッタを適切に表示できます。

別の戦略: open(MYSELF, "|-")("open" in perlfunc を参照)を使って自分自身に対するパイプをオープンして常に STDOUT ではなく MYSELF に write() するようにします。子プロセスではその STDIN からの入力を、ヘッダとフッタを再構成するために処理します。これは非常にお手軽というわけではありませんが、やればできます。

フォーマット機構の内部にアクセスする

フォーマット機構に対する低水準アクセスのために、formline() を使ったり、直接 $^A($ACCUMULATOR 変数) にアクセスすることができます。

例えば:

    $str = formline <<'END', 1,2,3;
    @<<<  @|||  @>>>
    END

    print "Wow, I just stored '$^A' in the accumulator!\n";

また、printf() に対する sprintf() と同じことを write() に対して行うサブルーチン swrite() を作成するために以下のようにできます:

    use Carp;
    sub swrite {
        croak "usage: swrite PICTURE ARGS" unless @_;
        my $format = shift;
        $^A = "";
        formline($format,@_);
        return $^A;
    }

    $string = swrite(<<'END', 1, 2, 3);
 Check me out
 @<<<  @|||  @>>>
 END
    print $string;

警告

フォーマットを終了する独立したドットは、間違って設定されているインターネットメーラー(そして経験によれば、そういった間違った設定は通例のものであって、例外ではありません)を通して渡されるメールメッセージを早まって終わらせてしまう可能性もあります。ですから、メイルを通じてフォーマットコードを送るときには、フォーマットを終端するドットがレフトマージンに乗らないようにインデントすべきです; これにより SMTP が途中で切ってしまうことを防ぎます。

("my" を使って宣言された)レキシカル変数は、フォーマットがそのレキシカル変数のスコープの内側で宣言されていない限りは、フォーマットの内側では不可視になります。

プログラムの環境が LC_NUMERIC ロケールを指定して、フォーマットを宣言したときに use locale が有効の場合でも、指定した小数点文字がフォーマットされた出力に現れます。フォーマットされた出力は write() が呼び出された時点では use locale プラグマによって制御することはできません。ロケールの処理に関する議論は perllocale を参照してください。

固定テキストフィールドに表示される文字列中の各制御文字は空白に置換されます。 (しかし、詰め込みモードでは \r は特別な意味を持つことを忘れないでください。) これは、制御文字が出力メディアによっては「消える」時に揃えが乱れることを防ぎます。