名前¶

CGI - Common Gateway Interface のリクエストとレスポンスを扱う

概要¶

    use CGI;

    my $q = CGI->new;

    # Process an HTTP request
     @values  = $q->param('form_field');

     $fh      = $q->upload('file_field');

     $riddle  = $query->cookie('riddle_name');
     %answers = $query->cookie('answers');

    # Prepare various HTTP responses
    print $q->header();
    print $q->header('application/json');

        $cookie1 = $q->cookie(-name=>'riddle_name', -value=>"The Sphynx's Question");
        $cookie2 = $q->cookie(-name=>'answers', -value=>\%answers);
    print $q->header(
        -type    => 'image/gif',
        -expires => '+3d',
        -cookie  => [$cookie1,$cookie2]
        );

   print  $q->redirect('http://somewhere.else/in/movie/land');

説明¶

CGI.pm は、HTML リクエストとレスポンスを処理したり準備したりするための、 安定しており、完全で、枯れているソリューションです。 主な機能としては、フォームの処理、ファイルアップロード、クッキーの読み書き、 クエリ文字列の生成と操作、HTML ヘッダの処理と準備などがあります。 いくつかの HTML 生成ユーリティティも含んでいます。

CGI.pm は CGI.pm 単体の環境でとてもよく機能し、 mod_perl や mod_perl2 および FastCGI 対応も内蔵しています。

数十人の貢献者によって 10 年以上開発と精製されてきたという利点があり、 何千ものウェブサイトで使われています。 CGI.pm は Perl 5.4 から Perl 配布に含まれていて、デファクトスタンダードに なっています。

プログラミングスタイル¶

CGI.pm ではオブジェクト指向スタイルと関数指向スタイルの 二つのプログラミングスタイルがあります。 オブジェクト指向スタイルでは、一つまたは 複数の CGI オブジェクトを作成し、ページのさまなざな要素を作成するために オブジェクトメソッドを使います。 各オブジェクトはサーバーによって スクリプトに渡された名前付きパラメータのリストが出発点となります。 オブジェクトを変更したり、ファイルやデータベースに格納し、それを元に 戻すことが出来ます。 というのも各オブジェクトは CGI スクリプトの "状態"(state)に対応しており、各オブジェクトのパラメータリストは、 その他のものとは独立しているため、スクリプトの状態を保存し後から 取り出すこともできるのです。

以下にオブジェクト指向スタイルを使って、簡単な "Hello World" HTML ページを どのように作成するかの例を示します:

   #!/usr/local/bin/perl -w
   use CGI;                             # load CGI routines
   $q = CGI->new;                        # create new CGI object
   print $q->header,                    # create the HTTP header
         $q->start_html('hello world'), # start the HTML
         $q->h1('hello world'),         # level 1 header
         $q->end_html;                  # end the HTML

関数指向スタイルでは、直接扱うことがまずない、一つのデフォルトの CGI オブジェクトがあります。 CGI パラメータを取り出し、HTML タグを作成し、 クッキーを管理する等々のために、代りに関数を単に呼び出します。 これは、よりすっきりしたプログラミングインタフェースを提供しますが、 一度に一つの CGI オブジェクトしか使えないよう制限します。 以下の例は同じページで関数指向インターフェースを使っています。 主な違いは、今度は名前空間に関数のセット (通常は "standard" の関数群) を インポートする必要があること、そして CGI オブジェクトを作成する必要が ないことです。

   #!/usr/local/bin/perl
   use CGI qw/:standard/;           # load standard CGI routines
   print header,                    # create the HTTP header
         start_html('hello world'), # start the HTML
         h1('hello world'),         # level 1 header
         end_html;                  # end the HTML

このドキュメントの例では主にオブジェクト指向スタイルを使います。 CGI.pm での関数指向プログラミングについての重要な情報は 「関数のインポート方法」をご覧下さい。

CGI.pm ルーチンの呼び出し¶

ほとんどの CGI.pm ルーチンはさまざまな引数を受け取ります。 中には 20 ものオプションの引数を受取るものもあります! このインターフェースを簡単にするため、すべてのルーチンは以下のような 名前付き引数呼び出しスタイルを使います:

   print $q->header(-type=>'image/gif',-expires=>'+3d');

各引数の名前の前にはダッシュがつきます。 引数リストでは大文字／小文字や順番は問題になりません。 -type、-Type、-TYPE のすべてが受取られます。 実際には、最初の引数だけがダッシュから始まる必要があります。 最初の引数にダッシュがあれば、CGI.pm は後のものにもダッシュが あるものとします。

さまざまなルーチンは一般に一つの引数だけで呼ばれます。 それらのルーチンの場合、引数名なしに一つの引数を与えることが出来ます。 header() は、そうしたルーチンの一つです。 この場合、一つの引数はドキュメントタイプです。

   print $q->header('text/html');

他のそのようなルーチンは下記で記述しています。

名前付き引数はあるときはスカラを期待し、あるときは配列へのリファレンス、 あるいはハッシュへのリファレンスを期待します。 多くの場合、どんな種類の引数も渡すことができ、ルーチンはそれに対して 最も適切なことを行います。 例えば param() ルーチンは CGI パラメータに一つあるいは複数の値を設定する ために使われます。 二つのケースを以下に示します:

   $q->param(-name=>'veggie',-value=>'tomato');
   $q->param(-name=>'veggie',-value=>['tomato','tomahto','potato','potahto']);

CGI.pm のルーチンの多くがモジュール内で特に定義されておらず、必要に応じて 自動的に生成されます。 これらは動的に生成されるページで使われ、HTML を 生成する "HTML ショートカット" ルーチンです。 HTML タグは属性(タグ自身に入っている属性="値"の組) と内容 (開始と終了の組の間の部分) の両方を持ちます。 属性と内容とを区別するため、CGI.pm は HTML 属性をハッシュリファレンスで 最初の引数として、そして内容があればその後の引数として、 渡すような約束を使っています。 それは以下のように機能します:

   Code                           Generated HTML
   ----                           --------------
   h1()                           <h1>
   h1('some','contents');         <h1>some contents</h1>
   h1({-align=>left});            <h1 align="LEFT">
   h1({-align=>left},'contents'); <h1 align="LEFT">contents</h1>

HTML タグについては後で詳しく記述します。

CGI を使い始めたばかりの人の多くが、HTML タグ属性を囲む中かっこを必要とする HTML ショートカットの呼び出し方と、中かっこ無しに属性の生成を管理する他の ルーチンの呼び出し方との違いに惑わされます。 混乱しないで下さい。 便宜上、中かっこは HTML を除くすべてでオプションです。 もし好むなら、名前付き引数を取るどのようなルーチンでも呼び出すときに 中かっこを使えます。 例えば:

   print $q->header( {-type=>'image/gif',-expires=>'+3d'} );

-w スイッチを使うと、いくつかの CGI.pm 引数は Perl 組込関数と名前が ぶつかっていることを警告されるでしょう。 これらのほとんどは、 複数の値を持つメニュー(multi-valued menu)、ラジオボタン(radio button)、 クラスター(cluster)などを作成するために使われる -values 引数です。 この警告を回避するためには、いくつかの選択肢があります:

1. Use another name for the argument, if one is available. For example, -value is an alias for -values.

   もし他の名前が使えれば、引数に他の名前を使う。 例えば -value は -values のための別名です。

2. Change the capitalization, e.g. -Values

   先頭を大文字化する。 例. -Values

3. Put quotes around the argument name, e.g. '-values'

   引数名の周りをクォートで囲む。 例. '-values'

多くのルーチンが理解できない名前付き引数についても、なんらかの有効なことを 行います。 例えば、名前付きの引数として与えることにより標準ではない HTTP ヘッダフィールドを作成することが出来ます:

  print $q->header(-type  =>  'text/html',
                   -cost  =>  'Three smackers',
                   -annoyance_level => 'high',
                   -complaints_to   => 'bit bucket');

これは以下の標準ではない HTTP ヘッダを作成します:

   HTTP/1.0 200 OK
   Cost: Three smackers
   Annoyance-level: high
   Complaints-to: bit bucket
   Content-type: text/html

アンダースコアが自動的にハイフンに変換される方法について注意してください。 HTML 作成ルーチンは異なる変換をします。

この機能は HTTP と HTML の"標準"に迅速に追いかけることを可能にします。

新しい問い合わせオブジェクトの作成(オブジェクト指向スタイル) ¶

     $query = CGI->new;

これは (POST と GET メソッドの両方からの) 入力を解析し、 $query と呼ばれる perl5 オブジェクトに格納します。

ファイルアップロードからのすべてのファイルハンドルは、 その位置をファイルの先頭にリセットします。

入力ファイルからの新しい問い合わせオブジェクトの作成¶

     $query = CGI->new(INPUTFILE);

ファイルハンドルを new() メソッドに与えると、ファイル (または STDIN でも なんでも) からパラメータを読み込みます。 デバッグ中、ファイルには以下に説明する形式ならば、何にでも することができます (つまり改行で区切られたタグ=値の組が機能します) 。 便利なことに、このファイルのタイプは save() メソッドにより作成されます。 複数のレコードを保存し、元に戻すことが出来ます。

Perl 純粋主義者はこの文法がファイルハンドルを、ファイルハンドルグロブさえも 受取ることを知って喜ぶでしょう; これはファイルハンドルを渡す「公式の」 方法です:

    $query = CGI->new(\*STDIN);

CGI オブジェクトを FileHandle または IO::File オブジェクトで初期化することも 出来ます。

関数指向インターフェースを使っていて、CGI 状態をファイルハンドルで 初期化したければ、restore_parameters()でおこないます。 これはデフォルトの CGI オブジェクトを指定されたファイルハンドルで (再) 初期化します。

    open (IN,"test.in") || die;
    restore_parameters(IN);
    close IN;

ハッシュリファレンスから問い合わせオブジェクトを初期化することも出来ます:

    $query = CGI->new( {'dinosaur'=>'barney',
                       'song'=>'I love you',
                       'friends'=>[qw/Jessica George Nancy/]}
                    );

あるいは適切にフォーマットされた、URL エスケープされた問い合わせ文字列から:

    $query = CGI->new('dinosaur=barney&color=purple');

あるいは既に存在している CGI オブジェクトから (現在、これはパラメータリストの 複製を作りますが、autoescaping のようなオブジェクト特有のフィールドは 複写しません):

    $old_query = CGI->new;
    $new_query = CGI->new($old_query);

空の問い合わせを作成するためには、空文字列または空のハッシュで初期化します:

   $empty_query = CGI->new("");

       -or-

   $empty_query = CGI->new({});

問い合わせからのキーワードのリストの取り出し¶

     @keywords = $query->keywords

<ISINDEX> 検索の結果としてスクリプトが呼び出されれば、解析されたキーワードは keywords() メソッドを使って配列として取得出来ます。

スクリプトの渡された全てのパラメータの名前の取り出し:¶

     @names = $query->param

パラメータ付きでスクリプトが呼び出されると (例えば "name1=value1&name2=value2&name3=value3") 、 param()メソッドはパラメータ名をリストで返します。 もしスクリプトが<ISINDEX>スクリプトとして呼び出され、アンパサンドのない 文字列が入っていれば (例えば、"value1+value2+value3") 、 "+" で区切られたキーワードが入った "keywords" という名前の一つの パラメータになります。

注意:バージョン1.5では、パラメータ名の配列はブラウザにより実行されたのと 同じ順番でした。 通常、この順序はパラメータがフォームで定義された順と同じです (しかしながら仕様には入っていないため保証はされません。)

一つの名前つきパラメータの値を取り出す:¶

    @values = $query->param('foo');

              -or-

    $value = $query->param('foo');

名前付きパラメータの値を取り出すために param() メソッドに一つの引数を 渡してください。 もしそのパラメータが複数の値を持っていれば(例えば スクローリングリスト(scrolling list)での複数の選択から)、配列で 受け取るようにすることが出来ます。 そうでなければ、このメソッドは一つの値を返します。

もし値が問い合わせ文字列で与えられなければ、つまり問い合わせで "name1=&name2=" であれば、空文字列を返します。

もしパラメータが全くなければ、param() はスカラコンテキストでは undef を 返し、リストコンテキストでは空リストを返します。

名前つきパラメータへの値の設定:¶

    $query->param('foo','an','array','of','values');

これは名前付きパラメータ 'foo' の値として値の配列を設定します。 これは、スクリプトが前に一度呼び出された後にフィールドの値を変更するための 一つの方法です。 (もう一つの方法はフォーム要素を作成するすべてのメソッドで受け取られる -override パラメータを使うことです。)

param() は下記でさらに詳しく記述する呼び出しの名前付きパラメータ形式も 理解します:

    $query->param(-name=>'foo',-values=>['an','array','of','values']);

                              -or-

    $query->param(-name=>'foo',-value=>'the value');

名前つきパラメータに値を追加する:¶

   $query->append(-name=>'foo',-values=>['yet','more','values']);

これは値または値のリストを名前付きパラメータに追加します。 既にあれば、その値はパラメータの最後に追加されます。 そうでなければパラメータが作成されます。 このメソッドは名前付き引数呼び出し書式しか理解しないことに注意してください。

すべてのパラメータの名前空間へのインポート:¶

   $query->import_names('R');

これは一連の変数を 'R' 名前空間に作成します。 例えば $R::foo、@R:foo のように。 キーワードリストでは、変数 @R:keyword があります。 名前空間が指定されなければ、この引数は 'Q' を想定します。 警告: 'main' には何もインポートしないこと; それはセキュリティ上、大きな 危険性があります!!!

注意 1: 変数名は必要に応じて有効な Perl 変数名に変換されます。 全ての無効な文字は下線に変換されます。 もし元の名前を保存しておく必要が亜あるなら、CGI 変数に名前で アクセスするのではなく、param() メソッドを使うべきです。

注意 2: 古いバージョンでは、このメソッドは import() と呼ばれていました。 バージョン 2.20 から、組み込みの Perl モジュール import 演算子と ぶつかることを避けるため、この名前は完全に削除されました。

パラメータを完全に削除する:¶

    $query->delete('foo','bar','baz');

これはパラメータを完全にクリアします。 それはスクリプト呼び出しの間で、渡したくないパラメータをリセットするのに 時々便利です。

関数呼び出しインターフェースを使っているのであれば、Perl の組み込み演算子 delete との衝突を避けるため、代わりに "Delete()" を使ってください。

すべてのパラメータを削除する:¶

   $query->delete_all();

これは CGI オブジェクトを完全にクリアします。 これはフォームを作成するときに、すべてのデフォルトが取られることを 保証するために便利です。

関数呼び出しインターフェースを使っているならば、代りに Delete_all() を使って ください。

URL エンコードされていない引数を扱う¶

もし POST されたデータのタイプが application/x-www-form-urlencoded か multipart/form-data ではない場合、POST されたデータは処理されず、 代わりに POSTDATA という名前のパラメータにそのままの形で返されます。 これを取得するには、以下のようなコードを使います:

   my $data = $query->param('POSTDATA');

同様に、PUT されたデータは以下のようなコードで取得できます:

   my $data = $query->param('PUTDATA');

(もしここに書いたことの意味が分からなくても、気にする必要はありません。 これは CGI を、XML 処理やその他の特殊な処理に使おうとする人々にのみ 影響します。

パラメータリストへの直接アクセス:¶

   $q->param_fetch('address')->[1] = '1313 Mockingbird Lane';
   unshift @{$q->param_fetch(-name=>'address')},'George Munster';

上述のメソッドでカバーされていない方法でパラメータリストへアクセスする 必要があるなら、その名前で param_fetch() を呼び出すことにより、それへの 直接のリファレンスを取得出来ます。 これは名前付きパラメータへの配列リファレンスを返し、これは好きなように 操作できます。

-name を使って、名前付き引数スタイルを使うことも出来ます。

パラメータリストのハッシュでの取り出し:¶

    $params = $q->Vars;
    print $params->{'address'};
    @foo = split("\0",$params->{'foo'});
    %params = $q->Vars;

    use CGI ':cgi-lib';
    $params = Vars;

多くの人がすべてのパラメータリストを、CGI パラメータの名前をキーとし、 そのパラメータの値を値とするハッシュとして取り出しがります。 これを Vars() メソッドが行います。 スカラコンテキストで呼ばれると、tie されたハッシュリファレンスとして パラメータリストを返します。 キーを変更すると、元になっている CGI パラメータリストでのパラメータの 値を変更します。 ハッシュコンテキストで呼ばれると、それは通常のハッシュとして パラメータリストを返します。 これによりパラメータリストの内容を読むことが出来ますが、変更することは できません。

これを使うとき、複数の値を持つ CGI パラメータについて気をつけなければ いけません。 ハッシュはスカラコンテキストとリストコンテキストを区別しないので、複数の値を もつパラメータは "\0"(null) 文字で区切られた、パックされた文字列で 返されます。 それぞれの値を取り出すためにはパックされた文字列を分割しなければなりません。 このやり方は Perl バージョン 4 のための cgi-lib.pl モジュールで、 Steve Brrenner によってずっと昔に導入されました。

Vars() を関数として使いたければ、関数呼び出しセット :cgi-lib を インポートしてください。 (CGI-LIB との互換性についてのセクションもご覧下さい)。

スクリプトの状態をファイルに保存する:¶

    $query->save(\*FILEHANDLE)

これはフォームの現在の状態を指定されたファイルハンドルに書き込みます。 new() メソッドにファイルハンドルを与えることにより読み戻すことが出来ます。 ファイルハンドルは、ファイル、パイプ、その他何にでもにすることが 出来ることに注意してください!

保存されるファイルの形式は以下の通りです:

        NAME1=VALUE1
        NAME1=VALUE1'
        NAME2=VALUE2
        NAME3=VALUE3
        =

名前と値の両方が URL エスケープされます。 複数の値を持つ CGI パラメータは名前を繰り返すことにより表すことができます。 セッションレコードはsingle=symbol によって範囲を決められます。 何回も new を呼ぶことにより、複数のレコードを書き出し、読み戻すことが 出来ます。 追記 (append) モードでファイルを開くことにより、複数のセッションに またがって、これを行うことが出来、これにより原始的なゲストブックや ユーザの質問の履歴を作成することが出来ます。 以下は複数のセッションレコードを作成する短い例です:

   use CGI;

   open (OUT,'>>','test.out') || die;
   $records = 5;
   for (0..$records) {
       my $q = CGI->new;
       $q->param(-name=>'counter',-value=>$_);
       $q->save(\*OUT);
   }
   close OUT;

   # reopen for reading
   open (IN,'<','test.out') || die;
   while (!eof(IN)) {
       my $q = CGI->new(\*IN);
       print $q->param('counter'),"\n";
   }

保存／復帰に使われるファイルフォーマットは Whitehead Genome Center の データ交換フォーマット"Boulderio" に使われているものと同じで、 Boulderio ユーティリティを使って扱ったり、さらにはデータベース化することが できます。 さらなる詳細は

  http://stein.cshl.org/boulder/

をご覧下さい。

関数指向 (非OO) からこの関数を使いたいのであれば、エクスポートされる このメソッドの名前は save_parameters() です。

CGIエラーの取り出し¶

ユーザ入力を処理して切る間、特にアップロードされたファイルを処理している 間にエラーが発生することがあります。 これらのエラーが発生したとき、CGI は処理を止め、空のパラメータリストを 返します。 エラーの存在とその性質を cgi_error() 関数を使って調べることが出来ます。 エラーメッセージは HTTP ステータスコードとしてフォーマットされます。 HTML ページにそのエラーテキストを入れたり、HTTP ステータスの値として 使うことができます:

    my $error = $q->cgi_error;
    if ($error) {
        print $q->header(-status=>$error),
              $q->start_html('Problems'),
              $q->h2('Request not processed'),
              $q->strong($error);
        exit 0;
    }

関数指向インターフェース (次のセクションをご覧下さい) を使うとき、エラーは 最初に param() を呼んだときにだけ発生します。 これに備えてください!

関数指向インターフェースの使い方¶

関数指向インタフェースを使うためには、どの CGI.pm ルーチンまたは関数群を スクリプトの名前空間にインポートするかを指定しなければいけません。 このインポートに関連して少しオーバーヘッドがありますが、大したことは ありません。

   use CGI <list of methods>;

リストに入れられたメソッドは現在のパッケージにインポートされます; CGI オブジェクトを最初に作成することなく直接呼び出すことが出来ます。 この例ではどのように param() と header() メソッドをインポートし、 それらを直接使うかを示しています:

   use CGI 'param','header';
   print header('text/plain');
   $zipcode = param('zipcode');

さらに多くの場合、名前でグループを参照することにより一般的な関数の組を インポートします。 すべての関数の組の前には ":html3" (HTML3標準で定義されたタグ用) のように、 前に":" がつきます。

以下にインポートできる関数の組のリストを示します:

:cgi

Import all CGI-handling methods, such as param(), path_info() and the like.

param(), path_info() のような、CGI を扱うすべてのメソッドを インポートします。

:form

Import all fill-out form generating methods, such as textfield().

textfield() のような、フォームを作成するメソッドをインポートします。

:html2

Import all methods that generate HTML 2.0 standard elements.

HTML 2.0 標準要素を作成するすべてのメソッドをインポートします。

:html3

Import all methods that generate HTML 3.0 elements (such as <table>, <super> and <sub>).

HTML 3.0 標準要素を作成するすべてのメソッドをインポートします。 (<table>, <super>, <sub> のような)

:html4

Import all methods that generate HTML 4 elements (such as <abbrev>, <acronym> and <thead>).

HTML 4 標準要素を作成するすべてのメソッドをインポートします。 (<abbrev>, <acronym>, <thead> のような)

:netscape

Import the <blink>, <fontsize> and <center> tags.

<blink>, <fontsize>, <center> タグをインポートします。

:html

Import all HTML-generating shortcuts (i.e. 'html2', 'html3', 'html4' and 'netscape')

すべての HTML 作成ショートカットをインポートします (つまり 'html2', 'html3', 'html4', 'netscape')

:standard

Import "standard" features, 'html2', 'html3', 'html4', 'form' and 'cgi'.

"標準"の機能、つまり 'html2', 'html3', 'html4', 'form', 'cgi' を インポートします。

:all

Import all the available methods. For the full list, see the CGI.pm code, where the variable %EXPORT_TAGS is defined.

利用可能なすべてのメソッドをインポートします。 全体のリストは CGI.pm のコードをご覧下さい; %EXPORT_TAGS という変数が定義されています。

CGI.pm の一部ではない関数名をインポートすると、モジュールはそれを 新しい HTML タグとして扱い、適切なサブルーチンを作成します。 そこで他の HTML タグと同じように使うことが出来ます。 これは急速に発展する HTML の「"標準」を提供するためです。 例えば Microsoft は <gradient> という新しいタグを発表したとします (これはマシンをリブートするまで、ユーザのデスクトップを回転する斜線で いっぱいにします)。 これをすぐに使い始めるのに、新しいバージョンの CGI.pm を待つ必要は ありません:

   use CGI qw/:standard :html3 gradient/;
   print gradient({-start=>'red',-end=>'blue'});

実行スピードの点から、CGI.pm はロードシンボルを指定するための標準の Exporter の書式を使わないことに注意してください。 これは将来変更されるかもしれません。

もし状態管理 CGI、またはフォーム作成メソッドのいずれかをインポートすると、 あることを要求するメソッドのいずれかを最初に使ったときに、デフォルトの CGI オブジェクトが自動的に作成され初期化されます。 これには param(), textfield(), submit() などが含まれます。 (直接 CGI オブジェクトにアクセスする必要があれば、グローバル変数 $CGI::Q があります)。 CGI.pm メソッドをインポートすることによって、以下のようにエレガントな スクリプトを書くことが出来ます:

   use CGI qw/:standard/;
   print 
       header,
       start_html('Simple Script'),
       h1('Simple Script'),
       start_form,
       "What's your name? ",textfield('name'),p,
       "What's the combination?",
       checkbox_group(-name=>'words',
                      -values=>['eenie','meenie','minie','moe'],
                      -defaults=>['eenie','moe']),p,
       "What's your favorite color?",
       popup_menu(-name=>'color',
                  -values=>['red','green','blue','chartreuse']),p,
       submit,
       end_form,
       hr,"\n";

    if (param) {
       print 
           "Your name is ",em(param('name')),p,
           "The keywords are: ",em(join(", ",param('words'))),p,
           "Your favorite color is ",em(param('color')),".\n";
    }
    print end_html;

プラグマ¶

関数セットに加えて、多くのプラグマをインポートすることができます。 プラグマの前には常にハイフンがつき、多くの方法で CGI.pm 関数の動きを 変更します。 プラグマ、関数セットそして個々の関数はすべて同じ use() 行で インポートすることができます。 例えば、以下の use ステートメントは標準の関数セットをインポートし、 デバッグモードを不可能にします(プラグマ -debug):

   use CGI qw/:standard -debug/;

プラグマの現在の一覧を以下に示します:

-any

When you use CGI -any, then any method that the query object doesn't recognize will be interpreted as a new HTML tag. This allows you to support the next ad hoc HTML extension. This lets you go wild with new and unsupported tags:

use CGI -any を使うとき、問い合わせオブジェクトが理解しない全ての メソッドは HTML タグとして解釈されます。 これにより次の アドホックな HTML 拡張をサポートすることが出来ます。 これは新しく、まだサポートされていないタグを自由に使わせてくれます:

   use CGI qw(-any);
   $q=CGI->new;
   print $q->gradient({speed=>'fast',start=>'red',end=>'blue'});

Since using <cite>any</cite> causes any mistyped method name to be interpreted as an HTML tag, use it with care or not at all.

<cite>any</cite> を使うと打ち間違えたどんなメソッド名も HTML タグとして 解釈されるので、使うときには注意するか、まったく使わないかのどちらかに してください。

-compile

This causes the indicated autoloaded methods to be compiled up front, rather than deferred to later. This is useful for scripts that run for an extended period of time under FastCGI or mod_perl, and for those destined to be crunched by Malcolm Beattie's Perl compiler. Use it in conjunction with the methods or method families you plan to use.

これは指定されたオートロードされるメソッドが後に延期されるのではなく、 先にコンパイルされます。 これは FastCGI や mod_perl などで 長時間実行されたり、Malcolm Beattie の Perl コンパイラにバリバリ食わせるようになっているような状況の下では 有効です。 使おうとしているメソッドあるいはメソッドファミリと結合して使ってください。

   use CGI qw(-compile :standard :html3);

or even

あるいは以下のようにさえも

   use CGI qw(-compile :all);

Note that using the -compile pragma in this way will always have the effect of importing the compiled functions into the current namespace. If you want to compile without importing use the compile() method instead:

このようにして-compile プラグマを使うことは、コンパイルされた関数が現在の 名前空間にインポートされる効果を常に持つことに注意してください。 インポートすることなしにコンパイルしたければ、代わりに compile() メソッドを 使ってください (下記をご覧下さい) :

   use CGI();
   CGI->compile();

This is particularly useful in a mod_perl environment, in which you might want to precompile all CGI routines in a startup script, and then import the functions individually in each mod_perl script.

これはあなたは startup スクリプトで全ての CGI ルーチンを予め コンパイルしておき、各 mod_perl スクリプトで個別に関数を インポートしたいかもしれない mod_perl 環境では特に便利です。

-nosticky

By default the CGI module implements a state-preserving behavior called "sticky" fields. The way this works is that if you are regenerating a form, the methods that generate the form field values will interrogate param() to see if similarly-named parameters are present in the query string. If they find a like-named parameter, they will use it to set their default values.

デフォルトでは CGI モジュールは "sticky" フィールドと呼ばれる、 ステート保存の振る舞いを実装します。 これが動作する方法は、フォームを再生成したときに、フォームフィールドの 値を生成するメソッドが、似たような名前のパラメータがクエリ文字列にあるか どうかを知るために param() に問い合わせます。 似たような名前のパラメータを見つけると、それをデフォルト値として使います。

Sometimes this isn't what you want. The -nosticky pragma prevents this behavior. You can also selectively change the sticky behavior in each element that you generate.

これがあなたの望んでいるものではない場合もあるでしょう。 -nosticky プラグマはこの振る舞いを抑制します。 生成した要素毎に sticky な振る舞いを変更することもできます。

-tabindex

Automatically add tab index attributes to each form field. With this option turned off, you can still add tab indexes manually by passing a -tabindex option to each field-generating method.

フォームフィールドのそれぞれに自動的にタブインデックス属性を追加します。 このオプションをオフにしても、それぞれのフィールド生成メソッドに -tabindex オプションを渡すことで手動でタブインデックスを追加できます。

-no_undef_params

This keeps CGI.pm from including undef params in the parameter list.

CGI.pm のパラメータリストに undef を入れさせないようにします。

-no_xhtml

By default, CGI.pm versions 2.69 and higher emit XHTML (http://www.w3.org/TR/xhtml1/). The -no_xhtml pragma disables this feature. Thanks to Michalis Kabrianis <kabrianis@hellug.gr> for this feature.

デフォルトでは、CGI.pm バージョン 2.69 以降は XHTML (http://www.w3.org/TR/xhtml1/) を出力します。 -no_xhtml プラグマは、この機能を止めます。 この機能について Michalis Kabrianis <kabrianis@hellug.gr> に感謝します。

If start_html()'s -dtd parameter specifies an HTML 2.0, 3.2, 4.0 or 4.01 DTD, XHTML will automatically be disabled without needing to use this pragma.

もし start_html() の -dtd パラメータで HTML 2.0, 3.2, 4.0, 4.01 の DTD が 指定されているなら、このプラグマを使わなくても XHTML は自動的に 無効になります。

-utf8

This makes CGI.pm treat all parameters as UTF-8 strings. Use this with care, as it will interfere with the processing of binary uploads. It is better to manually select which fields are expected to return utf-8 strings and convert them using code like this:

これは、CGI.pm が全てのパラメータを UTF-8 文字列として扱うようにします。 これはバイナリアップロードの邪魔となるので、注意して使ってください。 どのフィールドが utf-8 文字列を返すと想定されるかを自分で選択して、 それを以下のようなコードで変換した方がよいです:

 use Encode;
 my $arg = decode utf8=>param('foo');

-nph

This makes CGI.pm produce a header appropriate for an NPH (no parsed header) script. You may need to do other things as well to tell the server that the script is NPH. See the discussion of NPH scripts below.

これは CGI.pm にNPH (解析されないヘッダ(no parsed header)) スクリプトに 適したヘッダを作成させます。 サーバにそのスクリプトが NPH であると告げるために、他のことをする必要が あるかも知れません。 NPH スクリプトについては下記をご覧下さい。

-newstyle_urls

Separate the name=value pairs in CGI parameter query strings with semicolons rather than ampersands. For example:

CGI パラメータ問い合わせ文字列の名前=値の組を、アンパサンドではなく セミコロンで分割します。 例えば:

   ?name=fred;age=24;favorite_color=3

Semicolon-delimited query strings are always accepted, and will be emitted by self_url() and query_string(). newstyle_urls became the default in version 2.64.

セミコロン区切りの問い合わせ文字列は常に受け取られ、self_url() や query_string() では出力されません。 newstyle_urls はバージョン 2.64 からデフォルトになりました。

-oldstyle_urls

Separate the name=value pairs in CGI parameter query strings with ampersands rather than semicolons. This is no longer the default.

CGI パラメータ問い合わせ文字列の名前=値の組を、セミコロンではなく アンパサンドで分割します。 これはもはやデフォルトではありません。

-autoload

This overrides the autoloader so that any function in your program that is not recognized is referred to CGI.pm for possible evaluation. This allows you to use all the CGI.pm functions without adding them to your symbol table, which is of concern for mod_perl users who are worried about memory consumption. Warning: when -autoload is in effect, you cannot use "poetry mode" (functions without the parenthesis). Use hr() rather than hr, or add something like use subs qw/hr p header/ to the top of your script.

プログラム内の理解されないすべての関数が可能な評価のために CGI.pm が 参照されるよう autoloader をオーバーライドします。 これにより、それらをシンボルテーブルに加えることなく、すべての CGI.pm 関数を 使うことが出来ます。 これはメモリ消費を心配するmod_perlユーザに関連します。 警告: -autoload が有効なとき"詩的モード(poetry mode)" (かっこのない 関数) を使うことは出来ません。 hr ではなくhr() を使うか、use subs qw/hr p header/ のようなものを スクリプトの先頭に加えてください。

-no_debug

This turns off the command-line processing features. If you want to run a CGI.pm script from the command line to produce HTML, and you don't want it to read CGI parameters from the command line or STDIN, then use this pragma:

これはコマンド行処理機能をオフにします。 HTML を作成するため CGI.pm をコマンド行から実行したいけれども、標準入力や コマンド行からのリクエスト CGI パラメータを解析したくないのであれば、この プラグマを使ってください:

   use CGI qw(-no_debug :standard);

-debug

This turns on full debugging. In addition to reading CGI arguments from the command-line processing, CGI.pm will pause and try to read arguments from STDIN, producing the message "(offline mode: enter name=value pairs on standard input)" features.

これはコマンド行処理機能をオンにします。 コマンド行処理から CGI 引数を読み込むことに加えて、CGI.pm は一旦停止し、 STDIN から引数を読み込もうとして、 "(offline mode: enter name=value pairs on standard input)"という メッセージを出します。

See the section on debugging for more details.

さらなる詳細は「デバッグ」セクションをご覧ください。

-private_tempfiles

CGI.pm can process uploaded file. Ordinarily it spools the uploaded file to a temporary directory, then deletes the file when done. However, this opens the risk of eavesdropping as described in the file upload section. Another CGI script author could peek at this data during the upload, even if it is confidential information. On Unix systems, the -private_tempfiles pragma will cause the temporary file to be unlinked as soon as it is opened and before any data is written into it, reducing, but not eliminating the risk of eavesdropping (there is still a potential race condition). To make life harder for the attacker, the program chooses tempfile names by calculating a 32 bit checksum of the incoming HTTP headers.

CGI.pm はアップロードされたファイルを処理することができます。 通常、アップロードされたファイルはテンポラリディレクトリにスプールされ、 処理が終ると削除されます。 しかし、これには「ファイルアップロード」セクションでも説明しているように 盗聴の危険性があります。 それが秘密の情報であっても、アップロードの途中に他の CGI スクリプトの 作成者が覗き見ることができます。 UNIX システムでは、-private_tempfiles プラグマは、テンポラリファイルを 開かれると、何かデータが書込まれる前に、すぐに削除されるようにします。 これにより盗聴の危険性を減らしますが、完全ではなりません。 (まだ潜在的に可能な状態です) アタッカーに厳しく対応するためには、 プログラムは一時ファイル名をやって来た HTTP ヘッダの 32 ビットチェックサムを 計算することで選択します。

To ensure that the temporary file cannot be read by other CGI scripts, use suEXEC or a CGI wrapper program to run your script. The temporary file is created with mode 0600 (neither world nor group readable).

一時ファイルが他の CGI スクリプトが読むことが出来ないことを保証するには、 スクリプトを実行するために suEXEC または CGI ラッパを使ってください。 一時ファイルはモード 0600 (ワールドもグループも読むことが出来ない) で 作成されます。

The temporary directory is selected using the following algorithm:

一時ディレクトリは以下のアルゴリズムを使って選択されます:

    1. if the current user (e.g. "nobody") has a directory named
    "tmp" in its home directory, use that (Unix systems only).

    2. if the environment variable TMPDIR exists, use the location
    indicated.

    3. Otherwise try the locations /usr/tmp, /var/tmp, C:\temp,
    /tmp, /temp, ::Temporary Items, and \WWW_ROOT.

    1. 現在のユーザ(例えば"nobody")がホームディレクトリに "tmp" と
       いうディレクトリを持っていれば、それを使います (Unix システムのみ) 

    2. 環境変数 TMPDIR があれば、示された場所を使います

    3. そうでなければ、以下の場所を当たります /usr/tmp, /var/tmp, C:\temp,
    /tmp, /temp, ::Temporary Items, \WWW_ROOT

Each of these locations is checked that it is a directory and is writable. If not, the algorithm tries the next choice.

それぞれの場所はそれがディレクトリであるか、書きこみ可能かを チェックされます。 そうでなければアルゴリズムは次の選択を試してみます。

HTML タグ関数のインポートのための特別な形式¶

メソッドの多くが HTML を作成します。 下記で説明するように、タグ関数は自動的に開始と終了の両方のタグを自動的に 作成します。 例えば:

  print h1('Level 1 Header');

は 以下のものを作成します。

  <h1>Level 1 Header</h1>

ときには開始と終了タグを自分自身で作成したいときがあるでしょう。 この場合、以下のように start_タグ名 と end_タグ名 の形式を 使うことができます:

  print start_h1,'Level 1 Header',end_h1;

いくつかの例外がありますが (下記で説明)、start_タグ名 と end_タグ名関数は use CGI したときに自動的に作成されません。 しかし、その名前の前にアスタリスクを置くか、あるいは代わりに "start_タグ名" や "end_タグ名" をインポートリストに 要求することによって、start/end 関数を作成したいタグを 指定することができます。

例:

  use CGI qw/:standard *table start_ul/;

この例では、標準の関数に加えて以下の関数が作成されます:

1. start_table() (generates a <table> tag)

2. end_table() (generates a </table> tag)

3. start_ul() (generates a <ul> tag)

4. end_ul() (generates a </ul> tag)

動的なドキュメント作成¶

CGI.pm の関数のほとんどは実行中にドキュメントを作成することを扱います。 一般的にはまず HTTP ヘッダを作成し、その後にドキュメントそのものが続きます。 CGI.pm は HTML を作成するのと同じくらい、多くのさまざまな HTTP ヘッダを 作成するための関数を提供します! GIF イメージの作成については GD.pm モジュールをご覧ください。

これらの関数のそれぞれは HTML や HTTP の一部を作成します。 それらは直接出力できるので、ブラウザウィンドウに表示したり、文字列を 追加したり、後で使うようにファイルに保存したりといったことができます。

標準HTTPヘッダの作成:¶

通常、CGI スクリプトで最初にやることは HTTP ヘッダを出力することです。 これはブラウザに予想されるドキュメントのタイプを伝え、言語や有効期限、 ドキュメントをキャッシュするかどうかといった他のオプションの情報を与えます。 ヘッダは、サーバープッシュやペイパービューといった特別な目的のために 使われることもあります。

        print header;

             -or-

        print header('image/gif');

             -or-

        print header('text/html','204 No response');

             -or-

        print header(-type=>'image/gif',
                             -nph=>1,
                             -status=>'402 Payment required',
                             -expires=>'+3d',
                             -cookie=>$cookie,
                             -charset=>'utf-7',
                             -attachment=>'foo.gif',
                             -Cost=>'$2.00');

header() はContent-type: ヘッダを返します。 もし選択すれば、独自の MIME タイプを作成することができます。 そうでなければデフォルトは text/html です。 オプションの 2 番目のパラメータはステータスコードと人間が読むことができる メッセージを指定します。 例えば、204、"No response"を指定すると、ブラウザに何もしないように伝える スクリプトを作ることができます。

最後の例は、CGIメソッドへ引数を渡すための名前付き引数スタイルを示しています。 理解されるパラメータは -type, -status, -expires, -cookie です。 他の名前がついたパラメータはすべて、最初のハイフンを落とされて、 ヘッダフィールドに変えられるので、あなたが望むすべての HTTP ヘッダを 指定することが可能です。 内部のアンダースコアはハイフンに変換されます:

    print header(-Content_length=>3002);

ほとんどのブラウザは CGI スクリプトからの出力をキャッシュしません。 スクリプトが新たに呼び出されるたびに、ブラウザはページをリロードします。 この動きは -expires で変更することができます。 このパラメータで絶対または相対の有効期間を指定すると、いくつかのブラウザと プロキシーサーバは指定された有効期限まで、そのスクリプトの出力を キャッシュします。 以下の形式はすべて -expires フィールドに対して適切な値です:

        +30s                              30 seconds from now
        +10m                              ten minutes from now
        +1h                               one hour from now
        -1d                               yesterday (i.e. "ASAP!")
        now                               immediately
        +3M                               in three months
        +10y                              in ten years time
        Thursday, 25-Apr-1999 00:40:33 GMT  at the indicated time & date

        +30s                              今から 30 秒
        +10m                              今から 10 分
        +1h                               今から 1 時間
        -1d                               昨日 (つまり、「なるはや!」) 
        now                               直後に
        +3M                               3 ヶ月間
        +10y                              10 年間
        Thursday, 25-Apr-1999 00:40:33 GMT  指定された時刻と日付

-cookie パラメータはブラウザに、この後このスクリプトとの全ての トランザクションの間、「魔法のクッキー」を提供することを伝えます。 いくつかのクッキーは有効期限のような興味深い属性が入った特別な フォーマットを持っています。 セッションクッキーを作成し、取り出すためには cookie() メソッドを 使ってください。

-nphパラメータが真の値に設定されると、NPH (no-parse-header) スクリプトで機能するための正しいヘッダを出力します。 そのすべてのスクリプトが NPH であることを期待するような、ある種のサーバで 使う場合は重要です。

-charset パラメータはブラウザに送信される文字集合を制御するために 使うことが出来ます。 与えられなければ、デフォルトは ISO-8859-1 です。 副作用として、これは charset() メソッドも設定します。

-attachment パラメータは添付にページを切り替えるために使うことが出来ます。 ブラウザによっては、ページを表示する代りにファイルに保存するための プロンプトを表示します。 引数の値は保存されるファイルのための提案される名前です。 これが機能するためには、-type を "application/octet-stream" にしなければ いけないかもしれません。

-p3p パラメータは、出力ヘッダに P3P タグを追加します。 引数は、P3P タグの、配列リファレンスか空白区切りの文字列です。 例えば:

   print header(-p3p=>[qw(CAO DSP LAW CURa)]);
   print header(-p3p=>'CAO DSP LAW CURa');

どちらの場合も、出力されるヘッダh以下のようにフォーマットされます:

  P3P: policyref="/w3c/p3p.xml" cp="CAO DSP LAW CURa"

ヘッダの値に開業が含まれている場合、RFC2616 の 4.2 節で指定されているように、 すでに先頭に空白がない場合は、新しい行ごとに先頭に空白を追加します。 例えば:

    print header( -ingredients => "ham\neggs\nbacon" );

とすると、以下を出力します

    Ingredients: ham
     eggs
     bacon

リダイレクトヘッダの作成¶

   print $q->redirect('http://somewhere.else/in/movie/land');

ときには、ドキュメントをあなた自身が作成するのではなく、おそらく URL を 時刻やユーザの識別子をベースにより選択しながら、単にブラウザをどこかに リダイレクトしたいだけかもしれません。

redirect() メソッドはブラウザを他の URL にリダイレクトします。 もしこのようなリダイレクトを使えば、header も出力しては いけません。

リダイレクトするリクエストでは常に (http: や ftp: 部分も含めた) 完全な URL を使うべきです。 相対 URL は正しく動作しません。

名前付き引数も使うことができます:

    print $q->redirect(
        -uri=>'http://somewhere.else/in/movie/land',
            -nph=>1,
         -status=>301);

header() が認識する全ての名前付き引数は redirect() も認識します。 しかし、-cookie や -target で生成されるものを含む、ほとんどの HTTP ヘッダは ブラウザには無視されます。

-nph パラメータが真の値に設定されれば、それは NPH (no-parse-header) スクリプトで機能するための正しいヘッダを出力させます。 Microsoft IIS のように、そのすべてのスクリプトが NPH であることを期待する、 ある種のサーバで使うことは重要です。

-status パラメータはリダイレクトするステータスを設定します。 HTTP ではリダイレクトステータスコードとして三つの値を定義しています:

     301 Moved Permanently
     302 Found
     303 See Other

指定しなかったときのデフォルトは 302 で、"moved temporarily" を意味します。 望むならステータスを他のステータスコードに変更できます。 301, 302, 303 以外にステータスを変更すると、おそらくリダイレクトが 壊れるだろうということは忠告しておきます。

HTML ドキュメントヘッダの作成¶

   print start_html(-title=>'Secrets of the Pyramids',
                            -author=>'fred@capricorn.org',
                            -base=>'true',
                            -target=>'_blank',
                            -meta=>{'keywords'=>'pharaoh secret mummy',
                                    'copyright'=>'copyright 1996 King Tut'},
                            -style=>{'src'=>'/styles/style1.css'},
                            -BGCOLOR=>'blue');

HTTP ヘッダを作成した後、ほとんどの CGI スクリプトは HTML ドキュメントの 出力を始めます。 start_html() ルーチンはページの見た目や動きを制御するたくさんのオプションの 情報とともにページの先頭を作成します。

このメソッドは閉じられた HTML ヘッダと開かれた <body> タグを返します。 全てのパラメータはオプションです。 名前付きパラメータ形式で、理解されるパラメータは -title, -author, -base, -xbase, -target です (下記の説明をご覧ください) 。 非公式の BGCOLOR 属性ような、指定されたすべての追加のパラメータは <body> タグに追加されます。 追加のパラメータは前にハイフンをつけなければいけません。

引数 -xbase は以下のように、<base> タグを現在の位置から変えるために HREF を提供することを可能にします

    -xbase=>"http://home.mcom.com/"

すべての相対リンクは、このタグからの相対と解釈されます。

引数 -target はすべてのリンクとページ上のフォームのためのデフォルトの ターゲットフレームを指定することができます。 これは一部のブラウザでのみ機能する標準でない HTTP 機能です!

    -target=>"answer_window"

すべての相対リンクはこのタグのからの相対だと解釈されます。 -meta 引数でヘッダに任意のメタ情報を追加します。 この引数はメタ情報の名前/値の組が入ったハッシュへのリファレンスを想定します。 これらは以下のような、ヘッダでの一連の <meta> タグに変わります:

    <meta name="keywords" content="pharaoh secret mummy">
    <meta name="description" content="copyright 1996 King Tut">

<meta> タグの HTTP-EQUIV タイプを作るためには、以下で説明する -head を 使ってください。

-style タグはあなたのコードにカスケーディングスタイルシートを 入れるために使われます。 さらに詳細な情報は「カスケーディングスタイルシート」の節をご覧ください。

-lang 引数は <html> タグに language 属性を入れるために使われます。 例:

    print $q->start_html(-lang=>'fr-CA');

指定されなかった場合のデフォルトは アメリカ英語の "en-US" ですが、 -dtd 引数で HTML 2.0 か 3.2 DTD が指定された場合は lang 属性が省略されます。 その他の場合では空文字列を渡す (-lang=>'') ことによって lang 属性を 省略できます。

-encoding 引数を、XHTML のための文字集合を指定するために使うことが 出来ます。 指定されなければデフォルトは iso-8859-1 です。

XHTML と共に -declare_xml 引数が使われると、<?xml> 宣言が HTML ヘッダの 先頭に置かれます。 この宣言の唯一の目的は文字集合エンコーディングを宣言することです。 -declare_xml なしの場合、出力される HTML にはエンコーディングを指定した <meta> タグが含まれ、HTML が多くのバリデータを通過するようにします。 -declare_xml のデフォルトは偽です。

-head タグで他の任意の HTML 要素を <head> セクションに置くことができます。 例えば、あまり使われない <link> 要素を HEAD セクションに置くためには、 これを使ってください:

    print start_html(-head=>Link({-rel=>'next',
                                  -href=>'http://www.capricorn.com/s2.html'}));

複数の HTML 要素を <head> セクションに入れるためには、単に配列リファレンスを 渡してください:

    print start_html(-head=>[ 
                             Link({-rel=>'next',
                                   -href=>'http://www.capricorn.com/s2.html'}),
                             Link({-rel=>'previous',
                                   -href=>'http://www.capricorn.com/s1.html'})
                             ]
                     );

そして、これが HTTP-EQIV <meta> タグの作成方法です:

      print start_html(-head=>meta({-http_equiv => 'Content-Type',
                                    -content    => 'text/html'}))

JAVASCRIPTING: -script, -noScript, -onLoad, -onMouseOver, -onMouseOut, -onUnload パラメータが JavaScript 呼び出しをページに 追加するために使われます。 -script は JavaScript 関数定義が入ったテキストのブロックを 示さなければなりません。 このブロックは (HTTP ではなく) HTML 内部の <script> ブロックに置かれます。 たとえページが完全にロードされる前にユーザがストップボタンを押したとしても、 すべての JavaScript 関数が置かれるチャンスをあなたのページに与えるため、 そのブロックはヘッダに置きます。 CGI.pm は JavaScript を知らないブラウザが、そのコードで息が詰まることの ないような方法で、そのスクリプトをフォーマットしようとします: それにも関らず、残念ながら Chimera for Unix のように混乱してしまう ブラウザがいくつかあります。

-onLoad, -onUnload パラメータは、それぞれブラウザによって、 そのページが開かれたときと閉じられたときに実行される JavaScript コードを 示します。 通常これらのパラメータは -script フィールドで定義された関数を呼びます:

      $query = CGI->new;
      print header;
      $JSCRIPT=<<END;
      // Ask a silly question
      function riddle_me_this() {
         var r = prompt("What walks on four legs in the morning, " +
                       "two legs in the afternoon, " +
                       "and three legs in the evening?");
         response(r);
      }
      // Get a silly answer
      function response(answer) {
         if (answer == "man")
            alert("Right you are!");
         else
            alert("Wrong!  Guess again.");
      }
      END
      print start_html(-title=>'The Riddle of the Sphinx',
                               -script=>$JSCRIPT);

JavaScript を持っていないブラウザ (あるいは JavaScript がオフになっている ブラウザ) で表示される HTML テキストを渡すためには -noScript パラメータを 使ってください。

<script> タグは、"type" と src を含む、多くの属性を持ちます。 後者はソースを持った各ページに散乱させるのではなく、JavaScript コードを ファイルまたは CGI スクリプトに保管することを可能にするため、特に 興味深いものです。 この属性を使うためには、-script パラメータに一つまたはそれ以上の -type, -src, -code が入ったハッシュリファレンスを渡してください:

    print $q->start_html(-title=>'The Riddle of the Sphinx',
                         -script=>{-type=>'JAVASCRIPT',
                                   -src=>'/javascript/sphinx.js'}
                         );

    print $q->(-title=>'The Riddle of the Sphinx',
               -script=>{-type=>'PERLSCRIPT',
                         -code=>'print "hello world!\n;"'}
               );

最後の機能は複数の <script> セクションをヘッダに入れることを可能にします。 配列リファレンスとしてスクリプトセクションのリストを渡すだけです。 これは JavaScript の異なる方言のための異なるソースを指定することができます。 例えば:

     print $q->start_html(-title=>'The Riddle of the Sphinx',
                          -script=>[
                                    { -type => 'text/javascript',
                                      -src      => '/javascript/utilities10.js'
                                    },
                                    { -type => 'text/javascript',
                                      -src      => '/javascript/utilities11.js'
                                    },
                                    { -type => 'text/jscript',
                                      -src      => '/javascript/utilities12.js'
                                    },
                                    { -type => 'text/ecmascript',
                                      -src      => '/javascript/utilities219.js'
                                    }
                                 ]
                             );

"-language" オプションは -type と同じ意味で、過去互換性のためにあります。

古いスタイルの位置によるパラメータは以下の通りです。

Parameters:

1.

The title

タイトル

2.

The author's e-mail address (will create a <link rev="MADE"> tag if present

作者の e-mail アドレス (もしあれば <link ref="MADE"> タグを作成します)

3.

A 'true' flag if you want to include a <base> tag in the header. This helps resolve relative addresses to absolute ones when the document is moved, but makes the document hierarchy non-portable. Use with care!

<base> タグをヘッダに入れたければ、'true' フラグ。 これはドキュメントが動いたけれども、ドキュメントの階層は移植しないとき、 相対アドレスを絶対アドレスに解決するのを助けます。 注意して使ってください!

4, 5, 6...

Any other parameters you want to include in the <body> tag. This is a good place to put HTML extensions, such as colors and wallpaper patterns.

他のすべてのパラメータは <body> タグに入れたいものです。 ここは色や壁紙のパターンのような、HTML 拡張を置くのに適した場所です。

HTML ドキュメントの終わり:¶

        print end_html

</body></html> タグを出力することで HTML ドキュメントを終わらせます。

状態情報を保持し自分自身を参照する URL の作成:¶

    $myself = self_url;
    print q(<a href="$myself">I'm talking to myself.</a>);

self_url() は選択されたとき、今動いているすべての状態情報で、 このスクリプトを再度呼び出す URL を返します。 内部のアンカーを使ってドキュメントの中でジャンプしたいけれども、フォームの 現在の内容を壊したくないときにとても有効です。 以下のようにするとうまくいきます。

     $myself = self_url;
     print "<a href=\"$myself#table1\">See table 1</a>";
     print "<a href=\"$myself#table2\">See table 2</a>";
     print "<a href=\"$myself#yourself\">See for yourself</a>";

何を返すかを更に制御したければ、代わりに url() メソッドを使ってください。

処理されていない問い合わせ文字列は query_string() で取り出すこともできます:

    $the_string = query_string;

スクリプトの URL を取得する¶

    $full_url      = url();
    $full_url      = url(-full=>1);  #alternative syntax
    $relative_url  = url(-relative=>1);
    $absolute_url  = url(-absolute=>1);
    $url_with_path = url(-path_info=>1);
    $url_with_path_and_query = url(-path_info=>1,-query=>1);
    $netloc        = url(-base => 1);

url() はスクリプトの URL をさまざまなフォーマットで返します。 何も引数なしで呼ばれれば、ホスト名とポート番号を含んだ URL のフルの形式を 返します。

    http://your.host.com/path/to/script.cgi

このフォーマットを以下の名前付き引数で変更することができます:

-absolute

If true, produce an absolute URL, e.g.

真であれば、絶対 URL を作成します。 つまり、

    /path/to/script.cgi

-relative

Produce a relative URL. This is useful if you want to reinvoke your script with different parameters. For example:

相対 URL を作成します。 異なるパラメータでスクリプトをもう一度呼びたいときに、これは便利です。 例えば:

    script.cgi

-full

Produce the full URL, exactly as if called without any arguments. This overrides the -relative and -absolute arguments.

何も引数なしに呼んだのとまったく同じく、フルの URL を作成します。 これは -relative と-absolute を上書きします。

-path (-path_info)

Append the additional path information to the URL. This can be combined with -full, -absolute or -relative. -path_info is provided as a synonym.

URL に追加のパス情報を追加します。 これは -full, -absolute, -relative と一緒にすることができます。 -path_info が同義語として提供されます。

-query (-query_string)

Append the query string to the URL. This can be combined with -full, -absolute or -relative. -query_string is provided as a synonym.

URL に問い合わせ文字列を追加します。 これは -full, -absolute, -relative と一緒にすることができます。 -query_string が同義語として提供されます。

-base

Generate just the protocol and net location, as in http://www.foo.com:8000

http://www.foo.com:8000 のように単にプロトコルとネットでの位置を生成します。

-rewrite

If Apache's mod_rewrite is turned on, then the script name and path info probably won't match the request that the user sent. Set -rewrite=>1 (default) to return URLs that match what the user sent (the original request URI). Set -rewrite=>0 to return URLs that match the URL after mod_rewrite's rules have run. Because the additional path information only makes sense in the context of the rewritten URL, -rewrite is set to false when you request path info in the URL.

Apache の mod_rewrite が有効の場合、スクリプト名とパス情報はおそらく ユーザーが送ったリクエストと一致しないでしょう。 ユーザーが送ったものと一致する URL (本来のリクエスト URL) を返すためには -rewrite=>1 に設定します(これがデフォルトです)。 mod_rewrite のルールが適用された後の URL に一致する URL を返すためには -rewrite=>0 に設定します。 追加のパス情報は書き換えられたコンテキストでのみ意味があるので、 URL のパス情報を要求する場合は -rewrite に偽を設定します。

POST と URL パラメータを混ぜる¶

   $color = url_param('color');

問い合わせ文字列 (引数が後ろについた "?" マーク) が入った URL へ POST するフォームを作成することにより、スクリプトはフォームと同じように CGI パラメータをURLで受け取ることは可能です。 param() メソッドは、URL の問い合わせ文字列を無視し、常に POST された フォームの内容を返します。 URL パラメータを取り出すためには url_param() メソッドを 呼び出してください。 param() と同じように使ってください。 主な違いは、パラメータを読むことはできますが、設定はできないことです。

いかなる状況においても、URL 問い合わせ文字列の内容が POST されたフォームの 同じ名前の CGI パラメータを干渉することはありません。 URL 問い合わせ文字列と GET メソッドでサブミットされるフォームとを 混ぜてみると、その結果はあなたが予想しなかったことになるでしょう。

標準HTML要素の作成:¶

HTML 3 と HTML 4 タグのうち、全てではないとしても大半のものについて、 CGI.pm は一般的な HTML ショートカットメソッドを定義します。 HTML ショートカットは一つの HTML の後に名づけられ、出力でき、好きなように 扱うことができる HTML テキストの一部を返します。 各ショートカットは文字列に追加したり、ファイルの保存したり、または最も 一般的にはブラウザウィンドウで表示するように出力することができる HTML コードを返します。

この例は HTML メソッドをどのように使うかを示します:

   print $q->blockquote(
                     "Many years ago on the island of",
                     $q->a({href=>"http://crete.org/"},"Crete"),
                     "there lived a Minotaur named",
                     $q->strong("Fred."),
                    ),
       $q->hr;

この結果は以下の HTML コードになります (読みやすくするために改行を 入れています):

   <blockquote>
   Many years ago on the island of
   <a href="http://crete.org/">Crete</a> there lived
   a minotaur named <strong>Fred.</strong> 
   </blockquote>
   <hr>

HTML ショートカットの呼出しの書き方が不格好だと思えば、 名前空間にインポートし、オブジェクト的な書き方を完全に無くすことが できます (詳細は次のセクションをご覧ください) :

   use CGI ':standard';
   print blockquote(
      "Many years ago on the island of",
      a({href=>"http://crete.org/"},"Crete"),
      "there lived a minotaur named",
      strong("Fred."),
      ),
      hr;

HTML ショートカットに引数を与える¶

HTML メソッドは 0、一つまたは複数の引数を受け取ります。 もし引数を与えなければ一つのタグを得ます:

   print hr;    #  <hr>

もし一つまたは複数の文字列引数を与えれば、スペースでつなげられ、 開始と終了タグに囲まれます:

   print h1("Chapter","1"); # <h1>Chapter 1</h1>"

もし最初の引数がハッシュリファレンスであれば、そのハッシュのキーと 値は HTML タグの属性になります:

   print a({-href=>'fred.html',-target=>'_new'},
      "Open a new frame");

            <a href="fred.html",target="_new">Open a new frame</a>

もしそうしたければ、属性名の前につくダッシュをはずすことができます:

   print img {src=>'fred.gif',align=>'LEFT'};

           <img align="LEFT" src="fred.gif">

HTML タグ属性が引数を持たないこともあります。 例えば順序付きリストは COMPACT として印をつけることができます。 この書き方は undef 文字列を示す引数になります:

   print ol({compact=>undef},li('one'),li('two'),li('three'));

CGI.pm バージョン 2.41 より以前では、空('')文字列を属性引数として与える ことは undef を与えるのと同じでした。 しかし、これは <IMG ALT=""> 形式のタグを作りたい人たちに合わせるために 変更されました。 違いは以下の二つのコードで示されます:

   CODE                   RESULT
   img({alt=>undef})      <img alt>
   img({alt=>''})         <img alt="">

HTMLショートカットの分配されるプロパティ¶

HTML ショートカットの素晴らしい機能の一つに、それらが分配されることが あります。 リストへの リファレンス が入った引数を与えると、そのタグはリストの 各要素をまたがって分配されます。 例えば、順序付きのリストを作る方法の一つを以下に示します:

   print ul(
             li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy'])
           );

これは結果として以下のような HTML 出力になります:

   <ul>
     <li type="disc">Sneezy</li>
     <li type="disc">Doc</li>
     <li type="disc">Sleepy</li>
     <li type="disc">Happy</li>
   </ul>

これはテーブルを作るのとにとても便利です。 例えば:

   print table({-border=>undef},
           caption('When Should You Eat Your Vegetables?'),
           Tr({-align=>'CENTER',-valign=>'TOP'},
           [
              th(['Vegetable', 'Breakfast','Lunch','Dinner']),
              td(['Tomatoes' , 'no', 'yes', 'yes']),
              td(['Broccoli' , 'no', 'no',  'yes']),
              td(['Onions'   , 'yes','yes', 'yes'])
           ]
           )
        );

HTML ショートカットとリストの挿入¶

この小さなコードについて考えてみてください:

   print blockquote(em('Hi'),'mom!'));

これは通常に、おそらく期待した文字列を返します、すなわち:

   <blockquote><em>Hi</em> mom!</blockquote>

要素 "Hi" と要素" mom!" の間のスページに注意してください。 CGI.pm は配列を間に入れた場所に追加のスペースをおきます。 これは特別な $" 変数により制御されます。 時には、例えば一連のイメージの並べようとしているときなど、この追加の スペースはあなたの望んでいたものではありません。 この場合、$" を空文字列に変更することによって簡単に変更できます。

   {
      local($") = '';
      print blockquote(em('Hi'),'mom!'));
    }

コードをここで示したようにブロックにいれることを提案します。 そうしなければ明示的にリセットするまで、$" の変更が後のコードに影響を 与えます。

標準ではない HTML ショートカット¶

いくつかの HTML タグは様々な理由のために標準パターンに従いません。

comment() はHTMLコメント(<!-- comment -->)を作成します。 以下のように呼び出してください

    print comment('here is my comment');

組み込み Perl 関数とぶつかるので、以下の関数は先頭の文字が大文字になります:

    Select
    Tr
    Link
    Delete
    Accept
    Sub

さらに start_html(), end_html(), start_form(), end_form(), start_multipart_form() および全てのフォームタグは特別です。 それぞれのセクションをご覧ください。

HTMLの自動エスケープ¶

デフォルトでは、フォーム作成関数用により作成されるすべての HTML は escapeHTML() という関数を通ります:

$escaped_string = escapeHTML("unescaped string");

Escape HTML formatting characters in a string.

文字列に入っている HTML フォーマットの文字をエスケープします。

文字集合 ISO-8859-1 (デフォルト)を指定すると、標準の HTML エスケープの ルールが使われます。 "<" 文字は "&lt;"、">" は "&gt;", "&" は "&amp"、クォート文字は "&quot" になります。 さらに 0x8b と 0x9b 文字、これは多くの Windows ベースのブラウザは 左と右の斜めかっこに解釈されるのですが、は数値文字参照 ("&#8249" と "&#8250;") に置きかえられます。 charset() メソッドを明示的に呼び出すか、header() に -charset 引数を 渡すことにより、手で文字設定を変更した場合、CGI.pm はすべての可能性のある エンコーディングのための検索テーブルを持たないので、すべての 文字は 数値参照によって置きかえられます。

escapeHTML() は、与えられる文字列がテキスト文字列であることを 仮定しています。 これは、「外側」から受け取ったデータは Encode::decode して、 文字列は外側に送り出す前に Encode::encode するべきであるということです。 ソースコードが UTF-8 でエンコードされていて、ソース中の文字列リテラルを テキスト文字列に昇格したいなら、"use utf8" が使えます。 Perl がバイナリ文字列とテキスト文字列の違いをどう扱うかに関するさらなる 情報については perlunitut, perlunifaq, perlunicode を 参照してください。

自動エスケープは h1() のような他のショートカットには適用されません。 人々がゲストブックなどにいれるかもしれない困った書き方からあなたのページを 守るため、信用できないデータに対して escapeHTML() を呼ぶべきです。 文字集合を変更するには、charset() を使ってください。 自動エスケープを完全に止めるには autoEscape(0) を使ってください:

$charset = charset([$charset]);

Get or set the current character set.

現在の文字集合を取得あるいは設定します。

$flag = autoEscape([$flag]);

Get or set the value of the autoescape flag.

自動エスケープフラグの値を取得または設定します。

HTML をきれいに出力(PRETTY-PRINTING)¶

デフォルトでは、これらの関数により作成されるすべての HTML は、改行や インデントのない一つの長い行になります。 これは汚いですが、ドキュメントの大きさを 10%-20% 減らします。 きれいな出力を取得するには、Brian Paulsen によって作成された サブクラス CGI::Pretty を使ってください。

フォームの作成:¶

一般的な注意点 様々なフォーム作成メソッドは、すべて呼び出し元に要求された フォーム要素を作成するタグが入った文字列を返します。 あなたはこれらの文字列を実際に出力する責任があります。 このように設定されるので、フォーム要素の周りにフォーマットするタグを 置くことが出来ます。

他の注意点 フォームに指定するデフォルトの値は、(問い合わせ文字列がない時) スクリプトが呼び出された 最初のとき だけ使われます。 その後のスクリプト呼び出しでは(問い合わせ文字列があるとき)、たとえ 空白であっても前の値が使われます。

前の値からフィールドの値を変更したければ二つの選択肢があります:

(1) 設定するために param() メソッドを呼び出す。

(2) -override (別名 -force) パラメータを使う (バージョン 2.15 での新しい 機能)。 これは前の値に関係なく、デフォルトの値が使われるように強制します:

   print textfield(-name=>'field_name',
                           -default=>'starting value',
                           -override=>1,
                           -size=>50,
                           -maxlength=>80);

さらにもう一つの注意 デフォルトでは、フォーム要素のテキストとラベルは HTML ルールにしたがってエスケープされます。 つまりボタンのためのラベルとして "<CLICK ME>" を安全に使うことが出来ます。 しかしそのために、フィールドに A のような特殊な HTML 文字の並びを いれることができません。 自動的なエスケープをオフにしたければ、CGI オブジェクトを作成した直後に autoEscape() メソッドを false で呼び出してください:

   $query = CGI->new;
   $query->autoEscape(0);

autoEscape() は CGI.pm の HTML 生成関数がどのようにエスケープを扱うかの 振る舞いに影響を与えるためだけに使われることに注意してください。 明示的に escapeHTML() を呼び出すと、常に HTML をエスケープします。

潜んでいる罠! フォーム要素生成メソッドには複数のタグを返すものも あります。 スカラコンテキストでは、タグは空白(正確には $" 大域変数の現在の値)で 連結されます。 リストコンテキストでは、メソッドは要素のリストを返して、望むなら これを修正できます。 普通はこの振る舞いに気付くことはないでしょうが、以下のようなものには 注意してください:

    printf("%s\n",end_form())

end_form() は複数のタグを生成しますが、フォーマットは一つの値だけを 想定しているので、最初の一つだけが表示されます。

<p>

ISINDEX タグの作成¶

   print isindex(-action=>$action);

         -or-

   print isindex($action);

<isindex> タグを出力します。 あまり面白くはありません。 パラメータ -action は、問い合わせを処理するスクリプトの URL を指定します。 デフォルトでは現在のスクリプトで問い合わせを処理します。

フォームの開始と終了¶

    print start_form(-method=>$method,
                    -action=>$action,
                    -enctype=>$encoding);
      <... various form stuff ...>
    print end_form;

        -or-

    print start_form($method,$action,$encoding);
      <... various form stuff ...>
    print end_form;

start_form() は <form> タグを指定したオプションのメソッド、アクション、 フォームエンコーディングと一緒に返します。 デフォルトは以下の通りです:

    method: POST
    action: this script
    enctype: application/x-www-form-urlencoded for non-XHTML
             multipart/form-data for XHTML, see mulitpart/form-data below.

end_form() は </form> タグを返します。

Start_form() の enctype 引数はブラウザがフォームをサーバに送信する前にフォームの 様々なフィールドをどのようにパッケージするかを伝えます。 以下の二つの値が指定できます:

注意: このメソッドは以前 startform() および endform() という名前でした。 これらのメソッドは今では非推奨です。 代わりに start_form() と end_form() を使ってください。

application/x-www-form-urlencoded

This is the older type of encoding. It is compatible with many CGI scripts and is suitable for short fields containing text data. For your convenience, CGI.pm stores the name of this encoding type in &CGI::URL_ENCODED.

これは古いタイプのエンコーディングです。 多くの CGI スクリプトと互換性があり、テキストデータが入った短いフィールドに 適しています。 便利なように CGI.pm は、このエンコーディングタイプの名前を &$CGI::URL_ENCODED に格納しています。

multipart/form-data

This is the newer type of encoding. It is suitable for forms that contain very large fields or that are intended for transferring binary data. Most importantly, it enables the "file upload" feature. For your convenience, CGI.pm stores the name of this encoding type in &CGI::MULTIPART

これは新しいタイプのエンコーディングです。 これは非常に大きなフィールドを持ったフォームやバイナリデータを転送する フォームに適しています。 最も重要なことは、これは「ファイルアップロード」機能を可能にすることです。 便利なように CGI.pm は、このエンコーディングタイプの名前を &CGI::MULTIPART に格納しています。

Forms that use this type of encoding are not easily interpreted by CGI scripts unless they use CGI.pm or another library designed to handle them.

CGI.pm やそれらを扱うように設計されているほかのライブラリを使わなければ、 CGI スクリプトはこのタイプのエンコーディングを使うフォームを簡単には 解釈できません。

If XHTML is activated (the default), then forms will be automatically created using this type of encoding.

XHTML が有効(これがデフォルトです)なら、フォームは自動的にこのタイプの エンコーディングを使って作成されます。

start_form() メソッドは、XHTML を要求されない限りデフォルトでは古い形を 使います。 デフォルトで新しい形式を使いたければ、start_form() の代わりに start_multipart_form() を呼ぶことが出来ます。 end_multipart_form() メソッドは end_form() へのエイリアスです。

 JAVASCRIPTING: The B<-name> and B<-onSubmit> parameters are provided
for use with JavaScript.  The -name parameter gives the
form a name so that it can be identified and manipulated by
JavaScript functions.  -onSubmit should point to a JavaScript
function that will be executed just before the form is submitted to your
server.  You can use this opportunity to check the contents of the form 
for consistency and completeness.  If you find something wrong, you
can put up an alert box or maybe fix things up yourself.  You can 
abort the submission by returning false from this function.  

JAVASCRIPTING: -name と -onSubmit パラメータが JavaScript での 使用のために提供されています。 -name パラメータは JavaScript 関数によって識別され、扱えるようにフォームの 名前を与えます。 -onSubmit はフォームがサーバにサブミットされる直前に実行される JavaScript 関数を示さなければなりません。 この機会を使って、フォームの内容に矛盾がないか、すべて入っているかを チェックすることができます。 何かおかしな事を見つけたら、アラートボックスを表示したり、自分でそれを 修正するかもしれません。 この関数から false を返すことによってサブミットを中止することが出来ます。

通常 JavaScript の固まりは HTML ヘッダでの <script> ブロックで定義され、 -onSubmit はこれらの関数呼び出しの一つを指します。 詳細については start_html() をご覧下さい。

form 要素¶

フォームの開始後、典型的には一つまたは複数のテキストフィールド、 ポップアップメニュー、ラジオボタン、あるいはその他のフォーム要素を作成します。 これらの要素のそれぞれは標準セットの名前付き引数を取ります。 要素によってはオプションの引数もあります。 標準的な引数は以下のようなものです:

-name

The name of the field. After submission this name can be used to retrieve the field's value using the param() method.

フィールドの名前です。 送信後、この名前は param() メソッドでフィールドの値を取り出すときに 使われます。

-value, -values

The initial value of the field which will be returned to the script after form submission. Some form elements, such as text fields, take a single scalar -value argument. Others, such as popup menus, take a reference to an array of values. The two arguments are synonyms.

フォーム送信後スクリプトに返されるフィールドの初期値です。 テキストフィールドなどのいくつかの form 要素は、単一のスカラの -value 引数を取ります。 ポップアップメニューのようなそれ以外のものは、配列へのリファレンスを 取ります。 二つの引数は同義語です。

-tabindex

A numeric value that sets the order in which the form element receives focus when the user presses the tab key. Elements with lower values receive focus first.

ユーザーがタブキーを押したときにどの form 要素がフォーカスを受けるかの 順番をセットする数値です。 小さい値の要素が先にフォーカスを受けます。

-id

A string identifier that can be used to identify this element to JavaScript and DHTML.

要素を JavaScript や DHTML で識別するために使われる識別文字列。

-override

A boolean, which, if true, forces the element to take on the value specified by -value, overriding the sticky behavior described earlier for the -nosticky pragma.

真なら以前に指定された -nosticky プラグマを上書きして、-value で 指定された値を使うという真偽値。

-onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut, -onSelect

These are used to assign JavaScript event handlers. See the JavaScripting section for more details.

これらは JavaScript イベントハンドラを割り当てるために使われます。 更なる詳細については JavaScript の章を参照してください。

その他の一般的な引数は次の章で記述されています。 これらに加えて、HTML 仕様で技術されている全ての属性に対応しています。

テキストフィールドの作成¶

    print textfield(-name=>'field_name',
                    -value=>'starting value',
                    -size=>50,
                    -maxlength=>80);
        -or-

    print textfield('field_name','starting value',50,80);

textfield() はテキスト入力フィールドを返します。

Parameters

1.

The first parameter is the required name for the field (-name).

最初のパラメータは必須で、フィールド名です (-name)。

2.

The optional second parameter is the default starting value for the field contents (-value, formerly known as -default).

2 番目のパラメータはオプションで、フィールド内容のデフォルト文字列です (-value; 以前は -default でした)。

3.

The optional third parameter is the size of the field in characters (-size).

3 番目のパラメータはオプションで、文字数によるフィールドの 大きさです (-size)。

4.

The optional fourth parameter is the maximum number of characters the field will accept (-maxlength).

4 番目のパラメータはオプションで、そのフィールドが受けつける 最大文字数です (-maxlength)。

これらすべてのメソッドでは、フィールドはそのスクリプトの以前の呼び出し からの内容で初期化されます。 フォームが処理されたとき、テキストフィールドの値は以下のように 取り出すことが出来ます:

       $value = param('foo');

そのスクリプトが1 回呼び出された後に初期値でリセットしたければ、 以下のようにすることが出来ます:

       param('foo',"I'm taking over this value!");

大きなテキストフィールドの作成¶

   print textarea(-name=>'foo',
                          -default=>'starting value',
                          -rows=>10,
                          -columns=>50);

        -or

   print textarea('foo','starting value',10,50);

textarea() は、まるでテキストフィールドのようですが、複数行テキスト 入力ボックスのために行と列を指定することが出来ます。 そのフィールドに開始する値を与えることができます。 それは長くしたり、複数行にすることができます。

パスワードフィールドの作成¶

   print password_field(-name=>'secret',
                                -value=>'starting value',
                                -size=>50,
                                -maxlength=>80);
        -or-

   print password_field('secret','starting value',50,80);

password_field() は、その内容が web ページでは星印で表示されることを 除いては、textfield() と同じです。

ファイルアップロードフィールドの作成¶

    print filefield(-name=>'uploaded_file',
                            -default=>'starting value',
                            -size=>50,
                            -maxlength=>80);
        -or-

    print filefield('uploaded_file','starting value',50,80);

filefield() はファイルアップロードフィールドを返します。 利点をすべて生かすためには、そのフォームに 新しいマルチパートエンコーディングスキームを使わなければなりません。 これはエンコーディングタイプを &CGI::MULTIPART で start_form() を 呼び出すか、普通の start_form() の代わりに新しいメソッド start_multipart_form() を呼び出すかのどちらかで行うことが出来ます。

Parameters

1.

The first parameter is the required name for the field (-name).

最初のパラメータは必須で、フィールド名です(-name) 。

2.

The optional second parameter is the starting value for the field contents to be used as the default file name (-default).

2 番目のパラメータはオプションで、デフォルトのファイル名として 使われるフィールド内容のための初期値です (-default)。

For security reasons, browsers don't pay any attention to this field, and so the starting value will always be blank. Worse, the field loses its "sticky" behavior and forgets its previous contents. The starting value field is called for in the HTML specification, however, and possibly some browser will eventually provide support for it.

セキュリティ上の理由から、ブラウザはこのフィールドには注意を 払いません、そのため初期値は常にブランクになります。 さらに悪いことに、フィールドはその "stickyな" 動きを失い、前の内容を 忘れてしまいます。 しかし HTML 仕様では初期値フィールドが要求されていて、多分いくつかの ブラウザは最終的にはそれをサポートでしょう。

3.

The optional third parameter is the size of the field in characters (-size).

3 番目のパラメータはオプションで、フィールドの大きさを文字数で 指定します (-size)。

4.

The optional fourth parameter is the maximum number of characters the field will accept (-maxlength).

4 番目のパラメータはオプションで、そのフィールドが受取る最大文字数です (-maxlength)。

JAVASCRIPTING: -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut, -onSelect パラメータが理解されます。 詳細は textfield() をご覧下さい。

ファイルアップロードフィールドの処理¶

基本¶

フォームを処理するときに、以下のようにしてファイルアップロード用の IO::Handle 互換のハンドルを取得できます:

  $lightweight_fh  = $q->upload('field_name');

  # undef may be returned if it's not a valid file handle
  if (defined $lightweight_fh) {
    # Upgrade the handle to one compatible with IO::Handle:
    my $io_handle = $lightweight_fh->handle;

    open (OUTFILE,'>>','/usr/local/web/users/feedback');
    while ($bytesread = $io_handle->read($buffer,1024)) {
      print OUTFILE $buffer;
    }
  }

リストコンテキストでは、upload() はファイルハンドルの配列を返します。 これにより同じ名前の複数の upload フィールドを使うフォームを処理することが 可能になります。

入力されたファイル名がほしい場合は、単に param() を呼び出します:

  $filename = $q->param('field_name');

ブラウザによってちょっとずつ違う名前を返します。 あるブラウザはファイル名だけを返します。 あるものはユーザのマシンのパスの書き方を使ったファイルへのフルパスを 返します。 いずれにせよ返される名前は常に ユーザの マシンでのファイル名で、 CGI.pm がアップロードのスプーリングのさいに 作成する一時ファイルの名前には関連しません (以下をご覧ください)。

ファイルがアップロードされるとき、ブラウザは通常、ヘッダのフォーマットの 中にいくつかの情報を一緒に送信します。 その情報には通常、MIME content type が入っています。 この情報を取り出すためには、uploadInfo()を呼び出してください。 それはすべてのドキュメントヘッダが入ったハッシュへのリファレンスを返します。

       $filename = $q->param('uploaded_file');
       $type = $q->uploadInfo($filename)->{'Content-Type'};
       unless ($type eq 'text/html') {
        die "HTML FILES ONLY!";
       }

"text" と "binary" データモードを理解するマシンを使っているのであれば、 それをいつ、どのように使うかを確認してください (ラクダ本をご覧下さい)。 そうでなければ、ファイルアップロードの間にバイナリファイルが おかしくなることを発見するでしょう。

一時ファイルに直接アクセスする¶

アップロードされたファイルを処理するときに、CGI.pm はハードディスクに 一時ファイルを作って、あなたにそのファイルのファイルハンドルを返します。 あなたがファイルハンドルを使い終わった後、CGI.pm は一時ファイルを 削除します。 もし必要なら、一時ファイルに直接アクセすることもできます。 ファイルアップロードの一時ファイルには、tmpFileName() メソッドに ファイル名を渡すことでアクセスできます:

       $filename = $query->param('uploaded_file');
       $tmpfilename = $query->tmpFileName($filename);

一時ファイルは、あなたが手動で名前を変えない限り、プログラムの終了時に 自動的に削除されます。 (Windows NT のような)一部の OS では、プログラムの終了前に一時ファイルの ファイルハンドルを閉じる必要があります。 さもなければ一時ファイルの削除に失敗します。

中断されたファイルアップロードを扱う¶

ときどきアップロードされたファイルを解析している途中に問題が発生します。 通常それはユーザがアップロードが完了する前に "Stop" を押したときにおこります。 この場合、CGI.pm はアップロードされたファイルの名前の代りに undef を、 cgi_error() に文字列 "400 Bad Request (malformed multipart POST)" を 設定します。 このエラーメッセージはブラウザに送信するステータスコードに 入れることができるように考えられています。 例えば:

   $file = $q->upload('uploaded_file');
   if (!$file && $q->cgi_error) {
      print $q->header(-status=>$q->cgi_error);
      exit 0;
   }

もしも望むなら、エラーについて不満をいうために独自の HTML ページを自由に 作ることができます。

Progress bars for file uploads and avoiding temp files¶

CGI.pm は、ファイルアップロードフックを通してファイルアップロード管理への 低レベルアクセスを提供します。 この機能を使って、ファイルアップロード時のテンポラリファイルの使用を 完全にオフにしたり、独自のファイルアップロードプログレスバーを書いたり 出来ます。

これは Apache::Request で提供される UPLOAD_HOOK 機能ととてもよく 似ていますが、コールバックへ渡される最初の引数が Apache::Upload オブジェクトではなく、リモートファイル名であるという違いがあります。

 $q = CGI->new(\&hook [,$data [,$use_tempfile]]);

 sub hook {
        my ($filename, $buffer, $bytes_read, $data) = @_;
        print  "Read $bytes_read bytes of $filename\n";
 }

$data フィールドはオプションです; これにより、フックした コールバックに設定情報 (データベースハンドルなど) を渡せます。

$use_tempfile フィールドは、CGI.pm がファイルアップロード中に ディスクベースの一時ファイルの使用をオンまたはオフにするフラグです。 もしこれを偽の値にする (デフォルトは真) と、$q->param('uploaded_file') は もはや動作せず、アップロードされたデータを得る唯一の方法は設定された フック経由になります。

関数指向インターフェースを使う場合は、param() はその他の CGI 関数を 呼び出す前に CGI::upload_hook() を呼び出します:

  CGI::upload_hook(\&hook [,$data [,$use_tempfile]]);

このメソッドはデフォルトではエクスポートされません。 これを CGI:: 接頭辞なしで使いたいなら、明示的にインポートする必要が あります。

Windows でのファイルアップロードのトラブルシューティング¶

Windows プラットホームで CGI.pm を使っていて、バイナリファイルは 少し大きくなるのに、テキストファイルは同じままであることを発見したならば、 あなたは出力のファイルにバイナリモードを有効にすることを忘れています。 アップロードされたファイルをディスクに書き出すための全てのハンドルに binmode() を確実に呼び出してください。

ファイルアップロードを処理するための古い方法¶

(この章は完全性のためにあります。もし CGI.pm を使って新たにアプリケーションを 作っているのなら、読み飛ばしてください。)

CGI.pm でファイルアップロードを処理する元々の方法は param() を 使うことでした。 返される値はファイル名と軽量ファイルハンドルの二重の性質を持っています。 この二重の性質は、use strict を指定するという推奨されている慣習に 従っていると問題となります。 Perl は文字列をファイルハンドルとして使おうとすると警告を出します。 もっと深刻なことに、リモートユーザがアップロードフィールドにごみを 設定することが可能で、この場合 param() で得られるのは ファイルハンドルではなく、単なる文字列です。

この問題を解決するために upload() メソッドが追加され、常に軽量 ファイルハンドルを返します。 これは一般的にはうまく動作しますが、ファイルハンドルが IO::Handle の 派生クラスではないため、その他のモジュールとの相互運用性に問題が起きることが ありました。 それで、upload() で返されるファイルハンドルに対して handle() メソッドを 呼び出すという、上述した現在の推奨となりました。 これは、最初に呼び出したときに IO::Handle を読み込むという小さいペナルティと 引き替えに互換性に関して大きな勝利となりました。

ポップアップメニューの作成¶

   print popup_menu('menu_name',
                            ['eenie','meenie','minie'],
                            'meenie');

      -or-

   %labels = ('eenie'=>'your first choice',
              'meenie'=>'your second choice',
              'minie'=>'your third choice');
   %attributes = ('eenie'=>{'class'=>'class of first choice'});
   print popup_menu('menu_name',
                            ['eenie','meenie','minie'],
          'meenie',\%labels,\%attributes);

        -or (named parameter style)-

   print popup_menu(-name=>'menu_name',
                            -values=>['eenie','meenie','minie'],
                            -default=>['meenie','minie'],
          -labels=>\%labels,
          -attributes=>\%attributes);

popup_menu() はメニューを作成します。

1. The required first argument is the menu's name (-name).

   最初のパラメータは必須で、メニューの名前です (-name)。

2. The required second argument (-values) is an array reference containing the list of menu items in the menu. You can pass the method an anonymous array, as shown in the example, or a reference to a named array, such as "\@foo".

   2 番目の引数 (-values) は必須で 、メニューでのメニュー項目が入った 配列リファレンスです。 例のように無名配列をメソッドに渡すことが出来ます。 また "\@foo" のように名前付き配列へのリファレンスにすることも出来ます.

3. The optional third parameter (-default) is the name of the default menu choice. If not specified, the first item will be the default. The values of the previous choice will be maintained across queries. Pass an array reference to select multiple defaults.

   3 番目の引数 (-default) はオプションで、デフォルトで選択されるメニューの 名前です。 指定されなければ最初の項目がデフォルトです。 前に選択された値が問い合わせをまたがって維持されます。 デフォルトで複数を選択するために配列リファレンスを渡します。

4. The optional fourth parameter (-labels) is provided for people who want to use different values for the user-visible label inside the popup menu and the value returned to your script. It's a pointer to an hash relating menu values to user-visible labels. If you leave this parameter blank, the menu values will be displayed by default. (You can also leave a label undefined if you want to).

   4 番目のパラメータ (-labels) はオプションで、ユーザに見えるラベルのための値と スクリプトに返される値とを違うものにしたい人のために提要されています。 メニューの値とユーザに見えるラベルとを関連付けるハッシュへのポインタです。 このパラメータを空にしておくと、デフォルトでメニューの値は表示された ものになります (もしそうしたければラベルを未定義にしておくこともできます)

5. The optional fifth parameter (-attributes) is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to a hash relating menu values to another hash with the attribute's name as the key and the attribute's value as the value.

   5 番目のパラメータ (-attributes) はオプションで、汎用的な HTML 属性を 個別のメニュー要素に与えるために提供されます。 メニューの値を属性の名前をキーとし属性の値を値とする他のハッシュに関連付ける ハッシュへのポインタになります。

フォームが処理されるとき、ポップアップメニューの選択された値は 以下のようにして取り出すことが出来ます:

      $popup_menu_value = param('menu_name');

オプショングループの作成¶

名前付きパラメータのスタイル

  print popup_menu(-name=>'menu_name',
                  -values=>[qw/eenie meenie minie/,
                            optgroup(-name=>'optgroup_name',
                                             -values => ['moe','catch'],
                                             -attributes=>{'catch'=>{'class'=>'red'}})],
                  -labels=>{'eenie'=>'one',
                            'meenie'=>'two',
                            'minie'=>'three'},
                  -default=>'meenie');

  Old style
  print popup_menu('menu_name',
                  ['eenie','meenie','minie',
                   optgroup('optgroup_name', ['moe', 'catch'],
                                   {'catch'=>{'class'=>'red'}})],'meenie',
                  {'eenie'=>'one','meenie'=>'two','minie'=>'three'});

optgroup() はポップアップメニューの中にオプショングループを作成します。

1. The required first argument (-name) is the label attribute of the optgroup and is not inserted in the parameter list of the query.

   最初のパラメータ (-name) は必須で、optgroup の label 属性であり、 問い合わせのパラメータリストには 挿入されません。

2. The required second argument (-values) is an array reference containing the list of menu items in the menu. You can pass the method an anonymous array, as shown in the example, or a reference to a named array, such as \@foo. If you pass a HASH reference, the keys will be used for the menu values, and the values will be used for the menu labels (see -labels below).

   2番目の引数 (-values) は必須で 、メニューでのメニュー項目が入った 配列リファレンスです。 例のように無名配列をメソッドに渡すことが出来ます。 また \@foo のように名前付き配列へのリファレンスにすることも出来ます。 もしハッシュリファレンスを渡せば、キーがメニューの値として使われ、 値はメニューのラベルとして使われます(下記の -labels をご覧ください) 。

3. The optional third parameter (-labels) allows you to pass a reference to a hash containing user-visible labels for one or more of the menu items. You can use this when you want the user to see one menu string, but have the browser return your program a different one. If you don't specify this, the value string will be used instead ("eenie", "meenie" and "minie" in this example). This is equivalent to using a hash reference for the -values parameter.

   3 番目のパラメータ (-labels) はオプションで、メニュー項目の一つあるいは 複数のユーザーに見えるラベルが入ったハッシュへのリファレンスを渡すことを 可能にします。 ユーザメニュー文字列を見て、ブラウザにはあなたに違う値を返すことを 可能にします。 これを指定しないと、value の文字列が代わりに使われます。 (この例では"eenie", "meenie", "minie" になります)。 これは -values パラメータにハッシュリファレンスを使うのと同じです。

4. An optional fourth parameter (-labeled) can be set to a true value and indicates that the values should be used as the label attribute for each option element within the optgroup.

   4 番目の引数 (-labeled) はオプションで、true 値に 設定することができます。 value が、optgroup の中のオプション各オプション項目のための label 属性として 使われることを示します。

5. An optional fifth parameter (-novals) can be set to a true value and indicates to suppress the val attribute in each option element within the optgroup.

   5 番目の引数 (-novals) はオプションで、true 値に設定することができます。 optgroup の中の各オプション項目での val 属性を抑止することを示します。

   See the discussion on optgroup at W3C (http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP) for details.

   詳細については W3C での optgroup についての議論をご覧ください。 (http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP)

6. An optional sixth parameter (-attributes) is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to a hash relating menu values to another hash with the attribute's name as the key and the attribute's value as the value.

   6 番目の引数 (-attributes) はオプションで、個別のメニュー項目に共通の HTML 属性のいずれかに代入するために提供されます。 メニューの値を属性の名前をキー、属性の値を値とするハッシュに関連付ける ハッシュへのポインタとなります。

スクローリングリストの作成¶

   print scrolling_list('list_name',
                                ['eenie','meenie','minie','moe'],
        ['eenie','moe'],5,'true',{'moe'=>{'class'=>'red'}});
      -or-

   print scrolling_list('list_name',
                                ['eenie','meenie','minie','moe'],
                                ['eenie','moe'],5,'true',
        \%labels,%attributes);

        -or-

   print scrolling_list(-name=>'list_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -default=>['eenie','moe'],
                                -size=>5,
                                -multiple=>'true',
        -labels=>\%labels,
        -attributes=>\%attributes);

scrolling_list() はスクローリングリストを作成します。

Parameters:

1.

The first and second arguments are the list name (-name) and values (-values). As in the popup menu, the second argument should be an array reference.

最初と 2 番目の引数はリストの名前 (-name) と値 (-values)です。 ポップアップメニュー (訳者注:スクローリングリストの間違いらしい) では、 2 番目の引数は配列リファレンスでなければなりません。

2.

The optional third argument (-default) can be either a reference to a list containing the values to be selected by default, or can be a single value to select. If this argument is missing or undefined, then nothing is selected when the list first appears. In the named parameter version, you can use the synonym "-defaults" for this parameter.

3 番目の引数 (-default) はオプションで、デフォルトで選択される値が 入ったリストへのリファレンスか、選択される一つの値のどちらかにすることが できます。 この引数がないか未定義であれば、リストがはじめて表示されたときには 何も選択されません。 名前付きパラメータのバージョンでは、このパラメータに同義語 "-defaults" を 使うことが出来ます。

3.

The optional fourth argument is the size of the list (-size).

4 番目の引数はオプションで、リストの大きさです (-size)。

4.

The optional fifth argument can be set to true to allow multiple simultaneous selections (-multiple). Otherwise only one selection will be allowed at a time.

5 番目の引数はオプションで、同時に複数の選択を許すためには真を設定します (-multiple)。 そうでなければ一度には一つのだけが許されます。

5.

The optional sixth argument is a pointer to a hash containing long user-visible labels for the list items (-labels). If not provided, the values will be displayed.

6 番目の引数はオプションで、リスト要素のための長い、ユーザに見えるラベルが 入ったハッシュへのポインタです (-labels)。 提供されなければ値(values)が表示されます。

6.

The optional sixth parameter (-attributes) is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to a hash relating menu values to another hash with the attribute's name as the key and the attribute's value as the value.

7 番目(訳注:原文では 6th)の引数 (-attributes) はオプションで、個別の メニュー項目に共通の HTML 属性のいずれかに代入するために提供されます。 メニューの値を属性の名前をキー、属性の値を値とするハッシュに関連付ける ハッシュへのポインタとなります。

When this form is processed, all selected list items will be returned as a list under the parameter name 'list_name'. The values of the selected items can be retrieved with:

このフォームが処理されるとき、選択されたリスト要素はパラメータ名 'list_name' のリストで返されます。 選択された要素の値は以下のようにして取り出すことが出来ます:

      @selected = param('list_name');

関連付けられたチェックボックスのグループの作成¶

   print checkbox_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -default=>['eenie','moe'],
                                -linebreak=>'true',
                                -disabled => ['moe'],
        -labels=>\%labels,
        -attributes=>\%attributes);

   print checkbox_group('group_name',
                                ['eenie','meenie','minie','moe'],
        ['eenie','moe'],'true',\%labels,
        {'moe'=>{'class'=>'red'}});

   HTML3-COMPATIBLE BROWSERS ONLY:

   print checkbox_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -rows=2,-columns=>2);

checkbox_group() は同じ名前によって関連付けられたチェックボックスのリストを 作成します。

Parameters:

1.

The first and second arguments are the checkbox name and values, respectively (-name and -values). As in the popup menu, the second argument should be an array reference. These values are used for the user-readable labels printed next to the checkboxes as well as for the values passed to your script in the query string.

最初と 2 番目の引数はそれぞれ、チェックボックスの名前と値 (-name と -values) です。 ポップアップメニューと同じように、2 番目の引数は配列リファレンスで なければなりません。 これらの値は、チェックボックスの隣に出力されるユーザが読むことが出来る ラベルであり、また問い合わせ文字列でスクリプトに渡される値でもあります。

2.

The optional third argument (-default) can be either a reference to a list containing the values to be checked by default, or can be a single value to checked. If this argument is missing or undefined, then nothing is selected when the list first appears.

3 番目の引数 (-default) はオプションで、デフォルトでチェックされる値が入った リストへのリファレンスか、チェックされる一つの値のどちらかにすることが できます。 この引数がないか、未定義であれば、最初にリストが表示されたときには何も 選択されません。

3.

The optional fourth argument (-linebreak) can be set to true to place line breaks between the checkboxes so that they appear as a vertical list. Otherwise, they will be strung together on a horizontal line.

4 番目の引数 (-linebreak) はオプションで、trueに設定されると垂直なリストで 表示されるようチェックボックスの間に改行をいれます。 そうでなければ水平に一緒になって並べられます。

5 番目の引数はオプションで、チェックボックスの値とチェックボックスの隣に 出力されるユーザに見えるラベルとを関連付けるハッシュへのポインタです。 与えられなければ値 (values) がデフォルトとして使われます。

オプションのパラメータである -rows と -columns は、checkbox_group を 指定された数の行と列で整形されたチェックボックスグループが入った HTML3 互換のテーブルを返させるようにします。 そうしたければ、-columns だけを与えることもできます; check_group は正しい 行数をあなたに代って計算します。

オプションの -disabled はチェックボックスの値の配列を取って、 指定されたものをグレイアウトして無効にします(これは全てのブラウザで 対応しているというわけではないかもしれません)。

オプションの -attributes は、個別のメニュー項目に共通の HTML 属性の いずれかに代入するために提供されます。 メニューの値を属性の名前をキー、属性の値を値とするハッシュに関連付ける ハッシュへのポインタとなります。

オプションの -tabindex 引数は、ユーザがタブボタンを押したときに ラジオボタンがフォーカスを受け取る順序を制御するために使えます。 スカラの数値が渡されると、グループの最初の要素がこのタブインデックスを 受け取り、引き続く要素は 1 ずつ加算されたものになります。 ラジオボタンの値の配列へのリファレンスが渡されると、配列で指定された 順序がタブ順序に対応するようにインデックスが操作されます。 また、ハッシュキーがラジオボタンの値で、値がそれぞれのボタンの タブインデックスであるような配列へのリファレンスも渡せます。 例:

  -tabindex => 100    #  this group starts at index 100 and counts up
  -tabindex => ['moe','minie','eenie','meenie']  # tab in this order
  -tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order

オプションの -labelattributes 引数はそれぞれのボタンを囲む <label> 要素に 付加される要素を指定します。

フォームが処理されるとき、すべてのチェックされたボックスはパラメータ名 'group_name' のリストとして返されます。 "on" の値のチェックボックスは以下のようにして取り出すことが出来ます:

      @turned_on = param('group_name');

checkbox_group() によって返される値は実際にはボタン要素の配列です。 以下のようにして、それらを取得し、テーブル、リストあるいはその他の作成方法で 使うことが出来ます:

    @h = checkbox_group(-name=>'group_name',-values=>\@values);
    &use_in_creative_way(@h);

独立したチェックボックスの作成¶

    print checkbox(-name=>'checkbox_name',
                           -checked=>1,
                           -value=>'ON',
                           -label=>'CLICK ME');

        -or-

    print checkbox('checkbox_name','checked','ON','CLICK ME');

checkbox() は他とは論理的に関連付けられない独立したチェックボックスを 作成するために使われます。

Parameters:

1.

The first parameter is the required name for the checkbox (-name). It will also be used for the user-readable label printed next to the checkbox.

最初のパラメータは必須で、チェックボックスのための名前です (-name)。 それはチェックボックスの隣に出力されるユーザが読むことができるラベルとしても 使われます。

2.

The optional second parameter (-checked) specifies that the checkbox is turned on by default. Synonyms are -selected and -on.

2 番目のパラメータ (-checked) はオプションで、デフォルトでチェックボックスが on とすることを指定します。 同義語は -selected と -on です。

3.

The optional third parameter (-value) specifies the value of the checkbox when it is checked. If not provided, the word "on" is assumed.

3 番目のパラメータ (-value) はチェックされたときのチェックボックスの 値を指定します。 指定されなければ "on" が想定されます。

4.

The optional fourth parameter (-label) is the user-readable label to be attached to the checkbox. If not provided, the checkbox name is used.

4 番目のパラメータ (-label) はチェックボックスにつけられるユーザが 読むことが出来るラベルです。 指定されなければ、チェックボックスの名前が使われます。

チェックボックスの値は以下のようにして取り出すことが出来ます:

    $turned_on = param('checkbox_name');

ラジオボタングループの作成¶

   print radio_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie'],
                             -default=>'meenie',
                             -linebreak=>'true',
           -labels=>\%labels,
           -attributes=>\%attributes);

        -or-

   print radio_group('group_name',['eenie','meenie','minie'],
            'meenie','true',\%labels,\%attributes);


   HTML3-COMPATIBLE BROWSERS ONLY:

   print radio_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -rows=2,-columns=>2);

radio_group() は論理的に関連付けられたラジオボタンのセット (グループの メンバーの一つがオンになると、他はオフになります) を作成します。

Parameters:

1.

The first argument is the name of the group and is required (-name).

最初の引数はグループ名で必須です (-name)。

2.

The second argument (-values) is the list of values for the radio buttons. The values and the labels that appear on the page are identical. Pass an array reference in the second argument, either using an anonymous array, as shown, or by referencing a named array as in "\@foo".

2 番目の引数 (-values) はラジオボタンのための値のリストです。 ページ上で表示される値とラベルはインデントされます。 2 番目の引数には配列リファレンスか、上記に示されたような無名配列、または "\@foo" のような名前付き配列をリファレンスにしたもの渡してください。

3.

The optional third parameter (-default) is the name of the default button to turn on. If not specified, the first item will be the default. You can provide a nonexistent button name, such as "-" to start up with no buttons selected.

3 番目のパラメータ (-default) はオプションで、オンするデフォルトボタンの 名前です。 指定されなければ最初の要素がデフォルトになります。 何もボタンが選択されていない状態で開始するために、"-" のような存在しない ボタン名を指定することが出来ます。

4.

The optional fourth parameter (-linebreak) can be set to 'true' to put line breaks between the buttons, creating a vertical list.

4 番目のパラメータは (-linebreak) オプションで、ボタンの間に改行を入れ、 垂直なリストを作成するために 'true' に設定することが出来ます。

5.

The optional fifth parameter (-labels) is a pointer to an associative array relating the radio button values to user-visible labels to be used in the display. If not provided, the values themselves are displayed.

5 番目のパラメータ (-labels) はオプションで、ラジオボタンの値と表示のときに 使われるユーザに見えるラベルとを関連付けるハッシュへのポインタです。 与えられなければ、値そのものが表示されます。

最近の全てのブラウザはオプションの引数である -rows と -columns の利点を 受けられます。 これらの引数は、radio_group() を、指定された行と列で整形された ラジオグループを含む HTML3 互換のテーブルを返うようにします。 もし望むなら -columns 引数だけを指定することも出来ます; radio_group は 正しい行数を代わりに計算します。

返されるテーブルに行と列のヘッダを入れるために、-rowheaders と -colheaders パラメータを使うことが出来ます。 これらは両方とも使用するヘッダの配列へのポインタを受取ります。 ヘッダは単なる飾りです。 それらはラジオボタンの解析を理解しません -- それらはまだ名前がついた一つの ユニットです。

オプションの -tabindex 引数は、ユーザーがタブボタンを押したときにどの ラジオボタンがフォーカスを受けるかの順番を制御するために使われます。 スカラ数値を渡すと、グループの最初の要素がこのタブインデックスを受けとり、 引き続く要素は 1 インクリメントされます。 ラジオボタンの値の配列へのリファレンスを受け取ると、配列で指定された 順序がタブ順序に対応しているものとしてインデックスが作り出されます。 また、ハッシュのキーがラジオボタンの値でハッシュの値がそれぞれのボタンの タブインデックスであるハッシュへのリファレンスを渡すこともできます。 例:

  -tabindex => 100    #  this group starts at index 100 and counts up
  -tabindex => ['moe','minie','eenie','meenie']  # tab in this order
  -tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order

オプションの -attributes 引数は、個別のメニュー項目に共通の HTML 属性の いずれかに代入するために提供されます。 メニューの値を属性の名前をキー、属性の値を値とするハッシュに関連付ける ハッシュへのポインタとなります。

オプションの -labelattributes 引数は、それぞれのボタンを囲む <label> 要素に付加される属性を指定します。

フォームが処理されるとき、選択されたラジオボタンは以下のようにして 取り出すことが出来ます:

      $which_radio_button = param('group_name');

radio_group() により返される値は実際にはボタン要素の配列です。 以下のようにしてそれらを取得し、テーブル、リストあるいは、その他の作成方法で 使うことが出来ます:

    @h = radio_group(-name=>'group_name',-values=>\@values);
    &use_in_creative_way(@h);

サブミットボタンの作成¶

   print submit(-name=>'button_name',
                        -value=>'value');

        -or-

   print submit('button_name','value');

submit() は問い合わせサブミットボタンを作成します。 すべてのフォームはこれらのいずれかを持たなければいけません。

Parameters:

1.

The first argument (-name) is optional. You can give the button a name if you have several submission buttons in your form and you want to distinguish between them.

最初の引数 (-name) はオプションです。 フォームにたくさんのサブミットボタンを持っていて、それらを区別したければ、 名前を与えることが出来ます。

2.

The second argument (-value) is also optional. This gives the button a value that will be passed to your script in the query string. The name will also be used as the user-visible label.

2 番目の引数 (-value) もオプションです。 これはボタンに問い合わせ文字列でスクリプトに渡される値を与えます。 名前はまたユーザーが目にするラベルとしても使われます。

3.

You can use -label as an alias for -value. I always get confused about which of -name and -value changes the user-visible label on the button.

-label を -value のエイリアスとして使えます。 私は -name と -value のどちらが、ボタン上のユーザーが目にするラベルかで いつも混乱します。

それぞれに異なる値を使うことによりどのボタンが押されたかを見分けることが 出来ます:

     $which_one = param('button_name');

リセットボタンの作成¶

   print reset

reset() は「リセット」ボタンを作成します。 必ずしもデフォルトではなく、最後にスクリプトが呼ばれたときからの値をその フォームに再設定することに注意してください。

これが Perl に組込まれている reset() とぶつかることに注意してください。 元の reset 関数を取得するには CORE::reset() を使ってください。

デフォルトボタンの作成¶

   print defaults('button_label')

defaults() は、呼び出されたとき、フォームを完全にデフォルトにリセットし、 ユーザがそれまで行ったすべての変更を洗い流してしまうボタンを作成します。

隠しフィールドの作成¶

        print hidden(-name=>'hidden_name',
                             -default=>['value1','value2'...]);

                -or-

        print hidden('hidden_name','value1','value2'...);

hidden() はユーザには見えないテキストフィールドを作成します。 これはあるスクリプトの呼び出しから次へ状態変数情報を渡すのに便利です。

Parameters:

1.

The first argument is required and specifies the name of this field (-name).

最初の引数は必須で、このフィールドの名前を指定します (-name)。

2.

The second argument is also required and specifies its value (-default). In the named parameter style of calling, you can provide a single value here or a reference to a whole list

2 番目の引数も必須で、その値を指定します (-default)。 呼び出しの名前付きパラメータ形式では、一つの値またはリスト全体への リファレンスを指定することが出来ます。

隠しフィールドの値は以下のようにして取り出してください:

     $hidden_value = param('hidden_name');

他のすべてのフォーム要素と同じように、隠しフィールドは "sticky" であることに 注意してください。 スクリプトが一度呼び出された後に、何か他の値で隠しフィールドを 置き換えたければ、手動でおこなう必要があります:

     param('hidden_name','new','values','here');

クリッカブルイメージボタンの作成¶

     print image_button(-name=>'button_name',
                                -src=>'/source/URL',
                                -align=>'MIDDLE');      

        -or-

     print image_button('button_name','/source/URL','MIDDLE');

image_button() はクリッカブルなイメージを作成します。 クリックされると、スクリプトへクリックの位置が "bottun_name.x" と "button_name.y" として返されます。 "button_name" のところはそれに指定した名前です。

Parameters:

1.

The first argument (-name) is required and specifies the name of this field.

最初の引数 (-name) は必須で、このフィールドの名前を指定します。

2.

The second argument (-src) is also required and specifies the URL

2 番目の引数(-src) も必須で、URL を指定します。

3.

The third option (-align, optional) is an alignment type, and may be TOP, BOTTOM or MIDDLE

3 番目のオプション(-align, オプションです) はアラインメントのタイプで、 TOP, BOTTOM, MIDDLE を指定することが出来ます。

このボタンの値は以下のようにして取り出してください:

     $x = param('button_name.x');
     $y = param('button_name.y');

JavaScript アクションボタンの作成¶

     print button(-name=>'button_name',
                          -value=>'user visible label',
                          -onClick=>"do_something()");

        -or-

     print button('button_name',"user visible value","do_something()");

button() は type="button" な <input> を生成します。 これが押されると、-onClickパラメータで示される JavaScript のコードが 実行されます。

HTTP クッキー¶

ブラウザは、ブラウザセッションでの状態を保持することを助けるように 設計された、いわゆる「クッキー」をサポートしています。 CGI.pm はクッキーをサポートするさまざまなメソッドを持っています。

クッキーは、CGI 問い合わせ文字列の名前付きパラメータによく似た、名前=値の 組です。 CGI スクリプトは一つまたは複数のクッキーを作り、HTTP ヘッダに入れて ブラウザに送信します。 ブラウザは特定のWebサーバに所属するクッキーのリストを保持し、その後の対話の 間、CGI スクリプトに返します。

必須の名前=値の組に加えて、各クッキーはさまざまなオプションの属性を 持っています:

1. an expiration time

This is a time/date string (in a special GMT format) that indicates when a cookie expires. The cookie will be saved and returned to your script until this expiration date is reached if the user exits the browser and restarts it. If an expiration date isn't specified, the cookie will remain active until the user quits the browser.

これはクッキーの有効期限を示す時刻／日付の文字列 (特別な GMT フォーマットに よる) です。 ユーザがブラウザを終了させ、再起動したならば、 この有効期限が来るまで、クッキーは保存され、スクリプトに返されます。 有効期限が指定されなければ、クッキーはユーザがブラウザを終わらせるまで 有効です。

2. a domain

This is a partial or complete domain name for which the cookie is valid. The browser will return the cookie to any host that matches the partial domain name. For example, if you specify a domain name of ".capricorn.com", then the browser will return the cookie to Web servers running on any of the machines "www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com", etc. Domain names must contain at least two periods to prevent attempts to match on top level domains like ".edu". If no domain is specified, then the browser will only return the cookie to servers on the host the cookie originated from.

これはクッキーが有効であるドメイン名の全体あるいは一部です。 ブラウザはドメイン名の一部がマッチする、すべてのホストにクッキーを 返します。 例えばドメイン名に ".capricorn.com" を指定すれば、ブラウザは "www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com" などの マシンのすべて実行されている Web サーバにクッキーを返します。 ".edu" のように最上位のドメインにマッチしようとすることを防ぐよう、 ドメイン名は少なくとも二つのピリオドが入っていなければなりません。 もしドメインが指定されなければ、ブラウザはクッキーが作成されたホストの サーバにだけクッキーを返します。

3. a path

If you provide a cookie path attribute, the browser will check it against your script's URL before returning the cookie. For example, if you specify the path "/cgi-bin", then the cookie will be returned to each of the scripts "/cgi-bin/tally.pl", "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl", but not to the script "/cgi-private/site_admin.pl". By default, path is set to "/", which causes the cookie to be sent to any CGI script on your site.

クッキークリプトの URL を path 属性を与えると、ブラウザはクッキーを 返す前にあなたのスクリプトの URL をチェックします。 例えばパスを "/cgi-bin" と指定すれば、"/cgi-bin/tally.pl", "/cgi-bin/order.pl", "/cgi-bin/customer_service/complain.pl" のそれぞれの スクリプトには返されますが、"/cgi-private/site_admin.pl'" には返されません。 デフォルトではパスは "/" で、これはあなたのサイトのすべての CGI スクリプトにクッキーが送信させます。

4. a "secure" flag

If the "secure" attribute is set, the cookie will only be sent to your script if the CGI request is occurring on a secure channel, such as SSL.

もし "secure" 属性が設定されると、クッキーは CGI リクエストが SSL のような セキュアなチャンネルで発生された場合にのみ送信されます。

HTTP クッキーへのインタフェースは cookie() メソッドです:

    $cookie = cookie(-name=>'sessionID',
                             -value=>'xyzzy',
                             -expires=>'+1h',
                             -path=>'/cgi-bin/database',
                             -domain=>'.capricorn.org',
                             -secure=>1);
    print header(-cookie=>$cookie);

cookie() は新しいクッキーを作成します。 そのパラメータには以下のものがあります:

-name

The name of the cookie (required). This can be any string at all. Although browsers limit their cookie names to non-whitespace alphanumeric characters, CGI.pm removes this restriction by escaping and unescaping cookies behind the scenes.

クッキーの名前 (必須) 。 これにはどんな文字列でも指定できます。 ブラウザは、そのクッキー名を空白が入らない、英数字に限定しますが、 CGI.pm は背後でクッキーをエスケープ、アンエスケープすることにより、 これらの制限を取り払います。

-value

The value of the cookie. This can be any scalar value, array reference, or even hash reference. For example, you can store an entire hash into a cookie this way:

クッキーの値。 これにはすべてのスカラ値、配列リファレンス、さらに ハッシュリファレンスさえも指定できます。 例えば完全なハッシュをクッキーに以下のようにして格納することが出来ます:

        $cookie=cookie(-name=>'family information',
                               -value=>\%childrens_ages);

-path

The optional partial path for which this cookie will be valid, as described above.

オプションで、上記で説明したようにクッキーが有効になるパスの一部。

-domain

The optional partial domain for which this cookie will be valid, as described above.

オプションで、上記で説明したようにクッキーが有効になるドメインの一部。

-expires

The optional expiration date for this cookie. The format is as described in the section on the header() method:

オプションで、このクッキーの有効期限。 フォーマットは header() メソッドについてのセクションで説明したのと同じ:

        "+1h"  one hour from now

-secure

If set to true, this cookie will only be used within a secure SSL session.

trueに設定されれば、このクッキーは安全な SSL セッションでのみ使われます。

cookie() によって作成されたクッキーは、header() メソッドによって返される 文字列で、HTTP ヘッダの中に入れられなければなりません:

        use CGI ':standard';
        print header(-cookie=>$my_cookie);

複数のクッキーを作成するには、header() に配列リファレンスを指定してください:

        $cookie1 = cookie(-name=>'riddle_name',
                                  -value=>"The Sphynx's Question");
        $cookie2 = cookie(-name=>'answers',
                                  -value=>\%answers);
        print header(-cookie=>[$cookie1,$cookie2]);

クッキーを取り出すには、cookie() メソッドを -value パラメータなしで 呼び出すことによって名前で要求します:

        use CGI;
        $query = CGI->new;
        $riddle = $query->cookie('riddle_name');
        %answers = $query->cookie('answers');

"riddle_name" クッキーのように、一つのスカラーの値で作成されたクッキーは、 その形で帰されます。 配列やハッシュを持っているクッキーも取り出すことが出来ます。

クッキーと CGI 名前空間は分かれています。 もし 'answers' という名前のパラメータと 'answers' という名前のクッキーを 持っていれば、param() と cookie() によって取り出される値はそれぞれ 独立しています。 しかしながら、CGI パラメータをクッキーにしたり、その逆も簡単です:

   # turn a CGI parameter into a cookie
   $c=cookie(-name=>'answers',-value=>[param('answers')]);
   # vice-versa
   param(-name=>'answers',-value=>[cookie('answers')]);

引数なしで cookie() を呼び出すと、スクリプトに渡された全てのクッキーの 名前のリストが返されます:

  @cookies = cookie();

クッキーをどのように効率よく使うかについての、いくつかのアイデアに ついては、例のスクリプト cookie.cgi をご覧下さい。

フレームの利用¶

CGI.pm スクリプトでは HTML4 フレーム機能を使って、たくさんのブラウザパネルと ウィンドウに書き込むことができます。 プログラム的に新しいフレームを定義するためには三つのテクニックがあります:

1. Create a <Frameset> document

After writing out the HTTP header, instead of creating a standard HTML document using the start_html() call, create a <frameset> document that defines the frames on the page. Specify your script(s) (with appropriate parameters) as the SRC for each of the frames.

HTTP ヘッダを出力した後、start_html() 呼び出しを使って標準の HTML ドキュメントを作成する代りに、ページにフレームを定義する <frameset> ドキュメントを作成します。 各フレームの SRC としてスクリプトを (適切なパラメータをつけて) 指定します。

There is no specific support for creating <frameset> sections in CGI.pm, but the HTML is very simple to write.

CGI.pm には <frameset> セクションを作成するのに特別なサポートはありません。 しかし HTML はとても簡単に書けます。

2. Specify the destination for the document in the HTTP header

You may provide a -target parameter to the header() method:

header() に -target を指定することが出来ます:

    print header(-target=>'ResultsWindow');

This will tell the browser to load the output of your script into the frame named "ResultsWindow". If a frame of that name doesn't already exist, the browser will pop up a new window and load your script's document into that. There are a number of magic names that you can use for targets. See the HTML <frame> documentation for details.

これはブラウザにスクリプトの出力を "ResultsWindow" という名前の フレームにロードするように伝えます。 もしその名前のフレームがなければ、ブラウザは新しいウィンドウを立ち上げ、 それにスクリプトのドキュメントをロードします。 ターゲットに使うことが出来る特別な名前がたくさんあります。

3. Specify the destination for the document in the <form> tag

You can specify the frame to load in the FORM tag itself. With CGI.pm it looks like this:

FORM タグそれ自身にロードするフレームを指定することが出来ます。 CGI.pm では以下のようになります:

    print start_form(-target=>'ResultsWindow');

When your script is reinvoked by the form, its output will be loaded into the frame named "ResultsWindow". If one doesn't already exist a new window will be created.

フォームによりスクリプトが再び呼び出されると、その出力は "ResultsWindow" という名前のフレームにロードされます。 それがまだなければ新しいウィンドウが作成されます。

examples ディレクトリにあるスクリプト "frameset.cgi" は、フォームと レスポンスが隣り合ったフレームに存在するページを作成する一つの方法を 示しています。

JavaScript 対応¶

JavaScript を使う通常の方法は、HTML ヘッダの <SCRIPT> ブロックに関数を 定義して、そのページの様々な要素にイベントハンドラを登録するというものです。 イベントにはマウスがフォーム要素の上を通過する、ボタンがクリックされる、 テキストフィールドの内容が経こうされる、フォームが投稿される、といった ものです。 イベントハンドラが登録された要素に関係するイベントが発生すると、 関連づけられた JavaScript コードが呼び出されます。

イベントハンドラを登録できる要素には、HTML 文書の <BODY>、 ハイパーテキストリンク、フォームの様々な要素全て、およびフォーム自身を 含みます。 たくさんのイベントがあり、それぞれは適切な要素に対してのみ適用されます。 以下は部分的なリストです:

onLoad

The browser is loading the current document. Valid in:

ブラウザは現在のドキュメントを読み込んでいます。有効なのは:

     + The HTML <BODY> section only.

onUnload

The browser is closing the current page or frame. Valid for:

ブラウザは現在のページ又はフレームを閉じようとしています。有効なのは:

     + The HTML <BODY> section only.

onSubmit

The user has pressed the submit button of a form. This event happens just before the form is submitted, and your function can return a value of false in order to abort the submission. Valid for:

ユーザーがフォームの送信ボタンを押しました。 このイベントはフォームが送信される直前に起こり、送信を中断するために 偽の値を返すこともできます。 有効なのは:

     + Forms only.

onClick

The mouse has clicked on an item in a fill-out form. Valid for:

入力フォーjむのアイテムがクリックされました。 有効なのは:

     + Buttons (including submit, reset, and image buttons)
     + Checkboxes
     + Radio buttons

onChange

The user has changed the contents of a field. Valid for:

ユーザーがフィールドの内容を変更しました。 有効なのは:

     + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists

onFocus

The user has selected a field to work with. Valid for:

ユーザーがフィールドを選択しました。 有効なのは:

     + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists

onBlur

The user has deselected a field (gone to work somewhere else). Valid for:

ユーザーがフィールドから離れました(ほかのものを選択しました)。 有効なのは:

     + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists

onSelect

The user has changed the part of a text field that is selected. Valid for:

ユーザーが選択していたテキストフィールドの一部を変更しました。 有効なのは:

     + Text fields
     + Text areas
     + Password fields
     + File fields

onMouseOver

The mouse has moved over an element.

マウスが要素の上に移動しました。

     + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists

onMouseOut

The mouse has moved off an element.

マウスが要素から外れました。

     + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists

HTML 要素に JavaScript イベントハンドラを登録するには、対応する CGI メソッドを呼び出すときに単にイベント名を引数として渡します。 例えば、"age" という名前のテキストフィールドが変更される度に実行される validateAge() JavaScript コードがある場合、フィールドを以下のようにして 生成します:

 print textfield(-name=>'age',-onChange=>"validateAge(this)");

この例は、関連する <SCRIPT> ブロックで既に validateAge() 関数を 宣言していることをｋていしています。 CGI.pm の start_html() メソッドはこの節を作るための便利な方法を提供します。

同様に、以下のようにして、一貫性をチェックして、なんらかの重要な値が 欠けているときにはユーザーに警告するフォームを作れます:

  print start_form(-onSubmit=>"validateMe(this)");

これら全てがどのように働くかの例については javascript.cgi スクリプトを 参照してください。

カスケーディングスタイルシートの限定サポート¶

CGI.pm は HTML3 のカスケーディングスタイルシート (css) を限定付きで サポートします。 スタイルシートをドキュメントに組込むためには、start_html() メソッドに -style パラメータを渡します。 このパラメータの値にはスカラー(この場合はスタイルシートのソース URL です) あるいはハッシュリファレンスを指定することが出来ます。 後者の場合は、一つあるいは複数の -src または -code を持ったハッシュを 指定しなければいけません。 -src は完全に定義されたスタイルシートを見つけることが出来る URL を 示します。 -code は <style> セクションに組込まれるスカラー値を示します。 -code でのスタイルの定義は、-src での同じ名前のもので上書きされます。 これゆえに名前が "cascading" (滝のように落ちる) なのです。

-style によって示されるハッシュに、オプションの -type を 加えることによりスタイルシートの種類を指定することも出来ます。 もし指定されなければ、そのスタイルはデフォルトの 'text/css' です。

ドキュメントの本体 (Body) でスタイルを参照するためには、HTML要素に -class を加えます:

    print h1({-class=>'Fancy'},'Welcome to the Party');

あるいは、その場で -style パラメータでスタイルを定義します:

    print h1({-style=>'Color: red;'},'Welcome to Hell');

テキストのセクションにスタイルを適用するため、新しい span() を 使うことも出来ます:

    print span({-style=>'Color: red;'},
               h1('Welcome to Hell'),
               "Where did that handbasket get to?"
               );

span() メソッドを使えるようにするためには ":html3" をインポートしなければ いけないことに注意してください。 CSS 使用の簡単で汚い例を以下に示します。 さらなる詳細は http://www.w3.org/Style/CSS/ にあるCSSの仕様を ご覧下さい。

    use CGI qw/:standard :html3/;

    #here's a stylesheet incorporated directly into the page
    $newStyle=<<END;
    <!-- 
    P.Tip {
        margin-right: 50pt;
        margin-left: 50pt;
        color: red;
    }
    P.Alert {
        font-size: 30pt;
        font-family: sans-serif;
      color: red;
    }
    -->
    END
    print header();
    print start_html( -title=>'CGI with Style',
                      -style=>{-src=>'http://www.capricorn.com/style/st1.css',
                               -code=>$newStyle}
                     );
    print h1('CGI with Style'),
          p({-class=>'Tip'},
            "Better read the cascading style sheet spec before playing with this!"),
          span({-style=>'color: magenta'},
               "Look Mom, no hands!",
               p(),
               "Whooo wee!"
               );
    print end_html;

ドキュメントに複数のスタイルシートを組み込むためには -code か -src に 配列リファレンスを渡してください。

ヘッダに任意のフォーマッティングを含めるそのままのスタイルシートを 組み込みたい場合、以下のように、-style ハッシュに -verbatim タグを渡せます:

 print start_html (-style  =>  {-verbatim => '@import url("/server-common/css/'.$cssFile.'");',
                  -src    =>  '/server-common/css/core.css'});

これは、以下のものを含む HTML ヘッダを生成します:

 <link rel="stylesheet" type="text/css"  href="/server-common/css/core.css">
   <style type="text/css">
   @import url("/server-common/css/main.css");
   </style>

-style に渡される追加引数は <link> タグと関連づけられます。 例えば:

 start_html(-style=>{-src=>['/styles/print.css','/styles/layout.css'],
                          -media => 'all'});

これは以下のようになります:

 <link rel="stylesheet" type="text/css" href="/styles/print.css" media="all"/>
 <link rel="stylesheet" type="text/css" href="/styles/layout.css" media="all"/>

<p>

より複雑な <link> タグを作るには、以下のように、Link() 関数を使って、 それを start_html() の -head 引数として渡してください:

  @h = (Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/ss.css',-media=>'all'}),
        Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/fred.css',-media=>'paper'}));
  print start_html({-head=>\@h})

主スタイルシートと「代替」スタイルシートを作るには、-alternate オプションを 使います:

 start_html(-style=>{-src=>[
                           {-src=>'/styles/print.css'},
                           {-src=>'/styles/alt.css',-alternate=>1}
                           ]
                    });

デバッグ¶

コマンドラインからスクリプトを実行するか、perl デバッガのなかで 実行するならば、キーワードのリストやパラメータ=値の組をコマンド行や 標準入力からスクリプトに渡すことが出来ます (環境変数からスクリプトに 読み込むような仕組みについて心配する必要はありません) 。 キーワードを以下のようにして渡すことが出来ます:

    your_script.pl keyword1 keyword2 keyword3

あるいは:

   your_script.pl keyword1+keyword2+keyword3

あるいは:

    your_script.pl name1=value1 name2=value2

あるいは:

    your_script.pl name1=value1&name2=value2

この機能を無効にするには、-no_debug プラグマを使ってください。

POST メソッドをテストするために、-debug プラグマでフルのデバッグを 可能にすることができます。 これは改行で区切った名前=値の組み合わせを標準入力からスクリプトに 食わせることができます。

デバッグのとき、よく知っているシェルのマナーで、文字をエスケープするために クォートとバックスラッシュを使うことが出来ます。 パラメータ=値の組で、空白や他の変わった文字を置かせるためには 以下のようにします:

   your_script.pl "name1='I am a long value'" "name2=two\ words"

最後に、最初の名前=値の組の前にパスと疑問符 (?) をつけることで、スクリプトに パス情報をセットできます。

    your_script.pl /your/path/here?name1=value1&name2=value2

すべての名前／値の組み合わせをダンプする方法¶

Dump() メソッドはすべての問い合わせの名前／組が入った、ネストした リストとしてきれいに整形されたされた文字列を作成します。 こればデバッグの目的には有効です:

    print Dump

これは以下のようなものを作成します:

    <ul>
    <li>name1
        <ul>
        <li>value1
        <li>value2
        </ul>
    <li>name2
        <ul>
        <li>value1
        </ul>
    </ul>

ショートカットとして、完全な CGI オブジェクトを文字列に入れることが 出来ます。 そしてそれは上記に示されるきれいな HTML ダンプで置きかえられます:

    $query=CGI->new;
    print "<h2>Current Values</h2> $query\n";

環境変数の取り出し¶

いくつかのより便利な環境変数がこのインターフェースを通して取り出すことが 出来ます。 メソッドを以下に示します:

Accept()

Return a list of MIME types that the remote browser accepts. If you give this method a single argument corresponding to a MIME type, as in Accept('text/html'), it will return a floating point value corresponding to the browser's preference for this type from 0.0 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's accept list are handled correctly.

リモートのブラウザが受取るMIMEタイプのリストを返します。 Accept('text/html') のように、もしこのメソッドに MIME タイプに 対応する一つの引数を渡せば、このタイプについてのブラウザの優先順位に 対応する 0.0 (欲しくありません) から 1.0 までの浮動小数点値を返します。 ブラウザの受取リストでの Glob 型(例えば text/*)は正確に扱われます。

Note that the capitalization changed between version 2.43 and 2.44 in order to avoid conflict with Perl's accept() function.

Perl の accept() 関数とぶつかることを避けるために、2.43 と 2.44 の間で 先頭文字が大文字に変更されたことに注意してください。

raw_cookie()

Returns the HTTP_COOKIE variable. Cookies have a special format, and this method call just returns the raw form (?cookie dough). See cookie() for ways of setting and retrieving cooked cookies.

HTTP_COOKIE 変数を返します。 クッキーは特別なフォーマットを持っており、このメソッドは単にそのままの形式を 返します (いわばクッキーのタネ？) 。 調理されたクッキーを設定し、取得する方法については、cookie() をご覧下さい。

Called with no parameters, raw_cookie() returns the packed cookie structure. You can separate it into individual cookies by splitting on the character sequence "; ". Called with the name of a cookie, retrieves the unescaped form of the cookie. You can use the regular cookie() method to get the names, or use the raw_fetch() method from the CGI::Cookie module.

パラメータなしで呼ばれると、raw_cookie() はパックされたクッキー構造体を 返します。 ";" の文字並びで分割(split)することにより、ここのクッキーに分けることが 出来ます。 クッキーの名前をつけて呼び出すと、クッキーの エスケープされていない 形式を 取り出します。 名前を取得するために、通常の cookie() メソッドを使ったり、 CGI::Cookie モジュールからの raw_fetch メソッドを使うことが出来ます。

user_agent()

Returns the HTTP_USER_AGENT variable. If you give this method a single argument, it will attempt to pattern match on it, allowing you to do something like user_agent(Mozilla);

HTTP_USER_AGENT 変数を返します。 このメソッドに一つの引数を与えると、それにパターンマッチを試み、 user_agent(netscape); のようなことを行うことを可能にします。

path_info()

Returns additional path information from the script URL. E.G. fetching /cgi-bin/your_script/additional/stuff will result in path_info() returning "/additional/stuff".

スクリプトからの追加パス情報を返します。 例えば /cgi-bin/your_script/additional/stuff を取り出すと、path_info() は 結果として "addtional/stuff" を返します。

NOTE: The Microsoft Internet Information Server is broken with respect to additional path information. If you use the Perl DLL library, the IIS server will attempt to execute the additional path information as a Perl script. If you use the ordinary file associations mapping, the path information will be present in the environment, but incorrect. The best thing to do is to avoid using additional path information in CGI scripts destined for use with IIS.

注意: Microsoft Internet Information Server は追加のパス情報の見方で おかしくなっています。 Perl DLL ライブラリを使うと、IIS サーバは Perl スクリプトとして 追加パス情報を実行しようとします。 もし通常のファイル関連マッピングを使えば、パス情報は環境変数に表れますが 正しくありません。 これをおこなう一番よいことは、IIS で使用するような CGI では追加パス情報を 使うことを避けることです。

path_translated()

As per path_info() but returns the additional path information translated into a physical path, e.g. "/usr/local/etc/httpd/htdocs/additional/stuff".

path_info() と同様、しかし追加パス情報を物理パス情報に変換します。 例えば "/usr/local/etc/httpd/htdocs/addtional/stuff" 。

The Microsoft IIS is broken with respect to the translated path as well.

変換されたパスについても Microsoft IIS はイカレています。

remote_host()

Returns either the remote host name or IP address. if the former is unavailable.

リモートホスト名または、もし前者が使えなければ IP アドレスのどちらかを 返します。

remote_addr()

Returns the remote host IP address, or 127.0.0.1 if the address is unavailable.

リモートホストの IP アドレスか、あるいはアドレスが利用不能の場合は 127.0.0.1 を返します。

script_name()

Return the script name as a partial URL, for self-refering scripts.

自分を参照するスクリプトのため、URL の一部としてスクリプト名を返します。

referer()

Return the URL of the page the browser was viewing prior to fetching your script. Not available for all browsers.

ブラウザがスクリプトを取り出す前に見ていたページの URL を返します。 すべてのブラウザに利用できるわけではありません。

auth_type ()

Return the authorization/verification method in use for this script, if any.

もしあれば、このスクリプトのために使われた、 authorization/verification (認証/検証) 方法を返します。

server_name ()

Returns the name of the server, usually the machine's host name.

サーバの名前、通常はマシンのホスト名を返します。

virtual_host ()

When using virtual hosts, returns the name of the host that the browser attempted to contact

バーチャルホストを使っているとき、ブラウザがコンタクトしようとしたホストの 名前を返します。

server_port ()

Return the port that the server is listening on.

サーバソフトウェアとバージョン番号を返します。

virtual_port ()

Like server_port() except that it takes virtual hosts into account. Use this when running with virtual hosts.

server_port() と似ていますが、これは仮想ホストも考慮に入れます。 仮想ホストで実行しているときに使ってください。

server_software ()

Returns the server software and version number.

サーバソフトウェアとバージョン番号を返します。

remote_user ()

Return the authorization/verification name used for user verification, if this script is protected.

このスクリプトが保護されていれば、ユーザ検証に使われた authorization/verification 名を返します。

user_name ()

Attempt to obtain the remote user's name, using a variety of different techniques. This only works with older browsers such as Mosaic. Newer browsers do not report the user name for privacy reasons!

さまざまな異なる技術を使ってリモートユーザの名前を取得しようとします。 これは Mosaic のような古いブラウザでのみ機能します。 新しいブラウザはプライバシーの理由からユーザ名を報告しません!

request_method()

Returns the method used to access your script, usually one of 'POST', 'GET' or 'HEAD'.

スクリプトにアクセスするために使われたメソッドを返します。 通常は 'POST', 'GET', 'HEAD' のどれかです。

content_type()

Returns the content_type of data submitted in a POST, generally multipart/form-data or application/x-www-form-urlencoded

POST で送信されてきたデータの content_type を返します。 一般には multipart/form-data または application/x-www-form-urlencoded です。

http()

Called with no arguments returns the list of HTTP environment variables, including such things as HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the like-named HTTP header fields in the request. Called with the name of an HTTP header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.

引数なしで呼ばれると、それぞれリクエストでの似たような HTTP ヘッダフィールドに対応する、HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE, HTTP_ACCEPT_CHARSET のようなものが入った環境変数のリストを返します。 HTTP ヘッダフィールドの名前付きで呼ばれると、その値を返します。 大文字／小文字、アンダースコアの代わりにハイフンを使うことは区別されません。

For example, all three of these examples are equivalent:

例えば、この三つの例はすべて同値です:

   $requested_language = http('Accept-language');
   $requested_language = http('Accept_language');
   $requested_language = http('HTTP_ACCEPT_LANGUAGE');

https()

The same as http(), but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.

http() と同じ。 しかし SSL プロトコルが有効なときに現れる HTTPS 環境変数を扱います。 SSL がオンになっているかどうかを判定するためにも使うことができます。

NPHスクリプトの使い方¶

NPH または"解析されないヘッダ"("no-parsed-header")、では、完全な HTTP ヘッダを直接ブラウザに送信することにより、スクリプトはサーバを 完全にバイパスします。 これはパフォーマンスの面で少し利点があります。 しかしほとんどは、サーバプッシュや PICS ヘッダのような、サーバによって 直接にはサポートされていない HTTP 拡張の利点を得るために使われます。

CGI スクリプトを NPH として示すため、さまざまな約束が使われます。 多くの Unix サーバはスクリプトの名前の始まりに接頭辞 "nph-" があるかを 見ます。 これに対して Macintosh WebSTAR サーバと Microsoft の Internet Information Server は、スクリプト出力の先頭行をチェックする ことにより NPH スクリプトであるかを判定しようとします。

CGI.pm は特別は NPH モードで NPH スクリプトをサポートします。 このモードでは CGI.pm は header() や redirect() メソッドが呼ばれると 必要となる特殊なヘッダ情報を出力します。

Microsoft Internet Information Server は NPH モードを必要とします。 version 2.30 では、CGI.pm は IIS の元で実行されたとき自動的に検知し、 自分自身でこのモードにします。 手動でこのモードにする必要はありません。 しかしそうしたからといって、何も問題はありません。 しかしながらサービスパック 6 を提供しているのであれば、注意してください。 クッキーが設定されている間、リダイレクトするという機能も含めて、 NPH スクリプトの機能の多くが Microsoft からの特別なパッチなしには IIS では まったく機能しません。 この URL をご覧ください http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP: Non-Parsed Headers Stripped From CGI Applications That Have nph- Prefix in Name. (名前が nph- で始まらない CGI アプリケーションからの 解析されないヘッダの除去)

In the use statement

Simply add the "-nph" pragmato the list of symbols to be imported into your script:

スクリプトにインポートされるシンボルのリストに単に "-nph" プラグマを 追加してください:

      use CGI qw(:standard -nph)

By calling the nph() method:

Call nph() with a non-zero parameter at any point after using CGI.pm in your program.

CGI.pm をプログラムで使った後のどこかの時点で、非 0 のパラメータで nph() を呼び出してください。

      CGI->nph(1)

By using -nph parameters

in the header() and redirect() statements:

header() と redirect() 文で:

      print header(-nph=>1);

サーバープッシュ¶

CGI.pm は、サーバプッシュを実装するために必要な種類である マルチパートドキュメントを作成するために簡単な4つの関数を提供しています。 これらの関数はありがたいことに Ed Jordan <ed@fidalgo.net> によって 提供されました。 これらを名前空間にインポートするためには、":push" セットを インポートしなければいけません。 またスクリプトをNPH モードとし、バッファリングの問題を避けるために $| を 1 に設定したほうがよいでしょう。

サーバプッシュをデモンストレーションする簡単なスクリプトを以下に示します:

  #!/usr/local/bin/perl
  use CGI qw/:push -nph/;
  $| = 1;
  print multipart_init(-boundary=>'----here we go!');
  for (0 .. 4) {
      print multipart_start(-type=>'text/plain'),
            "The current time is ",scalar(localtime),"\n";
      if ($_ < 4) {
              print multipart_end;
      } else {
              print multipart_final;
      }
      sleep 1;
  }

このスクリプトは multipart_init() を呼ぶことによってサーバプッシュを 初期化しています。 そして multipart_start() を呼ぶことによって新しい マルチパートセクションを始め、現在のローカルタイムを出力し、 multipart_end() でマルチパートセクションを終わらせているループに 入ります。 そして 1 秒スリープした後、再び開始します。 最後の繰り返しでは multipart_end() ではなく multipart_final() で マルチパートセクションを終了させています。

multipart_init()

  multipart_init(-boundary=>$boundary);

Initialize the multipart system. The -boundary argument specifies what MIME boundary string to use to separate parts of the document. If not provided, CGI.pm chooses a reasonable boundary for you.

マルチパートシステムを初期化します。 -boundary 引数はドキュメントの部分を分割するために使われる MIME バウンダリ文字列を指定します。 指定されなければ、CGI.pm はあなたに代わって合理的なバウンダリを選択します。

multipart_start()

  multipart_start(-type=>$type)

Start a new part of the multipart document using the specified MIME type. If not specified, text/html is assumed.

指定された MIME タイプを使ってマルチパートドキュメントの新しい部分を 開始します。 指定されなければ、text/html が想定されます。

multipart_end()

  multipart_end()

End a part. You must remember to call multipart_end() once for each multipart_start(), except at the end of the last part of the multipart document when multipart_final() should be called instead of multipart_end().

部分(part)を終わらせます。 multipart_end() の代わりに multipart_final() を呼ばなければならない マルチパートドキュメントの最後の部分の終わりを除いて、 multipart_start() を呼ぶ毎に multpart_end() を呼ぶ事を忘れてはいけません。

multipart_final()

  multipart_final()

End all parts. You should call multipart_final() rather than multipart_end() at the end of the last part of the multipart document.

全ての部分を終了させます。 マルチパートドキュメントの最後の部分の終了のときには multipart_end() ではなく、multipart_final() を呼ばなければなりません。

サーバプッシュアプリケーションに興味のあるユーザは CGI::Push モジュールも 見るべきです。

サービス不能(DoS)攻撃の回避¶

CGI.pm での潜在的な問題は、デフォルトでは POST されたフォームが どんなに大きくても処理しようとすることです。 ずるがしこいハッカーは数メガバイトの巨大な POST を CGI スクリプトに 送信することにより、あたなのサイトを攻撃することが出来ます。 CGI.pm は POST 全体を変数に読み込もうとし、メモリがなくなるまで、 その大きさは巨大に成長します。 スクリプトがメモリを占有しようとする間、システムは劇的に遅くなるかも しれません。 これがサービス不能(DoS)攻撃の形です。

他の可能な攻撃はリモードユーザが CGI.pm に巨大なファイルのアップロードを 受け取ることを強要することです。 CGI.pm は、例えあなたのスクリプトがアップロードされるファイルを受けることを 予想していなくても、アップロードを受けつけ、それを一時ディレクトリに 格納しようとします。 CGI.pm はそれが終わったとき、自動的にファイルを削除しますが、その間に リモートユーザがサーバのディスク空間をいっぱいにして、他の問題を 起こしてしまうかもしれません。

サービス不能攻撃を避ける一番よい方法は、CGI スクリプトが使うことが できるメモリ量、CPU 時間、ディスク容量を制限することです。 いつくかの Web サーバはこれを実現する組込み機能を持っています。 その他の場合、シェルの limit または ulimit を CGI の資源使用に上限を設定ために使うことが出来ます。

CGI.pm もサービス不能攻撃に対するいくかの簡単な組込まれた保護を 持っていますが、使えるようにするには有効にしなければなりません。 これらは CGI 名前空間での二つのグローバル変数の形を取ります:

$CGI::POST_MAX

If set to a non-negative integer, this variable puts a ceiling on the size of POSTings, in bytes. If CGI.pm detects a POST that is greater than the ceiling, it will immediately exit with an error message. This value will affect both ordinary POSTs and multipart POSTs, meaning that it limits the maximum size of file uploads as well. You should set this to a reasonably high value, such as 1 megabyte.

負でない整数が設定されると、この変数は POST されるサイズの上限をバイト数で 設定します。 CGI.pm は上限よりも大きい POST を検知すると、エラーメッセージとともにすぐに exit します。 この値は通常の POST とマルチパート POST の両方に影響を与えます。 つまりファイルアップロードの最大の大きさも制限するということです。 これは 1 メガバイトのように合理的に大きい値を設定しなければいけません。

$CGI::DISABLE_UPLOADS

If set to a non-zero value, this will disable file uploads completely. Other fill-out form values will work as usual.

非 0 の値が設定されると、これはファイルのアップロードを完全に 不可能にします。 他のフォームの値は通常通り機能します。

これらの変数を以下の二つの方法のどちらかで使うことが出来ます:

1. On a script-by-script basis

(スクリプト毎に)

Set the variable at the top of the script, right after the "use" statement:

"use" 文のすぐ後に、スクリプトの先頭でその変数を設定します:

    use CGI qw/:standard/;
    use CGI::Carp 'fatalsToBrowser';
    $CGI::POST_MAX=1024 * 100;  # max 100K posts
    $CGI::DISABLE_UPLOADS = 1;  # no uploads

2. Globally for all scripts

(全てのスクリプトに対してグローバルに)

Open up CGI.pm, find the definitions for $POST_MAX and $DISABLE_UPLOADS, and set them to the desired values. You'll find them towards the top of the file in a subroutine named initialize_globals().

CGI.pm を開き $POST_MAX と $DISABLE_UPLOADS のための定義を見つけ、 それを望んでいる値に設定します。 ファイルの先頭の近くinitialize_globals() という名前のサブルーチンの中で 見つけるでしょう。

$POST_MAX バイトよりも大きな POST を送信しようとすると param() は 空の CGI パラメータを返します。 このイベントは CGI オブジェクトを作成した後もしくは関数指向インターフェースを 使っていれば最初に param() を呼び出した後に、cgi_error() を チェックすることで調べることができます。 もし POST が中断されていれば、cgi_error() は "413 POST too large" というメッセージを返します。

このエラーメッセージは実際には HTTP プロトコルで定義されており、 そして CGI スクリプトのステータスコードとしてブラウザに返されるように なっています。 例えば:

   $uploaded_file = param('upload');
   if (!$uploaded_file && cgi_error()) {
      print header(-status=>cgi_error());
      exit 0;
   }

しかしながら、すべてのブラウザが現在のところ、このステータスで何を すべきか分かっているかははっきりしません。 問題のユーザに警告する HTML ページを作るだけの方がよいかもしれません。

cgi-lib.pl との互換性¶

cgi-lib.pl を使っている既にあるプログラムの移植を簡単にするため、 互換性ルーチン "ReadParse" が提供されています。 移植は簡単です:

旧バージョン

    require "cgi-lib.pl";
    &ReadParse;
    print "The value of the antique is $in{antique}.\n";

新バージョン

    use CGI;
    CGI::ReadParse();
    print "The value of the antique is $in{antique}.\n";

CGI.pm の ReadParse() ルーチンは %in という名前の tie された変数を作成します。 それは問い合わせ変数を取得するためにアクセスされます。 ReadParse のように独自の変数を提供することも出来ます。 @in と $in 変数の作成のように、ReadParse のあまり頻繁には使われない機能は サポートされていません。

一度 ReadParse を使えば、以下のように問い合わせオブジェクトそれ自身を 取り出すことが出来ます:

    $q = $in{CGI};
    print textfield(-name=>'wow',
                        -value=>'does this really work?');

これにより、古いスクリプトを頭から書きなおすことなく、CGI.pm のより興味深い 機能を使い始めることが出来ます。

AUTHOR INFORMATION¶

The CGI.pm distribution is copyright 1995-2007, Lincoln D. Stein. It is distributed under GPL and the Artistic License 2.0.

バグレポートとコメントはこちらへ: lstein@cshl.org 。 バグレポートを送るときには CGI.pm のバージョン、Perl のバージョン、 Web サーバの名前とバージョン、そして使用しているオペレーティングシステムの 名前とバージョンを教えてください。 もし問題が離れた場所にあるブラウザにさえも依存していれば、影響される ブラウザについての情報を教えてください。

CREDITS¶

以下の方々に感謝します:

Matt Heffron (heffron@falstaff.css.beckman.com)

James Taylor (james.taylor@srs.gov)

Scott Anguish <sanguish@digifix.com>

Mike Jewell (mlj3u@virginia.edu)

Timothy Shimmin (tes@kbs.citri.edu.au)

Joergen Haegg (jh@axis.se)

Laurent Delfosse (delfosse@delfosse.com)

Richard Resnick (applepi1@aol.com)

Craig Bishop (csb@barwonwater.vic.gov.au)

Tony Curtis (tc@vcpc.univie.ac.at)

Tim Bunce (Tim.Bunce@ig.co.uk)

Tom Christiansen (tchrist@convex.com)

Andreas Koenig (k@franz.ww.TU-Berlin.DE)

Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)

Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)

Stephen Dahmen (joyfire@inxpress.net)

Ed Jordan (ed@fidalgo.net)

David Alan Pisoni (david@cnation.com)

Doug MacEachern (dougm@opengroup.org)

Robin Houston (robin@oneworld.org)

...and many many more...

(…そしてもっともっとたくさんの人々…)

for suggestions and bug fixes.

提案とバグ修正をしてくれました。

単純なフォームベースのスクリプトの完全な例¶

        #!/usr/local/bin/perl

        use CGI ':standard';

        print header;
        print start_html("Example CGI.pm Form");
        print "<h1> Example CGI.pm Form</h1>\n";
        print_prompt();
        do_work();
        print_tail();
        print end_html;

        sub print_prompt {
           print start_form;
           print "<em>What's your name?</em><br>";
           print textfield('name');
           print checkbox('Not my real name');

           print "<p><em>Where can you find English Sparrows?</em><br>";
           print checkbox_group(
                                 -name=>'Sparrow locations',
                                 -values=>[England,France,Spain,Asia,Hoboken],
                                 -linebreak=>'yes',
                                 -defaults=>[England,Asia]);

           print "<p><em>How far can they fly?</em><br>",
                radio_group(
                        -name=>'how far',
                        -values=>['10 ft','1 mile','10 miles','real far'],
                        -default=>'1 mile');

           print "<p><em>What's your favorite color?</em>  ";
           print popup_menu(-name=>'Color',
                                    -values=>['black','brown','red','yellow'],
                                    -default=>'red');

           print hidden('Reference','Monty Python and the Holy Grail');

           print "<p><em>What have you got there?</em><br>";
           print scrolling_list(
                         -name=>'possessions',
                         -values=>['A Coconut','A Grail','An Icon',
                                   'A Sword','A Ticket'],
                         -size=>5,
                         -multiple=>'true');

           print "<p><em>Any parting comments?</em><br>";
           print textarea(-name=>'Comments',
                                  -rows=>10,
                                  -columns=>50);

           print "<p>",reset;
           print submit('Action','Shout');
           print submit('Action','Scream');
           print end_form;
           print "<hr>\n";
        }

        sub do_work {

           print "<h2>Here are the current settings in this form</h2>";

           for my $key (param) {
              print "<strong>$key</strong> -> ";
              my @values = param($key);
              print join(", ",@values),"<br>\n";
          }
        }

        sub print_tail {
           print <<END;
        <hr>
        <address>Lincoln D. Stein</address><br>
        <a href="/">Home Page</a>
        END
        }

バグ¶

どうか報告してください。

SEE ALSO¶

CGI::Carp - CGI 環境用に仕立てられた Carp 実装を提供します。

CGI::Fast - CGI アプリケーションを FastCGI で動作させることをサポートします。

CGI::Pretty - CGI.pm で生成された HTML を (速度を犠牲にして) 整形します。

POD ERRORS¶

Hey! The above document had some coding errors, which are explained below:

Around line 2673:

Expected text after =item, not a number

Around line 2683:

Expected text after =item, not a number

Around line 2693:

Expected text after =item, not a number

Around line 3926:

Expected text after =item, not a number

Around line 3936:

Expected text after =item, not a number

Around line 3948:

Expected text after =item, not a number

Around line 3960:

Expected text after =item, not a number

Around line 4085:

Expected text after =item, not a number

Around line 4095:

Expected text after =item, not a number

Around line 4124:

Expected text after =item, not a number

Around line 4136:

Expected text after =item, not a number

Around line 4830:

Expected text after =item, not a number

Around line 4844:

Expected text after =item, not a number

Around line 4865:

Expected text after =item, not a number

Around line 4875:

Expected text after =item, not a number

Around line 4889:

Expected text after =item, not a number

Around line 4903:

Expected text after =item, not a number

Around line 4974:

Expected text after =item, not a number

Around line 4993:

Expected text after =item, not a number

Around line 5010:

Expected text after =item, not a number

Around line 5175:

Expected text after =item, not a number

Around line 5189:

Expected text after =item, not a number

Around line 5202:

Expected text after =item, not a number

Around line 5216:

Expected text after =item, not a number

Around line 5279:

Expected text after =item, not a number

Around line 5289:

Expected text after =item, not a number

Around line 5306:

Expected text after =item, not a number

Around line 5323:

Expected text after =item, not a number

Around line 5335:

Expected text after =item, not a number

Around line 5494:

Expected text after =item, not a number

Around line 5508:

Expected text after =item, not a number

Around line 5522:

Expected text after =item, not a number

Around line 5621:

Expected text after =item, not a number

Around line 5632:

Expected text after =item, not a number

Around line 5704:

Expected text after =item, not a number

Around line 5715:

Expected text after =item, not a number

Around line 5725:

Expected text after =item, not a number