CGI-3.49 > CGI
CGI-3.49
Other versions:
CGI-2.89

名前

CGI - Handle Common Gateway Interface requests and responses

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 is a stable, complete and mature solution for processing and preparing HTTP requests and responses. Major features including processing form submissions, file uploads, reading and writing cookies, query string generation and manipulation, and processing and preparing HTTP headers. Some HTML generation utilities are included as well.

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

CGI.pm performs very well in in a vanilla CGI.pm environment and also comes with built-in support for mod_perl and mod_perl2 as well as FastCGI.

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

It has the benefit of having developed and refined over 10 years with input from dozens of contributors and being deployed on thousands of websites. CGI.pm has been included in the Perl distribution since Perl 5.4, and has become a de-facto standard.

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

プログラミングスタイル

There are two styles of programming with CGI.pm, an object-oriented style and a function-oriented style. In the object-oriented style you create one or more CGI objects and then use object methods to create the various elements of the page. Each CGI object starts out with the list of named parameters that were passed to your CGI script by the server. You can modify the objects, save them to a file or database and recreate them. Because each object corresponds to the "state" of the CGI script, and because each object's parameter list is independent of the others, this allows you to save the state of the script and restore it later.

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

For example, using the object oriented style, here is how you create a simple "Hello World" HTML page:

以下にオブジェクト指向スタイルを使って、簡単な "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

In the function-oriented style, there is one default CGI object that you rarely deal with directly. Instead you just call functions to retrieve CGI parameters, create HTML tags, manage cookies, and so on. This provides you with a cleaner programming interface, but limits you to using one CGI object at a time. The following example prints the same page, but uses the function-oriented interface. The main differences are that we now need to import a set of functions into our name space (usually the "standard" functions), and we don't need to create the CGI object.

関数指向スタイルでは、直接扱うことがまずない、一つのデフォルトの 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

The examples in this document mainly use the object-oriented style. See HOW TO IMPORT FUNCTIONS for important information on function-oriented programming in CGI.pm

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

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

Most CGI.pm routines accept several arguments, sometimes as many as 20 optional ones! To simplify this interface, all routines use a named argument calling style that looks like this:

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

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

Each argument name is preceded by a dash. Neither case nor order matters in the argument list. -type, -Type, and -TYPE are all acceptable. In fact, only the first argument needs to begin with a dash. If a dash is present in the first argument, CGI.pm assumes dashes for the subsequent ones.

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

Several routines are commonly called with just one argument. In the case of these routines you can provide the single argument without an argument name. header() happens to be one of these routines. In this case, the single argument is the document type.

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

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

Other such routines are documented below.

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

Sometimes named arguments expect a scalar, sometimes a reference to an array, and sometimes a reference to a hash. Often, you can pass any type of argument and the routine will do whatever is most appropriate. For example, the param() routine is used to set a CGI parameter to a single or a multi-valued value. The two cases are shown below:

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

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

A large number of routines in CGI.pm actually aren't specifically defined in the module, but are generated automatically as needed. These are the "HTML shortcuts," routines that generate HTML tags for use in dynamically-generated pages. HTML tags have both attributes (the attribute="value" pairs within the tag itself) and contents (the part between the opening and closing pairs.) To distinguish between attributes and contents, CGI.pm uses the convention of passing HTML attributes as a hash reference as the first argument, and the contents, if any, as any subsequent arguments. It works out like this:

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 tags are described in more detail later.

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

Many newcomers to CGI.pm are puzzled by the difference between the calling conventions for the HTML shortcuts, which require curly braces around the HTML tag attributes, and the calling conventions for other routines, which manage to generate attributes without the curly brackets. Don't be confused. As a convenience the curly braces are optional in all but the HTML shortcuts. If you like, you can use curly braces when calling any routine that takes named arguments. For example:

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

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

If you use the -w switch, you will be warned that some CGI.pm argument names conflict with built-in Perl functions. The most frequent of these is the -values argument, used to create multi-valued menus, radio button clusters and the like. To get around this warning, you have several choices:

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

Many routines will do something useful with a named argument that it doesn't recognize. For example, you can produce non-standard HTTP header fields by providing them as named arguments:

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

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

This will produce the following nonstandard HTTP header:

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

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

Notice the way that underscores are translated automatically into hyphens. HTML-generating routines perform a different type of translation.

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

This feature allows you to keep up with the rapidly changing HTTP and HTML "standards".

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

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

     $query = CGI->new;

This will parse the input (from both POST and GET methods) and store it into a perl5 object called $query.

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

Any filehandles from file uploads will have their position reset to the beginning of the file.

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

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

     $query = CGI->new(INPUTFILE);

If you provide a file handle to the new() method, it will read parameters from the file (or STDIN, or whatever). The file can be in any of the forms describing below under debugging (i.e. a series of newline delimited TAG=VALUE pairs will work). Conveniently, this type of file is created by the save() method (see below). Multiple records can be saved and restored.

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

Perl purists will be pleased to know that this syntax accepts references to file handles, or even references to filehandle globs, which is the "official" way to pass a filehandle:

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

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

You can also initialize the CGI object with a FileHandle or IO::File object.

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

If you are using the function-oriented interface and want to initialize CGI state from a file handle, the way to do this is with restore_parameters(). This will (re)initialize the default CGI object from the indicated file handle.

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

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

You can also initialize the query object from a hash reference:

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

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

or from a properly formatted, URL-escaped query string:

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

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

or from a previously existing CGI object (currently this clones the parameter list, but none of the other object-specific fields, such as autoescaping):

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

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

To create an empty query, initialize it from an empty string or hash:

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

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

       -or-

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

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

     @keywords = $query->keywords

If the script was invoked as the result of an <ISINDEX> search, the parsed keywords can be obtained as an array using the keywords() method.

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

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

     @names = $query->param

If the script was invoked with a parameter list (e.g. "name1=value1&name2=value2&name3=value3"), the param() method will return the parameter names as a list. If the script was invoked as an <ISINDEX> script and contains a string without ampersands (e.g. "value1+value2+value3") , there will be a single parameter named "keywords" containing the "+"-delimited keywords.

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

NOTE: As of version 1.5, the array of parameter names returned will be in the same order as they were submitted by the browser. Usually this order is the same as the order in which the parameters are defined in the form (however, this isn't part of the spec, and so isn't guaranteed).

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

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

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

              -or-

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

Pass the param() method a single argument to fetch the value of the named parameter. If the parameter is multivalued (e.g. from multiple selections in a scrolling list), you can ask to receive an array. Otherwise the method will return a single value.

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

If a value is not given in the query string, as in the queries "name1=&name2=", it will be returned as an empty string.

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

If the parameter does not exist at all, then param() will return undef in a scalar context, and the empty list in a list context.

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

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

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

This sets the value for the named parameter 'foo' to an array of values. This is one way to change the value of a field AFTER the script has been invoked once before. (Another way is with the -override parameter accepted by all methods that generate form elements.)

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

param() also recognizes a named parameter style of calling described in more detail later:

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']);

This adds a value or list of values to the named parameter. The values are appended to the end of the parameter if it already exists. Otherwise the parameter is created. Note that this method only recognizes the named argument calling syntax.

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

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

   $query->import_names('R');

This creates a series of variables in the 'R' namespace. For example, $R::foo, @R:foo. For keyword lists, a variable @R::keywords will appear. If no namespace is given, this method will assume 'Q'. WARNING: don't import anything into 'main'; this is a major security risk!!!!

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

NOTE 1: Variable names are transformed as necessary into legal Perl variable names. All non-legal characters are transformed into underscores. If you need to keep the original names, you should use the param() method instead to access CGI variables by name.

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

NOTE 2: In older versions, this method was called import(). As of version 2.20, this name has been removed completely to avoid conflict with the built-in Perl module import operator.

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

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

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

This completely clears a list of parameters. It sometimes useful for resetting parameters that you don't want passed down between script invocations.

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

If you are using the function call interface, use "Delete()" instead to avoid conflicts with Perl's built-in delete operator.

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

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

   $query->delete_all();

This clears the CGI object completely. It might be useful to ensure that all the defaults are taken when you create a fill-out form.

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

Use Delete_all() instead if you are using the function call interface.

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

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

If POSTed data is not of type application/x-www-form-urlencoded or multipart/form-data, then the POSTed data will not be processed, but instead be returned as-is in a parameter named POSTDATA. To retrieve it, use code like this:

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

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

Likewise if PUTed data can be retrieved with code like this:

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

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

(If you don't know what the preceding means, don't worry about it. It only affects people trying to use CGI for XML processing and other specialized tasks.)

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

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

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

If you need access to the parameter list in a way that isn't covered by the methods above, you can obtain a direct reference to it by calling the param_fetch() method with the name of the . This will return an array reference to the named parameters, which you then can manipulate in any way you like.

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

You can also use a named argument style using the -name argument.

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

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

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

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

Many people want to fetch the entire parameter list as a hash in which the keys are the names of the CGI parameters, and the values are the parameters' values. The Vars() method does this. Called in a scalar context, it returns the parameter list as a tied hash reference. Changing a key changes the value of the parameter in the underlying CGI parameter list. Called in a list context, it returns the parameter list as an ordinary hash. This allows you to read the contents of the parameter list, but not to change it.

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

When using this, the thing you must watch out for are multivalued CGI parameters. Because a hash cannot distinguish between scalar and list context, multivalued parameters will be returned as a packed string, separated by the "\0" (null) character. You must split this packed string in order to get at the individual values. This is the convention introduced long ago by Steve Brenner in his cgi-lib.pl module for Perl version 4.

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

If you wish to use Vars() as a function, import the :cgi-lib set of function calls (also see the section on CGI-LIB compatibility).

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

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

    $query->save(\*FILEHANDLE)

This will write the current state of the form to the provided filehandle. You can read it back in by providing a filehandle to the new() method. Note that the filehandle can be a file, a pipe, or whatever!

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

The format of the saved file is:

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

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

Both name and value are URL escaped. Multi-valued CGI parameters are represented as repeated names. A session record is delimited by a single = symbol. You can write out multiple records and read them back in with several calls to new. You can do this across several sessions by opening the file in append mode, allowing you to create primitive guest books, or to keep a history of users' queries. Here's a short example of creating multiple session records:

名前と値の両方が 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";
   }

The file format used for save/restore is identical to that used by the Whitehead Genome Center's data exchange format "Boulderio", and can be manipulated and even databased using Boulderio utilities. See

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

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

for further details.

をご覧下さい。

If you wish to use this method from the function-oriented (non-OO) interface, the exported name for this method is save_parameters().

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

CGIエラーの取り出し

Errors can occur while processing user input, particularly when processing uploaded files. When these errors occur, CGI will stop processing and return an empty parameter list. You can test for the existence and nature of errors using the cgi_error() function. The error messages are formatted as HTTP status codes. You can either incorporate the error text into an HTML page, or use it as the value of the HTTP status:

ユーザ入力を処理して切る間、特にアップロードされたファイルを処理している 間にエラーが発生することがあります。 これらのエラーが発生したとき、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;
    }

When using the function-oriented interface (see the next section), errors may only occur the first time you call param(). Be ready for this!

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

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

To use the function-oriented interface, you must specify which CGI.pm routines or sets of routines to import into your script's namespace. There is a small overhead associated with this importation, but it isn't much.

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

   use CGI <list of methods>;

The listed methods will be imported into the current package; you can call them directly without creating a CGI object first. This example shows how to import the param() and header() methods, and then use them directly:

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

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

More frequently, you'll import common sets of functions by referring to the groups by name. All function sets are preceded with a ":" character as in ":html3" (for tags defined in the HTML 3 standard).

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

Here is a list of the function sets you can import:

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

: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 という変数が定義されています。

If you import a function name that is not part of CGI.pm, the module will treat it as a new HTML tag and generate the appropriate subroutine. You can then use it like any other HTML tag. This is to provide for the rapidly-evolving HTML "standard." For example, say Microsoft comes out with a new tag called <gradient> (which causes the user's desktop to be flooded with a rotating gradient fill until his machine reboots). You don't need to wait for a new version of CGI.pm to start using it immediately:

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

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

Note that in the interests of execution speed CGI.pm does not use the standard Exporter syntax for specifying load symbols. This may change in the future.

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

If you import any of the state-maintaining CGI or form-generating methods, a default CGI object will be created and initialized automatically the first time you use any of the methods that require one to be present. This includes param(), textfield(), submit() and the like. (If you need direct access to the CGI object, you can find it in the global variable $CGI::Q). By importing CGI.pm methods, you can create visually elegant scripts:

もし状態管理 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;

プラグマ

In addition to the function sets, there are a number of pragmas that you can import. Pragmas, which are always preceded by a hyphen, change the way that CGI.pm functions in various ways. Pragmas, function sets, and individual functions can all be imported in the same use() line. For example, the following use statement imports the standard set of functions and enables debugging mode (pragma -debug):

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

   use CGI qw/:standard -debug/;

The current list of pragmas is as follows:

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

-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 タグ関数のインポートのための特別な形式

Many of the methods generate HTML tags. As described below, tag functions automatically generate both the opening and closing tags. For example:

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

  print h1('Level 1 Header');

produces

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

  <h1>Level 1 Header</h1>

There will be some times when you want to produce the start and end tags yourself. In this case, you can use the form start_tag_name and end_tag_name, as in:

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

  print start_h1,'Level 1 Header',end_h1;

With a few exceptions (described below), start_tag_name and end_tag_name functions are not generated automatically when you use CGI. However, you can specify the tags you want to generate start/end functions for by putting an asterisk in front of their name, or, alternatively, requesting either "start_tag_name" or "end_tag_name" in the import list.

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

Example:

例:

  use CGI qw/:standard *table start_ul/;

In this example, the following functions are generated in addition to the standard ones:

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

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)

動的なドキュメント作成

Most of CGI.pm's functions deal with creating documents on the fly. Generally you will produce the HTTP header first, followed by the document itself. CGI.pm provides functions for generating HTTP headers of various types as well as for generating HTML. For creating GIF images, see the GD.pm module.

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

Each of these functions produces a fragment of HTML or HTTP which you can print out directly so that it displays in the browser window, append to a string, or save to a file for later use.

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

標準HTTPヘッダの作成:

Normally the first thing you will do in any CGI script is print out an HTTP header. This tells the browser what type of document to expect, and gives other optional information, such as the language, expiration date, and whether to cache the document. The header can also be manipulated for special purposes, such as server push and pay per view pages.

通常、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() returns the Content-type: header. You can provide your own MIME type if you choose, otherwise it defaults to text/html. An optional second parameter specifies the status code and a human-readable message. For example, you can specify 204, "No response" to create a script that tells the browser to do nothing at all.

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

The last example shows the named argument style for passing arguments to the CGI methods using named parameters. Recognized parameters are -type, -status, -expires, and -cookie. Any other named parameters will be stripped of their initial hyphens and turned into header fields, allowing you to specify any HTTP header you desire. Internal underscores will be turned into hyphens:

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

    print header(-Content_length=>3002);

Most browsers will not cache the output from CGI scripts. Every time the browser reloads the page, the script is invoked anew. You can change this behavior with the -expires parameter. When you specify an absolute or relative expiration interval with this parameter, some browsers and proxy servers will cache the script's output until the indicated expiration date. The following forms are all valid for the -expires field:

ほとんどのブラウザは 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  指定された時刻と日付

The -cookie parameter generates a header that tells the browser to provide a "magic cookie" during all subsequent transactions with your script. Some cookies have a special format that includes interesting attributes such as expiration time. Use the cookie() method to create and retrieve session cookies.

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

The -nph parameter, if set to a true value, will issue the correct headers to work with a NPH (no-parse-header) script. This is important to use with certain servers that expect all their scripts to be NPH.

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

The -charset parameter can be used to control the character set sent to the browser. If not provided, defaults to ISO-8859-1. As a side effect, this sets the charset() method as well.

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

The -attachment parameter can be used to turn the page into an attachment. Instead of displaying the page, some browsers will prompt the user to save it to disk. The value of the argument is the suggested name for the saved file. In order for this to work, you may have to set the -type to "application/octet-stream".

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

The -p3p parameter will add a P3P tag to the outgoing header. The parameter can be an arrayref or a space-delimited string of P3P tags. For example:

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

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

In either case, the outgoing header will be formatted as:

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

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

Note that if a header value contains a carriage return, a leading space will be added to each new line that doesn't already have one as specified by RFC2616 section 4.2. For example:

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

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

will generate

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

    Ingredients: ham
     eggs
     bacon

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

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

Sometimes you don't want to produce a document yourself, but simply redirect the browser elsewhere, perhaps choosing a URL based on the time of day or the identity of the user.

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

The redirect() method redirects the browser to a different URL. If you use redirection like this, you should not print out a header as well.

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

You should always use full URLs (including the http: or ftp: part) in redirection requests. Relative URLs will not work correctly.

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

You can also use named arguments:

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

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

All names arguments recognized by header() are also recognized by redirect(). However, most HTTP headers, including those generated by -cookie and -target, are ignored by the browser.

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

The -nph parameter, if set to a true value, will issue the correct headers to work with a NPH (no-parse-header) script. This is important to use with certain servers, such as Microsoft IIS, which expect all their scripts to be NPH.

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

The -status parameter will set the status of the redirect. HTTP defines three different possible redirection status codes:

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

     301 Moved Permanently
     302 Found
     303 See Other

The default if not specified is 302, which means "moved temporarily." You may change the status to another status code if you wish. Be advised that changing the status to anything other than 301, 302 or 303 will probably break redirection.

指定しなかったときのデフォルトは 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');

After creating the HTTP header, most CGI scripts will start writing out an HTML document. The start_html() routine creates the top of the page, along with a lot of optional information that controls the page's appearance and behavior.

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

This method returns a canned HTML header and the opening <body> tag. All parameters are optional. In the named parameter form, recognized parameters are -title, -author, -base, -xbase, -dtd, -lang and -target (see below for the explanation). Any additional parameters you provide, such as the unofficial BGCOLOR attribute, are added to the <body> tag. Additional parameters must be proceeded by a hyphen.

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

The argument -xbase allows you to provide an HREF for the <base> tag different from the current location, as in

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

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

All relative links will be interpreted relative to this tag.

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

The argument -target allows you to provide a default target frame for all the links and fill-out forms on the page. This is a non-standard HTTP feature which only works with some browsers!

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

    -target=>"answer_window"

All relative links will be interpreted relative to this tag. You add arbitrary meta information to the header with the -meta argument. This argument expects a reference to a hash containing name/value pairs of meta information. These will be turned into a series of header <meta> tags that look something like this:

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

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

To create an HTTP-EQUIV type of <meta> tag, use -head, described below.

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

The -style argument is used to incorporate cascading stylesheets into your code. See the section on CASCADING STYLESHEETS for more information.

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

The -lang argument is used to incorporate a language attribute into the <html> tag. For example:

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

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

The default if not specified is "en-US" for US English, unless the -dtd parameter specifies an HTML 2.0 or 3.2 DTD, in which case the lang attribute is left off. You can force the lang attribute to left off in other cases by passing an empty string (-lang=>'').

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

The -encoding argument can be used to specify the character set for XHTML. It defaults to iso-8859-1 if not specified.

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

The -declare_xml argument, when used in conjunction with XHTML, will put a <?xml> declaration at the top of the HTML header. The sole purpose of this declaration is to declare the character set encoding. In the absence of -declare_xml, the output HTML will contain a <meta> tag that specifies the encoding, allowing the HTML to pass most validators. The default for -declare_xml is false.

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

You can place other arbitrary HTML elements to the <head> section with the -head tag. For example, to place the rarely-used <link> element in the head section, use this:

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

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

To incorporate multiple HTML elements into the <head> section, just pass an array reference:

複数の 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'})
                             ]
                     );

And here's how to create an HTTP-EQUIV <meta> tag:

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

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

JAVASCRIPTING: The -script, -noScript, -onLoad, -onMouseOver, -onMouseOut and -onUnload parameters are used to add JavaScript calls to your pages. -script should point to a block of text containing JavaScript function definitions. This block will be placed within a <script> block inside the HTML (not HTTP) header. The block is placed in the header in order to give your page a fighting chance of having all its JavaScript functions in place even if the user presses the stop button before the page has loaded completely. CGI.pm attempts to format the script in such a way that JavaScript-naive browsers will not choke on the code: unfortunately there are some browsers, such as Chimera for Unix, that get confused by it nevertheless.

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

The -onLoad and -onUnload parameters point to fragments of JavaScript code to execute when the page is respectively opened and closed by the browser. Usually these parameters are calls to functions defined in the -script field:

-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);

Use the -noScript parameter to pass some HTML text that will be displayed on browsers that do not have JavaScript (or browsers where JavaScript is turned off).

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

The <script> tag, has several attributes including "type" and src. The latter is particularly interesting, as it allows you to keep the JavaScript code in a file or CGI script rather than cluttering up each page with the source. To use these attributes pass a HASH reference in the -script parameter containing one or more of -type, -src, or -code:

<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;"'}
               );

A final feature allows you to incorporate multiple <script> sections into the header. Just pass the list of script sections as an array reference. this allows you to specify different source files for different dialects of JavaScript. Example:

最後の機能は複数の <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'
                                    }
                                 ]
                             );

The option "-language" is a synonym for -type, and is supported for backwad compatibility.

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

The old-style positional parameters are as follows:

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

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

This ends an HTML document by printing the </body></html> tags.

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

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

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

self_url() will return a URL, that, when selected, will reinvoke this script with all its state information intact. This is most useful when you want to jump around within the document using internal anchors but you don't want to disrupt the current contents of the form(s). Something like this will do the trick.

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>";

If you want more control over what's returned, using the url() method instead.

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

You can also retrieve the unprocessed query string with query_string():

処理されていない問い合わせ文字列は 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() returns the script's URL in a variety of formats. Called without any arguments, it returns the full form of the URL, including host name and port number

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

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

You can modify this format with the following named arguments:

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

-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');

It is possible for a script to receive CGI parameters in the URL as well as in the fill-out form by creating a form that POSTs to a URL containing a query string (a "?" mark followed by arguments). The param() method will always return the contents of the POSTed fill-out form, ignoring the URL's query string. To retrieve URL parameters, call the url_param() method. Use it in the same way as param(). The main difference is that it allows you to read the parameters, but not set them.

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

Under no circumstances will the contents of the URL query string interfere with similarly-named CGI parameters in POSTed forms. If you try to mix a URL query string with a form submitted with the GET method, the results will not be what you expect.

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

標準HTML要素の作成:

CGI.pm defines general HTML shortcut methods for most, if not all of the HTML 3 and HTML 4 tags. HTML shortcuts are named after a single HTML element and return a fragment of HTML text that you can then print or manipulate as you like. Each shortcut returns a fragment of HTML code that you can append to a string, save to a file, or, most commonly, print out so that it displays in the browser window.

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

This example shows how to use the HTML methods:

この例は 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;

This results in the following HTML code (extra newlines have been added for readability):

この結果は以下の 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>

If you find the syntax for calling the HTML shortcuts awkward, you can import them into your namespace and dispense with the object syntax completely (see the next section for more details):

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 ショートカットに引数を与える

The HTML methods will accept zero, one or multiple arguments. If you provide no arguments, you get a single tag:

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

   print hr;    #  <hr>

If you provide one or more string arguments, they are concatenated together with spaces and placed between opening and closing tags:

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

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

If the first argument is a hash reference, then the keys and values of the hash become the HTML tag's attributes:

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

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

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

You may dispense with the dashes in front of the attribute names if you prefer:

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

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

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

Sometimes an HTML tag attribute has no argument. For example, ordered lists can be marked as COMPACT. The syntax for this is an argument that that points to an undef string:

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

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

Prior to CGI.pm version 2.41, providing an empty ('') string as an attribute argument was the same as providing undef. However, this has changed in order to accommodate those who want to create tags of the form <img alt="">. The difference is shown in these two pieces of code:

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

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

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

One of the cool features of the HTML shortcuts is that they are distributive. If you give them an argument consisting of a reference to a list, the tag will be distributed across each element of the list. For example, here's one way to make an ordered list:

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

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

This example will result in HTML output that looks like this:

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

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

This is extremely useful for creating tables. For example:

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

   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 ショートカットとリストの挿入

Consider this bit of code:

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

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

It will ordinarily return the string that you probably expect, namely:

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

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

Note the space between the element "Hi" and the element "mom!". CGI.pm puts the extra space there using array interpolation, which is controlled by the magic $" variable. Sometimes this extra space is not what you want, for example, when you are trying to align a series of images. In this case, you can simply change the value of $" to an empty string.

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

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

I suggest you put the code in a block as shown here. Otherwise the change to $" will affect all subsequent code until you explicitly reset it.

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

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

A few HTML tags don't follow the standard pattern for various reasons.

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

comment() generates an HTML comment (<!-- comment -->). Call it like

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

    print comment('here is my comment');

Because of conflicts with built-in Perl functions, the following functions begin with initial caps:

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

    Select
    Tr
    Link
    Delete
    Accept
    Sub

In addition, start_html(), end_html(), start_form(), end_form(), start_multipart_form() and all the fill-out form tags are special. See their respective sections.

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

HTMLの自動エスケープ

By default, all HTML that is emitted by the form-generating functions is passed through a function called escapeHTML():

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

$escaped_string = escapeHTML("unescaped string");

Escape HTML formatting characters in a string.

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

Provided that you have specified a character set of ISO-8859-1 (the default), the standard HTML escaping rules will be used. The "<" character becomes "&lt;", ">" becomes "&gt;", "&" becomes "&amp;", and the quote character becomes "&quot;". In addition, the hexadecimal 0x8b and 0x9b characters, which some browsers incorrectly interpret as the left and right angle-bracket characters, are replaced by their numeric character entities ("&#8249" and "&#8250;"). If you manually change the charset, either by calling the charset() method explicitly or by passing a -charset argument to header(), then all characters will be replaced by their numeric entities, since CGI.pm has no lookup table for all the possible encodings.

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

escapeHTML() expects the supplied string to be a character string. This means you should Encode::decode data received from "outside" and Encode::encode your strings before sending them back outside. If your source code UTF-8 encoded and you want to upgrade string literals in your source to character strings, you can use "use utf8". See perlunitut, perlunifaq and perlunicode for more information on how Perl handles the difference between bytes and characters.

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

The automatic escaping does not apply to other shortcuts, such as h1(). You should call escapeHTML() yourself on untrusted data in order to protect your pages against nasty tricks that people may enter into guestbooks, etc.. To change the character set, use charset(). To turn autoescaping off completely, use autoEscape(0):

自動エスケープは 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)

By default, all the HTML produced by these functions comes out as one long line without carriage returns or indentation. This is yuck, but it does reduce the size of the documents by 10-20%. To get pretty-printed output, please use CGI::Pretty, a subclass contributed by Brian Paulsen.

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

フォームの作成:

General note The various form-creating methods all return strings to the caller, containing the tag or tags that will create the requested form element. You are responsible for actually printing out these strings. It's set up this way so that you can place formatting tags around the form elements.

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

Another note The default values that you specify for the forms are only used the first time the script is invoked (when there is no query string). On subsequent invocations of the script (when there is a query string), the former values are used even if they are blank.

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

If you want to change the value of a field from its previous value, you have two choices:

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

(1) call the param() method to set it.

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

(2) use the -override (alias -force) parameter (a new feature in version 2.15). This forces the default value to be used, regardless of the previous value:

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

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

Yet another note By default, the text and labels of form elements are escaped according to HTML rules. This means that you can safely use "<CLICK ME>" as the label for a button. However, it also interferes with your ability to incorporate special HTML character sequences, such as &Aacute;, into your fields. If you wish to turn off automatic escaping, call the autoEscape() method with a false value immediately after creating the CGI object:

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

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

Note that autoEscape() is exclusively used to effect the behavior of how some CGI.pm HTML generation fuctions handle escaping. Calling escapeHTML() explicitly will always escape the HTML.

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

A Lurking Trap! Some of the form-element generating methods return multiple tags. In a scalar context, the tags will be concatenated together with spaces, or whatever is the current value of the $" global. In a list context, the methods will return a list of elements, allowing you to modify them if you wish. Usually you will not notice this behavior, but beware of this:

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

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

end_form() produces several tags, and only the first of them will be printed because the format only expects one value.

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

<p>

<p>

ISINDEX タグの作成

   print isindex(-action=>$action);

         -or-

   print isindex($action);

Prints out an <isindex> tag. Not very exciting. The parameter -action specifies the URL of the script to process the query. The default is to process the query with the current script.

<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() will return a <form> tag with the optional method, action and form encoding that you specify. The defaults are:

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() returns the closing </form> tag.

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

Start_form()'s enctype argument tells the browser how to package the various fields of the form before sending the form to the server. Two values are possible:

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

Note: These methods were previously named startform() and endform(). These methods are now DEPRECATED. Please use start_form() and end_form() instead.

注意: このメソッドは以前 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 が有効(これがデフォルトです)なら、フォームは自動的にこのタイプの エンコーディングを使って作成されます。

The start_form() method uses the older form of encoding by default unless XHTML is requested. If you want to use the newer form of encoding by default, you can call start_multipart_form() instead of start_form(). The method end_multipart_form() is an alias to end_form().

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

 JAVASCRIPTING: The -name and -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 を返すことによってサブミットを中止することが出来ます。

Usually the bulk of JavaScript functions are defined in a <script> block in the HTML header and -onSubmit points to one of these function call. See start_html() for details.

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

form 要素

After starting a form, you will typically create one or more textfields, popup menus, radio groups and other form elements. Each of these elements takes a standard set of named arguments. Some elements also have optional arguments. The standard arguments are as follows:

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

-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 の章を参照してください。

Other common arguments are described in the next section. In addition to these, all attributes described in the HTML specifications are supported.

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

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

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

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

textfield() will return a text input field.

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)。

As with all these methods, the field will be initialized with its previous contents from earlier invocations of the script. When the form is processed, the value of the text field can be retrieved with:

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

       $value = param('foo');

If you want to reset it from its initial value after the script has been called once, you can do so like this:

そのスクリプトが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() is just like textfield, but it allows you to specify rows and columns for a multiline text entry box. You can provide a starting value for the field, which can be long and contain multiple lines.

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

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

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

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

password_field() is identical to textfield(), except that its contents will be starred out on the web page.

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() will return a file upload field. In order to take full advantage of this you must use the new multipart encoding scheme for the form. You can do this either by calling start_form() with an encoding type of &CGI::MULTIPART, or by calling the new method start_multipart_form() instead of vanilla start_form().

filefield() はファイルアップロードフィールドを返します。 利点をすべて生かすためには、そのフォームに 新しいマルチパートエンコーディングスキームを使わなければなりません。 これはエンコーディングタイプを &CGI::MULTIPARTstart_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: The -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut and -onSelect parameters are recognized. See textfield() for details.

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

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

基本

When the form is processed, you can retrieve an IO::Handle compatibile handle for a file upload field like this:

フォームを処理するときに、以下のようにしてファイルアップロード用の 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;
    }
  }

In a list context, upload() will return an array of filehandles. This makes it possible to process forms that use the same name for multiple upload fields.

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

If you want the entered file name for the file, you can just call param():

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

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

Different browsers will return slightly different things for the name. Some browsers return the filename only. Others return the full path to the file, using the path conventions of the user's machine. Regardless, the name returned is always the name of the file on the user's machine, and is unrelated to the name of the temporary file that CGI.pm creates during upload spooling (see below).

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

When a file is uploaded the browser usually sends along some information along with it in the format of headers. The information usually includes the MIME content type. To retrieve this information, call uploadInfo(). It returns a reference to a hash containing all the document headers.

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

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

If you are using a machine that recognizes "text" and "binary" data modes, be sure to understand when and how to use them (see the Camel book). Otherwise you may find that binary files are corrupted during file uploads.

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

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

When processing an uploaded file, CGI.pm creates a temporary file on your hard disk and passes you a file handle to that file. After you are finished with the file handle, CGI.pm unlinks (deletes) the temporary file. If you need to you can access the temporary file directly. You can access the temp file for a file upload by passing the file name to the tmpFileName() method:

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

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

The temporary file will be deleted automatically when your program exits unless you manually rename it. On some operating systems (such as Windows NT), you will need to close the temporary file's filehandle before your program exits. Otherwise the attempt to delete the temporary file will fail.

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

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

There are occasionally problems involving parsing the uploaded file. This usually happens when the user presses "Stop" before the upload is finished. In this case, CGI.pm will return undef for the name of the uploaded file and set cgi_error() to the string "400 Bad request (malformed multipart POST)". This error message is designed so that you can incorporate it into a status code to be sent to the browser. Example:

ときどきアップロードされたファイルを解析している途中に問題が発生します。 通常それはユーザがアップロードが完了する前に "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;
   }

You are free to create a custom HTML page to complain about the error, if you wish.

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

Progress bars for file uploads and avoiding temp files

CGI.pm gives you low-level access to file upload management through a file upload hook. You can use this feature to completely turn off the temp file storage of file uploads, or potentially write your own file upload progess meter.

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

This is much like the UPLOAD_HOOK facility available in Apache::Request, with the exception that the first argument to the callback is an Apache::Upload object, here it's the remote filename.

これは 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";
 }

The $data field is optional; it lets you pass configuration information (e.g. a database handle) to your hook callback.

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

The $use_tempfile field is a flag that lets you turn on and off CGI.pm's use of a temporary disk-based file during file upload. If you set this to a FALSE value (default true) then $q->param('uploaded_file') will no longer work, and the only way to get at the uploaded data is via the hook you provide.

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

If using the function-oriented interface, call the CGI::upload_hook() method before calling param() or any other CGI functions:

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

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

This method is not exported by default. You will have to import it explicitly if you wish to use it without the CGI:: prefix.

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

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

If you are using CGI.pm on a Windows platform and find that binary files get slightly larger when uploaded but that text files remain the same, then you have forgotten to activate binary mode on the output filehandle. Be sure to call binmode() on any handle that you create to write the uploaded file to disk.

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

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

( This section is here for completeness. if you are building a new application with CGI.pm, you can skip it. )

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

The original way to process file uploads with CGI.pm was to use param(). The value it returns has a dual nature as both a file name and a lightweight filehandle. This dual nature is problematic if you following the recommended practice of having use strict in your code. Perl will complain when you try to use a string as a filehandle. More seriously, it is possible for the remote user to type garbage into the upload field, in which case what you get from param() is not a filehandle at all, but a string.

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

To solve this problem the upload() method was added, which always returns a lightweight filehandle. This generally works well, but will have trouble interoperating with some other modules because the file handle is not derived from IO::Handle. So that brings us to current recommedation given above, which is to call the handle() method on the file handle returned by upload(). That upgrades the handle to an IO::Handle. It's a big win for compatibility for a small penalty of loading IO::Handle the first time you call it.

この問題を解決するために 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() creates a menu.

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 属性を 個別のメニュー要素に与えるために提供されます。 メニューの値を属性の名前をキーとし属性の値を値とする他のハッシュに関連付ける ハッシュへのポインタになります。

When the form is processed, the selected value of the popup menu can be retrieved using:

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

      $popup_menu_value = param('menu_name');

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

Named parameter style

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

  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() creates an option group within a popup menu.

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() creates a scrolling list.

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() creates a list of checkboxes that are related by the same name.

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に設定されると垂直なリストで 表示されるようチェックボックスの間に改行をいれます。 そうでなければ水平に一緒になって並べられます。

The optional -labels argument is a pointer to a hash relating the checkbox values to the user-visible labels that will be printed next to them. If not provided, the values will be used as the default.

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

The optional parameters -rows, and -columns cause checkbox_group() to return an HTML3 compatible table containing the checkbox group formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; checkbox_group will calculate the correct number of rows for you.

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

The option -disabled takes an array of checkbox values and disables them by greying them out (this may not be supported by all browsers).

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

The optional -attributes argument 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.

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

The optional -tabindex argument can be used to control the order in which radio buttons receive focus when the user presses the tab button. If passed a scalar numeric value, the first element in the group will receive this tab index and subsequent elements will be incremented by one. If given a reference to an array of radio button values, then the indexes will be jiggered so that the order specified in the array will correspond to the tab order. You can also pass a reference to a hash in which the hash keys are the radio button values and the values are the tab indexes of each button. Examples:

オプションの -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

The optional -labelattributes argument will contain attributes attached to the <label> element that surrounds each button.

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

When the form is processed, all checked boxes will be returned as a list under the parameter name 'group_name'. The values of the "on" checkboxes can be retrieved with:

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

      @turned_on = param('group_name');

The value returned by checkbox_group() is actually an array of button elements. You can capture them and use them within tables, lists, or in other creative ways:

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() is used to create an isolated checkbox that isn't logically related to any others.

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) はチェックボックスにつけられるユーザが 読むことが出来るラベルです。 指定されなければ、チェックボックスの名前が使われます。

The value of the checkbox can be retrieved using:

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

    $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() creates a set of logically-related radio buttons (turning one member of the group on turns the others off)

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) はオプションで、ラジオボタンの値と表示のときに 使われるユーザに見えるラベルとを関連付けるハッシュへのポインタです。 与えられなければ、値そのものが表示されます。

All modern browsers can take advantage of the optional parameters -rows, and -columns. These parameters cause radio_group() to return an HTML3 compatible table containing the radio group formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; radio_group will calculate the correct number of rows for you.

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

To include row and column headings in the returned table, you can use the -rowheaders and -colheaders parameters. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpretation of the radio buttons -- they're still a single named unit.

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

The optional -tabindex argument can be used to control the order in which radio buttons receive focus when the user presses the tab button. If passed a scalar numeric value, the first element in the group will receive this tab index and subsequent elements will be incremented by one. If given a reference to an array of radio button values, then the indexes will be jiggered so that the order specified in the array will correspond to the tab order. You can also pass a reference to a hash in which the hash keys are the radio button values and the values are the tab indexes of each button. Examples:

オプションの -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

The optional -attributes argument 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.

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

The optional -labelattributes argument will contain attributes attached to the <label> element that surrounds each button.

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

When the form is processed, the selected radio button can be retrieved using:

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

      $which_radio_button = param('group_name');

The value returned by radio_group() is actually an array of button elements. You can capture them and use them within tables, lists, or in other creative ways:

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() will create the query submission button. Every form should have one of these.

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 のどちらが、ボタン上のユーザーが目にするラベルかで いつも混乱します。

You can figure out which button was pressed by using different values for each one:

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

     $which_one = param('button_name');

リセットボタンの作成

   print reset

reset() creates the "reset" button. Note that it restores the form to its value from the last time the script was called, NOT necessarily to the defaults.

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

Note that this conflicts with the Perl reset() built-in. Use CORE::reset() to get the original reset function.

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

デフォルトボタンの作成

   print defaults('button_label')

defaults() creates a button that, when invoked, will cause the form to be completely reset to its defaults, wiping out all the changes the user ever made.

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

隠しフィールドの作成

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

                -or-

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

hidden() produces a text field that can't be seen by the user. It is useful for passing state variable information from one invocation of the script to the next.

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)。 呼び出しの名前付きパラメータ形式では、一つの値またはリスト全体への リファレンスを指定することが出来ます。

Fetch the value of a hidden field this way:

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

     $hidden_value = param('hidden_name');

Note, that just like all the other form elements, the value of a hidden field is "sticky". If you want to replace a hidden field with some other values after the script has been called once you'll have to do it manually:

他のすべてのフォーム要素と同じように、隠しフィールドは "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() produces a clickable image. When it's clicked on the position of the click is returned to your script as "button_name.x" and "button_name.y", where "button_name" is the name you've assigned to it.

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 を指定することが出来ます。

Fetch the value of the button this way:

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

     $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() produces an <input> tag with type="button". When it's pressed the fragment of JavaScript code pointed to by the -onClick parameter will be executed.

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

HTTP クッキー

Browsers support a so-called "cookie" designed to help maintain state within a browser session. CGI.pm has several methods that support cookies.

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

A cookie is a name=value pair much like the named parameters in a CGI query string. CGI scripts create one or more cookies and send them to the browser in the HTTP header. The browser maintains a list of cookies that belong to a particular Web server, and returns them to the CGI script during subsequent interactions.

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

In addition to the required name=value pair, each cookie has several optional attributes:

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

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 のような セキュアなチャンネルで発生された場合にのみ送信されます。

The interface to HTTP cookies is the cookie() method:

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

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

cookie() creates a new cookie. Its parameters include:

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 セッションでのみ使われます。

The cookie created by cookie() must be incorporated into the HTTP header within the string returned by the header() method:

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

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

To create multiple cookies, give header() an array reference:

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

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

To retrieve a cookie, request it by name by calling cookie() method without the -value parameter. This example uses the object-oriented form:

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

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

Cookies created with a single scalar value, such as the "riddle_name" cookie, will be returned in that form. Cookies with array and hash values can also be retrieved.

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

The cookie and CGI namespaces are separate. If you have a parameter named 'answers' and a cookie named 'answers', the values retrieved by param() and cookie() are independent of each other. However, it's simple to turn a CGI parameter into a cookie, and vice-versa:

クッキーと 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')]);

If you call cookie() without any parameters, it will return a list of the names of all cookies passed to your script:

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

  @cookies = cookie();

See the cookie.cgi example script for some ideas on how to use cookies effectively.

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

フレームの利用

It's possible for CGI.pm scripts to write into several browser panels and windows using the HTML 4 frame mechanism. There are three techniques for defining new frames programmatically:

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" という名前のフレームにロードされます。 それがまだなければ新しいウィンドウが作成されます。

The script "frameset.cgi" in the examples directory shows one way to create pages in which the fill-out form and the response live in side-by-side frames.

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

JavaScript 対応

The usual way to use JavaScript is to define a set of functions in a <SCRIPT> block inside the HTML header and then to register event handlers in the various elements of the page. Events include such things as the mouse passing over a form element, a button being clicked, the contents of a text field changing, or a form being submitted. When an event occurs that involves an element that has registered an event handler, its associated JavaScript code gets called.

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

The elements that can register event handlers include the <BODY> of an HTML document, hypertext links, all the various elements of a fill-out form, and the form itself. There are a large number of events, and each applies only to the elements for which it is relevant. Here is a partial list:

イベントハンドラを登録できる要素には、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

In order to register a JavaScript event handler with an HTML element, just use the event name as a parameter when you call the corresponding CGI method. For example, to have your validateAge() JavaScript code executed every time the textfield named "age" changes, generate the field like this:

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

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

This example assumes that you've already declared the validateAge() function by incorporating it into a <SCRIPT> block. The CGI.pm start_html() method provides a convenient way to create this section.

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

Similarly, you can create a form that checks itself over for consistency and alerts the user if some essential value is missing by creating it this way:

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

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

See the javascript.cgi script for a demonstration of how this all works.

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

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

CGI.pm has limited support for HTML3's cascading style sheets (css). To incorporate a stylesheet into your document, pass the start_html() method a -style parameter. The value of this parameter may be a scalar, in which case it is treated as the source URL for the stylesheet, or it may be a hash reference. In the latter case you should provide the hash with one or more of -src or -code. -src points to a URL where an externally-defined stylesheet can be found. -code points to a scalar value to be incorporated into a <style> section. Style definitions in -code override similarly-named ones in -src, hence the name "cascading."

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

You may also specify the type of the stylesheet by adding the optional -type parameter to the hash pointed to by -style. If not specified, the style defaults to 'text/css'.

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

To refer to a style within the body of your document, add the -class parameter to any HTML element:

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

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

Or define styles on the fly with the -style parameter:

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

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

You may also use the new span() element to apply a style to a section of text:

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

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

Note that you must import the ":html3" definitions to have the span() method available. Here's a quick and dirty example of using CSS's. See the CSS specification at http://www.w3.org/Style/CSS/ for more information.

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;

Pass an array reference to -code or -src in order to incorporate multiple stylesheets into your document.

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

Should you wish to incorporate a verbatim stylesheet that includes arbitrary formatting in the header, you may pass a -verbatim tag to the -style hash, as follows:

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

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

This will generate an HTML header that contains this:

これは、以下のものを含む 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>

Any additional arguments passed in the -style value will be incorporated into the <link> tag. For example:

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

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

This will give:

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

 <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>

<p>

To make more complicated <link> tags, use the Link() function and pass it to start_html() in the -head argument, as in:

より複雑な <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})

To create primary and "alternate" stylesheet, use the -alternate option:

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

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

デバッグ

If you are running the script from the command line or in the perl debugger, you can pass the script a list of keywords or parameter=value pairs on the command line or from standard input (you don't have to worry about tricking your script into reading from environment variables). You can pass keywords like this:

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

    your_script.pl keyword1 keyword2 keyword3

or this:

あるいは:

   your_script.pl keyword1+keyword2+keyword3

or this:

あるいは:

    your_script.pl name1=value1 name2=value2

or this:

あるいは:

    your_script.pl name1=value1&name2=value2

To turn off this feature, use the -no_debug pragma.

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

To test the POST method, you may enable full debugging with the -debug pragma. This will allow you to feed newline-delimited name=value pairs to the script on standard input.

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

When debugging, you can use quotes and backslashes to escape characters in the familiar shell manner, letting you place spaces and other funny characters in your parameter=value pairs:

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

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

Finally, you can set the path info for the script by prefixing the first name/value parameter with the path followed by a question mark (?):

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

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

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

The Dump() method produces a string consisting of all the query's name/value pairs formatted nicely as a nested list. This is useful for debugging purposes:

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

    print Dump

Produces something that looks like:

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

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

As a shortcut, you can interpolate the entire CGI object into a string and it will be replaced with the a nice HTML dump shown above:

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

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

環境変数の取り出し

Some of the more useful environment variables can be fetched through this interface. The methods are as follows:

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

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, or "no-parsed-header", scripts bypass the server completely by sending the complete HTTP header directly to the browser. This has slight performance benefits, but is of most use for taking advantage of HTTP extensions that are not directly supported by your server, such as server push and PICS headers.

NPH または"解析されないヘッダ"("no-parsed-header")、では、完全な HTTP ヘッダを直接ブラウザに送信することにより、スクリプトはサーバを 完全にバイパスします。 これはパフォーマンスの面で少し利点があります。 しかしほとんどは、サーバプッシュや PICS ヘッダのような、サーバによって 直接にはサポートされていない HTTP 拡張の利点を得るために使われます。

Servers use a variety of conventions for designating CGI scripts as NPH. Many Unix servers look at the beginning of the script's name for the prefix "nph-". The Macintosh WebSTAR server and Microsoft's Internet Information Server, in contrast, try to decide whether a program is an NPH script by examining the first line of script output.

CGI スクリプトを NPH として示すため、さまざまな約束が使われます。 多くの Unix サーバはスクリプトの名前の始まりに接頭辞 "nph-" があるかを 見ます。 これに対して Macintosh WebSTAR サーバと Microsoft の Internet Information Server は、スクリプト出力の先頭行をチェックする ことにより NPH スクリプトであるかを判定しようとします。

CGI.pm supports NPH scripts with a special NPH mode. When in this mode, CGI.pm will output the necessary extra header information when the header() and redirect() methods are called.

CGI.pm は特別は NPH モードで NPH スクリプトをサポートします。 このモードでは CGI.pm は header() や redirect() メソッドが呼ばれると 必要となる特殊なヘッダ情報を出力します。

The Microsoft Internet Information Server requires NPH mode. As of version 2.30, CGI.pm will automatically detect when the script is running under IIS and put itself into this mode. You do not need to do this manually, although it won't hurt anything if you do. However, note that if you have applied Service Pack 6, much of the functionality of NPH scripts, including the ability to redirect while setting a cookie, do not work at all on IIS without a special patch from Microsoft. See http://web.archive.org/web/20010812012030/http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP Non-Parsed Headers Stripped From CGI Applications That Have nph- Prefix in Name.

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 provides four simple functions for producing multipart documents of the type needed to implement server push. These functions were graciously provided by Ed Jordan <ed@fidalgo.net>. To import these into your namespace, you must import the ":push" set. You are also advised to put the script into NPH mode and to set $| to 1 to avoid buffering problems.

CGI.pm は、サーバプッシュを実装するために必要な種類である マルチパートドキュメントを作成するために簡単な4つの関数を提供しています。 これらの関数はありがたいことに Ed Jordan <ed@fidalgo.net> によって 提供されました。 これらを名前空間にインポートするためには、":push" セットを インポートしなければいけません。 またスクリプトをNPH モードとし、バッファリングの問題を避けるために $| を 1 に設定したほうがよいでしょう。

Here is a simple script that demonstrates server push:

サーバプッシュをデモンストレーションする簡単なスクリプトを以下に示します:

  #!/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;
  }

This script initializes server push by calling multipart_init(). It then enters a loop in which it begins a new multipart section by calling multipart_start(), prints the current local time, and ends a multipart section with multipart_end(). It then sleeps a second, and begins again. On the final iteration, it ends the multipart section with multipart_final() rather than with multipart_end().

このスクリプトは 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() を呼ばなければなりません。

Users interested in server push applications should also have a look at the CGI::Push module.

サーバプッシュアプリケーションに興味のあるユーザは CGI::Push モジュールも 見るべきです。

サービス不能(DoS)攻撃の回避

A potential problem with CGI.pm is that, by default, it attempts to process form POSTings no matter how large they are. A wily hacker could attack your site by sending a CGI script a huge POST of many megabytes. CGI.pm will attempt to read the entire POST into a variable, growing hugely in size until it runs out of memory. While the script attempts to allocate the memory the system may slow down dramatically. This is a form of denial of service attack.

CGI.pm での潜在的な問題は、デフォルトでは POST されたフォームが どんなに大きくても処理しようとすることです。 ずるがしこいハッカーは数メガバイトの巨大な POST を CGI スクリプトに 送信することにより、あたなのサイトを攻撃することが出来ます。 CGI.pm は POST 全体を変数に読み込もうとし、メモリがなくなるまで、 その大きさは巨大に成長します。 スクリプトがメモリを占有しようとする間、システムは劇的に遅くなるかも しれません。 これがサービス不能(DoS)攻撃の形です。

Another possible attack is for the remote user to force CGI.pm to accept a huge file upload. CGI.pm will accept the upload and store it in a temporary directory even if your script doesn't expect to receive an uploaded file. CGI.pm will delete the file automatically when it terminates, but in the meantime the remote user may have filled up the server's disk space, causing problems for other programs.

他の可能な攻撃はリモードユーザが CGI.pm に巨大なファイルのアップロードを 受け取ることを強要することです。 CGI.pm は、例えあなたのスクリプトがアップロードされるファイルを受けることを 予想していなくても、アップロードを受けつけ、それを一時ディレクトリに 格納しようとします。 CGI.pm はそれが終わったとき、自動的にファイルを削除しますが、その間に リモートユーザがサーバのディスク空間をいっぱいにして、他の問題を 起こしてしまうかもしれません。

The best way to avoid denial of service attacks is to limit the amount of memory, CPU time and disk space that CGI scripts can use. Some Web servers come with built-in facilities to accomplish this. In other cases, you can use the shell limit or ulimit commands to put ceilings on CGI resource usage.

サービス不能攻撃を避ける一番よい方法は、CGI スクリプトが使うことが できるメモリ量、CPU 時間、ディスク容量を制限することです。 いつくかの Web サーバはこれを実現する組込み機能を持っています。 その他の場合、シェルの limit または ulimit を CGI の資源使用に上限を設定ために使うことが出来ます。

CGI.pm also has some simple built-in protections against denial of service attacks, but you must activate them before you can use them. These take the form of two global variables in the CGI name space:

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 の値が設定されると、これはファイルのアップロードを完全に 不可能にします。 他のフォームの値は通常通り機能します。

You can use these variables in either of two ways.

これらの変数を以下の二つの方法のどちらかで使うことが出来ます:

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() という名前のサブルーチンの中で 見つけるでしょう。

An attempt to send a POST larger than $POST_MAX bytes will cause param() to return an empty CGI parameter list. You can test for this event by checking cgi_error(), either after you create the CGI object or, if you are using the function-oriented interface, call <param()> for the first time. If the POST was intercepted, then cgi_error() will return the message "413 POST too large".

$POST_MAX バイトよりも大きな POST を送信しようとすると param() は 空の CGI パラメータを返します。 このイベントは CGI オブジェクトを作成した後もしくは関数指向インターフェースを 使っていれば最初に param() を呼び出した後に、cgi_error() を チェックすることで調べることができます。 もし POST が中断されていれば、cgi_error() は "413 POST too large" というメッセージを返します。

This error message is actually defined by the HTTP protocol, and is designed to be returned to the browser as the CGI script's status code. For example:

このエラーメッセージは実際には HTTP プロトコルで定義されており、 そして CGI スクリプトのステータスコードとしてブラウザに返されるように なっています。 例えば:

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

However it isn't clear that any browser currently knows what to do with this status code. It might be better just to create an HTML page that warns the user of the problem.

しかしながら、すべてのブラウザが現在のところ、このステータスで何を すべきか分かっているかははっきりしません。 問題のユーザに警告する HTML ページを作るだけの方がよいかもしれません。

cgi-lib.pl との互換性

To make it easier to port existing programs that use cgi-lib.pl the compatibility routine "ReadParse" is provided. Porting is simple:

cgi-lib.pl を使っている既にあるプログラムの移植を簡単にするため、 互換性ルーチン "ReadParse" が提供されています。 移植は簡単です:

OLD VERSION

旧バージョン

    require "cgi-lib.pl";
    &ReadParse;
    print "The value of the antique is $in{antique}.\n";

NEW VERSION

新バージョン

    use CGI;
    CGI::ReadParse();
    print "The value of the antique is $in{antique}.\n";

CGI.pm's ReadParse() routine creates a tied variable named %in, which can be accessed to obtain the query variables. Like ReadParse, you can also provide your own variable. Infrequently used features of ReadParse, such as the creation of @in and $in variables, are not supported.

CGI.pm の ReadParse() ルーチンは %in という名前の tie された変数を作成します。 それは問い合わせ変数を取得するためにアクセスされます。 ReadParse のように独自の変数を提供することも出来ます。 @in と $in 変数の作成のように、ReadParse のあまり頻繁には使われない機能は サポートされていません。

Once you use ReadParse, you can retrieve the query object itself this way:

一度 ReadParse を使えば、以下のように問い合わせオブジェクトそれ自身を 取り出すことが出来ます:

    $q = $in{CGI};
    print textfield(-name=>'wow',
                        -value=>'does this really work?');

This allows you to start using the more interesting features of CGI.pm without rewriting your old scripts from scratch.

これにより、古いスクリプトを頭から書きなおすことなく、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.

Address bug reports and comments to: lstein@cshl.org. When sending bug reports, please provide the version of CGI.pm, the version of Perl, the name and version of your Web server, and the name and version of the operating system you are using. If the problem is even remotely browser dependent, please provide information about the affected browers as well.

バグレポートとコメントはこちらへ: lstein@cshl.org 。 バグレポートを送るときには CGI.pm のバージョン、Perl のバージョン、 Web サーバの名前とバージョン、そして使用しているオペレーティングシステムの 名前とバージョンを教えてください。 もし問題が離れた場所にあるブラウザにさえも依存していれば、影響される ブラウザについての情報を教えてください。

CREDITS

Thanks very much to:

以下の方々に感謝します:

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
        }

バグ

Please report them.

どうか報告してください。

SEE ALSO

CGI::Carp - provides a Carp implementation tailored to the CGI environment.

CGI::Carp - CGI 環境用に仕立てられた Carp 実装を提供します。

CGI::Fast - supports running CGI applications under FastCGI

CGI::Fast - CGI アプリケーションを FastCGI で動作させることをサポートします。

CGI::Pretty - pretty prints HTML generated by CGI.pm (with a performance penalty)

CGI::Pretty - CGI.pm で生成された HTML を (速度を犠牲にして) 整形します。