=encoding euc-jp

=head1 NAME

=begin original

CGI - Handle Common Gateway Interface requests and responses

=end original

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

=head1 SYNOPSIS

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

=head1 DESCRIPTION

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=head2 PROGRAMMING STYLE

(プログラミングスタイル)

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=head2 CALLING CGI.PM ROUTINES

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

=begin original

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:

=end original

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

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

=begin original

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.

=end original

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

=begin original

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.

=end original

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

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

=begin original

Other such routines are documented below.

=end original

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

=begin original

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:

=end original

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

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

=begin original

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:

=end original

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>

=begin original

HTML tags are described in more detail later.

=end original

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

=begin original

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:

=end original

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

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

=begin original

If you use the B<-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:

=end original

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

=over 4

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

Change the capitalization, e.g. -Values

=end original

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

=item 3.

=begin original

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

=end original

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

=back

=begin original

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:

=end original

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

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

=begin original

This will produce the following nonstandard HTTP header:

=end original

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=head2 CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):

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

     $query = CGI->new;

=begin original

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

=end original

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

=begin original

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

=end original

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

=head2 CREATING A NEW QUERY OBJECT FROM AN INPUT FILE

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

     $query = CGI->new(INPUTFILE);

=begin original

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.

=end original

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

=begin original

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:

=end original

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

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

=begin original

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

=end original

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

=begin original

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
B<restore_parameters()>.  This will (re)initialize the
default CGI object from the indicated file handle.

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

       -or-

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

=head2 FETCHING A LIST OF KEYWORDS FROM THE QUERY:

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

     @keywords = $query->keywords

=begin original

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.

=end original

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

=head2 FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:

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

     @names = $query->param

=begin original

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.

=end original

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

=begin original

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

=end original

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

=head2 FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:

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

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

	      -or-

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

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.

=end original

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

=head2 SETTING THE VALUE(S) OF A NAMED PARAMETER:

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

			      -or-

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

=head2 APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:

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

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

=begin original

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.

=end original

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

=head2 IMPORTING ALL PARAMETERS INTO A NAMESPACE:

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

   $query->import_names('R');

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=head2 DELETING A PARAMETER COMPLETELY:

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=head2 DELETING ALL PARAMETERS:

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

   $query->delete_all();

=begin original

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.

=end original

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

=begin original

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

=end original

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

=head2 HANDLING NON-URLENCODED ARGUMENTS

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

=begin original

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:

=end original

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

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

=begin original

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

=end original

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

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

=begin original

(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.)

=end original

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

=head2 DIRECT ACCESS TO THE PARAMETER LIST:

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=head2 FETCHING THE PARAMETER LIST AS A HASH:

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

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

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

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=head2 SAVING THE STATE OF THE SCRIPT TO A FILE:

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

    $query->save(\*FILEHANDLE)

=begin original

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!

=end original

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

=begin original

The format of the saved file is:

=end original

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

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

=begin original

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

=end original

名前と値の両方が URL エスケープされます。
複数の値を持つ CGI パラメータは名前を繰り返すことにより表すことができます。
セッションレコードはsingle=symbol によって範囲を決められます。
何回も B<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";
   }

=begin original

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

=end original

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

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

=begin original

for further details.

=end original

をご覧下さい。

=begin original

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

=end original

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

=head2 RETRIEVING CGI ERRORS

(CGIエラーの取り出し)

=begin original

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

=end original

ユーザ入力を処理して切る間、特にアップロードされたファイルを処理している
間にエラーが発生することがあります。
これらのエラーが発生したとき、CGI は処理を止め、空のパラメータリストを
返します。
エラーの存在とその性質を I<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;
    }

=begin original

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

=end original

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

=head2 USING THE FUNCTION-ORIENTED INTERFACE

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

=begin original

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.

=end original

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

   use CGI <list of methods>;

=begin original

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 B<param()> and B<header()>
methods, and then use them directly:

=end original

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=over 4

=item B<:cgi>

=begin original

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

=end original

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

=item B<:form>

=begin original

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

=end original

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

=item B<:html2>

=begin original

Import all methods that generate HTML 2.0 standard elements.

=end original

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

=item B<:html3>

=begin original

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

=end original

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

=item B<:html4>

=begin original

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

=end original

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

=item B<:netscape>

=begin original

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

=end original

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

=item B<:html>

=begin original

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

=end original

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

=item B<:standard>

=begin original

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

=end original

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

=item B<:all>

=begin original

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

=end original

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

=back

=begin original

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:

=end original

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

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

=begin original

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

=end original

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

=begin original

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 B<param()>, B<textfield()>,
B<submit()> and the like.  (If you need direct access to the CGI
object, you can find it in the global variable B<$CGI::Q>).  By
importing CGI.pm methods, you can create visually elegant scripts:

=end original

もし状態管理 CGI、またはフォーム作成メソッドのいずれかをインポートすると、
あることを要求するメソッドのいずれかを最初に使ったときに、デフォルトの
CGI オブジェクトが自動的に作成され初期化されます。
これには B<param()>, B<textfield()>, B<submit()> などが含まれます。
(直接 CGI オブジェクトにアクセスする必要があれば、グローバル変数
B<$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;

=head2 PRAGMAS

(プラグマ)

=begin original

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

=end original

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

   use CGI qw/:standard -debug/;

=begin original

The current list of pragmas is as follows:

=end original

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

=over 4

=item -any

=begin original

When you I<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 I<ad hoc> HTML
extension.  This lets you go wild with new and unsupported tags:

=end original

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

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

=begin original

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.

=end original

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

=item -compile

=begin original

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.

=end original

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

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

=begin original

or even

=end original

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

   use CGI qw(-compile :all);

=begin original

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:

=end original

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

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

=begin original

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.

=end original

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

=item -nosticky

=begin original

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.

=end original

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

=begin original

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

=end original

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

=item -tabindex

=begin original

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.

=end original

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

=item -no_undef_params

=begin original

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

=end original

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

=item -no_xhtml

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=item -utf8

=begin original

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:

=end original

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

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

=item -nph

=begin original

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.

=end original

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

=item -newstyle_urls

=begin original

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

=end original

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

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

=begin original

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.

=end original

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

=item -oldstyle_urls

=begin original

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

=end original

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

=item -autoload

=begin original

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.  I<Warning:> when
I<-autoload> is in effect, you cannot use "poetry mode"
(functions without the parenthesis).  Use I<hr()> rather
than I<hr>, or add something like I<use subs qw/hr p header/> 
to the top of your script.

=end original

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

=item -no_debug

=begin original

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:

=end original

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

   use CGI qw(-no_debug :standard);

=item -debug

=begin original

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.

=end original

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

=begin original

See the section on debugging for more details.

=end original

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

=item -private_tempfiles

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

The temporary directory is selected using the following algorithm:

=end original

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

=begin original

    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.

=end original

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

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

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

=begin original

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

=end original

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

=back

=head2 SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS

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

=begin original

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

=end original

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

  print h1('Level 1 Header');

=begin original

produces

=end original

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

  <h1>Level 1 Header</h1>

=begin original

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_I<tag_name>
and end_I<tag_name>, as in:

=end original

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

  print start_h1,'Level 1 Header',end_h1;

=begin original

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

=end original

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

=begin original

Example:

=end original

例:

  use CGI qw/:standard *table start_ul/;

=begin original

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

=end original

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

=over 4

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

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

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

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

=back

=head1 GENERATING DYNAMIC DOCUMENTS

(動的なドキュメント作成)

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=head2 CREATING A STANDARD HTTP HEADER:

(標準HTTPヘッダの作成:)

=begin original

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.

=end original

通常、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');

=begin original

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.

=end original

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

=begin original

The last example shows the named argument style for passing arguments
to the CGI methods using named parameters.  Recognized parameters are
B<-type>, B<-status>, B<-expires>, and B<-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:

=end original

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

    print header(-Content_length=>3002);

=begin original

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

=end original

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

=begin original

	+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

=end original

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

=begin original

The B<-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.

=end original

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

=begin original

The B<-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.

=end original

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

=begin original

The B<-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.

=end original

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

=begin original

The B<-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 B<-type> to "application/octet-stream".

=end original

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

=begin original

The B<-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:

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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:

=end original

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

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

=begin original

will generate

=end original

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

    Ingredients: ham
     eggs
     bacon

=head2 GENERATING A REDIRECTION HEADER

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

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

=begin original

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.  

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

You can also use named arguments:

=end original

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

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

=begin original

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.

=end original

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

=begin original

The B<-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.

=end original

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

=begin original

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

=end original

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

     301 Moved Permanently
     302 Found
     303 See Other

=begin original

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.

=end original

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

=head2 CREATING THE HTML DOCUMENT HEADER

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

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

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

=begin original

All relative links will be interpreted relative to this tag.

=end original

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

=begin original

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

=end original

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

    -target=>"answer_window"

=begin original

All relative links will be interpreted relative to this tag.
You add arbitrary meta information to the header with the B<-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:

=end original

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

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=>'').

=end original

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

=begin original

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

=end original

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

=begin original

The B<-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.

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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


=begin original

JAVASCRIPTING: The B<-script>, B<-noScript>, B<-onLoad>,
B<-onMouseOver>, B<-onMouseOut> and B<-onUnload> parameters are used
to add JavaScript calls to your pages.  B<-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.

=end original

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

=begin original

The B<-onLoad> and B<-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
B<-script> field:

=end original

B<-onLoad>, B<-onUnload> パラメータは、それぞれブラウザによって、
そのページが開かれたときと閉じられたときに実行される JavaScript コードを
示します。
通常これらのパラメータは B<-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);

=begin original

Use the B<-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).

=end original

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

=begin original

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 B<-script> parameter containing one or more of -type, -src, or
-code:

=end original

<script> タグは、"type" と src を含む、多くの属性を持ちます。
後者はソースを持った各ページに散乱させるのではなく、JavaScript コードを
ファイルまたは CGI スクリプトに保管することを可能にするため、特に
興味深いものです。
この属性を使うためには、B<-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;"'}
	       );


=begin original

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:

=end original

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

=begin original

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

=end original

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

=begin original

The old-style positional parameters are as follows:

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

The title

=end original

タイトル

=item 2.

=begin original

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

=end original

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

=item 3.

=begin original

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!

=end original

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

=item 4, 5, 6...

=begin original

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.

=end original

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

=back

=head2 ENDING THE HTML DOCUMENT:

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

	print end_html

=begin original

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

=end original

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

=head2 CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:

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

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

    $the_string = query_string;

=head2 OBTAINING THE SCRIPT'S URL

(スクリプトの 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);

=begin original

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

=end original

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

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

=begin original

You can modify this format with the following named arguments:

=end original

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

=over 4

=item B<-absolute>

=begin original

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

=end original

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

    /path/to/script.cgi

=item B<-relative>

=begin original

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

=end original

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

    script.cgi

=item B<-full>

=begin original

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

=end original

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

=item B<-path> (B<-path_info>)

=begin original

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

=end original

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

=item B<-query> (B<-query_string>)

=begin original

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

=end original

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

=item B<-base>

=begin original

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

=end original

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

=item B<-rewrite>

=begin original

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.

=end original

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

=back

=head2 MIXING POST AND URL PARAMETERS

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

   $color = url_param('color');

=begin original

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
B<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 B<url_param()> method.  Use it in the same way as
B<param()>.  The main difference is that it allows you to read the
parameters, but not set them.

=end original

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

=begin original

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.

=end original

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

=head1 CREATING STANDARD HTML ELEMENTS:

(標準HTML要素の作成:)

=begin original

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.

=end original

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

=begin original

This example shows how to use the HTML methods:

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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;

=head2 PROVIDING ARGUMENTS TO HTML SHORTCUTS

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

=begin original

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

=end original

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

   print hr;  	#  <hr>

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

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

=begin original

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

=end original

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

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

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

=begin original

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:

=end original

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

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

=begin original

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:

=end original

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

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

=head2 THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS

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

=begin original

One of the cool features of the HTML shortcuts is that they are
distributive.  If you give them an argument consisting of a
B<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:

=end original

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

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

=begin original

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

=end original

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

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

=begin original

This is extremely useful for creating tables.  For example:

=end original

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

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

=head2 HTML SHORTCUTS AND LIST INTERPOLATION

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

=begin original

Consider this bit of code:

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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.

=end original

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

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

=begin original

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.

=end original

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

=head2 NON-STANDARD HTML SHORTCUTS

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

=begin original

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

=end original

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

=begin original

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

=end original

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

    print comment('here is my comment');

=begin original

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

=end original

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

    Select
    Tr
    Link
    Delete
    Accept
    Sub

=begin original

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.

=end original

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

=head2 AUTOESCAPING HTML

(HTMLの自動エスケープ)

=begin original

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

=end original

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

=over 4

=item $escaped_string = escapeHTML("unescaped string");

=begin original

Escape HTML formatting characters in a string.

=end original

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

=back

=begin original

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 B<all> characters will
be replaced by their numeric entities, since CGI.pm has no lookup
table for all the possible encodings.

=end original

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

=begin original

C<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 L<perlunitut>, L<perlunifaq> and L<perlunicode> for more
information on how Perl handles the difference between bytes and characters.

=end original

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

=begin original

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

=end original

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

=over 4

=item $charset = charset([$charset]);

=begin original

Get or set the current character set.

=end original

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

=item $flag = autoEscape([$flag]);

=begin original

Get or set the value of the autoescape flag.

=end original

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

=back

=head2 PRETTY-PRINTING HTML

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

=begin original

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 L<CGI::Pretty>, a subclass
contributed by Brian Paulsen.

=end original

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

=head1 CREATING FILL-OUT FORMS:

(フォームの作成:)

=begin original

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

=end original

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

=begin original

I<Another note> The default values that you specify for the forms are only
used the B<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.  

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

=begin original

<p>

=end original

<p>

=head2 CREATING AN ISINDEX TAG

(ISINDEX タグの作成)

   print isindex(-action=>$action);

	 -or-

   print isindex($action);

=begin original

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.

=end original

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

=head2 STARTING AND ENDING A FORM

(フォームの開始と終了)

    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;

=begin original

start_form() will return a <form> tag with the optional method,
action and form encoding that you specify.  The defaults are:

=end original

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.

=begin original

end_form() returns the closing </form> tag.  

=end original

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

=begin original

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:

=end original

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

=begin original

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

=end original

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

=over 4

=item B<application/x-www-form-urlencoded>

=begin original

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 B<&CGI::URL_ENCODED>.

=end original

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

=item B<multipart/form-data>

=begin original

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 B<&CGI::MULTIPART>

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=back

=begin original

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
B<start_multipart_form()> instead of B<start_form()>.  The
method B<end_multipart_form()> is an alias to B<end_form()>.

=end original

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

=begin original

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

=end original

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

=begin original

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.

=end original

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

=head2 FORM ELEMENTS

(form 要素)

=begin original

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:

=end original

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

=over 4

=item B<-name>

=begin original

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

=end original

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

=item B<-value>, B<-values>

=begin original

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.

=end original

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

=item B<-tabindex>

=begin original

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.

=end original

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

=item B<-id>

=begin original

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

=end original

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

=item B<-override>

=begin original

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

=end original

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

=item B<-onChange>, B<-onFocus>, B<-onBlur>, B<-onMouseOver>, B<-onMouseOut>, B<-onSelect>

=begin original

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

=end original

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

=back

=begin original

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

=end original

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

=head2 CREATING A TEXT FIELD

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

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

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

=begin original

textfield() will return a text input field. 

=end original

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

=over 4

=item B<Parameters>

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

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

=end original

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

=item 3.

=begin original

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

=end original

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

=item 4.

=begin original

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

=end original

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

=back

=begin original

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:

=end original

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

       $value = param('foo');

=begin original

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

=end original

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

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

=head2 CREATING A BIG TEXT FIELD

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

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

	-or

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

=begin original

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.

=end original

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

=head2 CREATING A PASSWORD FIELD

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

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

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

=begin original

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

=end original

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

=head2 CREATING A FILE UPLOAD FIELD

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

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

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

=begin original

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

=end original

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

=over 4

=item B<Parameters>

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

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

=end original

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

=begin original

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.

=end original

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

=item 3.

=begin original

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

=end original

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

=item 4.

=begin original

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

=end original

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

=back

=begin original

JAVASCRIPTING: The B<-onChange>, B<-onFocus>, B<-onBlur>,
B<-onMouseOver>, B<-onMouseOut> and B<-onSelect> parameters are
recognized.  See textfield() for details.

=end original

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

=head2 PROCESSING A FILE UPLOAD FIELD

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

=head3 Basics

(基本)

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

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

=begin original

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
I<user's> machine, and is unrelated to the name of the temporary file
that CGI.pm creates during upload spooling (see below).

=end original

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

=begin original

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.

=end original

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

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

=begin original

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.

=end original

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

=head3 Accessing the temp files directly

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

=begin original

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:

=end original

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

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

=begin original

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.

=end original

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

=head3 Handling interrupted file uploads

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

=begin original

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

=end original

ときどきアップロードされたファイルを解析している途中に問題が発生します。
通常それはユーザがアップロードが完了する前に "Stop" を押したときにおこります。
この場合、CGI.pm はアップロードされたファイルの名前の代りに undef を、
I<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;
   }

=begin original

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

=end original

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

=head3 Progress bars for file uploads and avoiding temp files

=begin original

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.

=end original

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

=begin original

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

=end original

これは L<Apache::Request> で提供される UPLOAD_HOOK 機能ととてもよく
似ていますが、コールバックへ渡される最初の引数が L<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";
 }

=begin original

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

=end original

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

=begin original

The C<< $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.

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

=head3 Troubleshooting file uploads on Windows

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

=begin original

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.

=end original

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

=head3 Older ways to process file uploads

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=head2 CREATING A POPUP MENU

(ポップアップメニューの作成)

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

=begin original

popup_menu() creates a menu.

=end original

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

=over 4

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

The required second argument (-values) is an array B<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".

=end original

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

=item 3.

=begin original

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.

=end original

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

=item 4.

=begin original

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

=end original

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

=item 5.

=begin original

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.

=end original

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

=back

=begin original

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

=end original

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

      $popup_menu_value = param('menu_name');

=head2 CREATING AN OPTION GROUP

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

=begin original

Named parameter style

=end original

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

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

=begin original

optgroup() creates an option group within a popup menu.

=end original

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

=over 4

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

The required second argument (B<-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).

=end original

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

=item 3.

=begin original

The optional third parameter (B<-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.

=end original

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

=item 4.

=begin original

An optional fourth parameter (B<-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.

=end original

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

=item 5.

=begin original

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.

=end original

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

=begin original

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

=end original

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

=item 6.

=begin original

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.

=end original

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

=back

=head2 CREATING A SCROLLING LIST

(スクローリングリストの作成)

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

=begin original

scrolling_list() creates a scrolling list.  

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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.

=end original

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

=item 2.

=begin original

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.

=end original

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

=item 3.

=begin original

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

=end original

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

=item 4.

=begin original

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.

=end original

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

=item 5.

=begin original

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.

=end original

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

=item 6.

=begin original

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.

=end original

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

=begin original

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:

=end original

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

      @selected = param('list_name');

=back

=head2 CREATING A GROUP OF RELATED CHECKBOXES

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

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


=begin original

checkbox_group() creates a list of checkboxes that are related
by the same name.

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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.

=end original

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

=item 2.

=begin original

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.

=end original

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

=item 3.

=begin original

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.

=end original

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

=back

=begin original

The optional B<-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.

=end original

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

=begin original

The optional parameters B<-rows>, and B<-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.

=end original

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

=begin original

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

=end original

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

=begin original

The optional B<-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.

=end original

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

=begin original

The optional B<-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:

=end original

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

=begin original

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

=end original

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

=begin original

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:

=end original

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

      @turned_on = param('group_name');

=begin original

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:

=end original

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

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

=head2 CREATING A STANDALONE CHECKBOX

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

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

	-or-

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

=begin original

checkbox() is used to create an isolated checkbox that isn't logically
related to any others.

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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.

=end original

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

=item 2.

=begin original

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

=end original

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

=item 3.

=begin original

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

=end original

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

=item 4.

=begin original

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

=end original

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

=back

=begin original

The value of the checkbox can be retrieved using:

=end original

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

    $turned_on = param('checkbox_name');

=head2 CREATING A RADIO BUTTON GROUP

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

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

=begin original

radio_group() creates a set of logically-related radio buttons
(turning one member of the group on turns the others off)

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

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 I<reference> in the second argument, either
using an anonymous array, as shown, or by referencing a named array as
in "\@foo".

=end original

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

=item 3.

=begin original

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.

=end original

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

=item 4.

=begin original

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

=end original

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

=item 5.

=begin original

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.

=end original

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

=back


=begin original

All modern browsers can take advantage of the optional parameters
B<-rows>, and B<-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.

=end original

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

=begin original

To include row and column headings in the returned table, you
can use the B<-rowheaders> and B<-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.

=end original

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

=begin original

The optional B<-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:

=end original

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

=begin original

The optional B<-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.

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

      $which_radio_button = param('group_name');

=begin original

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:

=end original

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

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

=head2 CREATING A SUBMIT BUTTON 

(サブミットボタンの作成)

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

	-or-

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

=begin original

submit() will create the query submission button.  Every form
should have one of these.

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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.  

=end original

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

=item 2.

=begin original

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.

=end original

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

=item 3.

=begin original

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.

=end original

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

=back

=begin original

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

=end original

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

     $which_one = param('button_name');

=head2 CREATING A RESET BUTTON

(リセットボタンの作成)

   print reset

=begin original

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.

=end original

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

=begin original

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

=end original

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

=head2 CREATING A DEFAULT BUTTON

(デフォルトボタンの作成)

   print defaults('button_label')

=begin original

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.

=end original

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

=head2 CREATING A HIDDEN FIELD

(隠しフィールドの作成)

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

		-or-

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

=begin original

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.

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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

=end original

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

=item 2.  

=begin original

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

=end original

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

=back

=begin original

Fetch the value of a hidden field this way:

=end original

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

     $hidden_value = param('hidden_name');

=begin original

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:

=end original

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

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

=head2 CREATING A CLICKABLE IMAGE BUTTON

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

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

	-or-

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

=begin original

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.

=end original

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

=over 4

=item B<Parameters:>

=item 1.

=begin original

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

=end original

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

=item 2.

=begin original

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

=end original

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

=item 3.

=begin original

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

=end original

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

=back

=begin original

Fetch the value of the button this way:

=end original

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

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

=head2 CREATING A JAVASCRIPT ACTION BUTTON

(JavaScript アクションボタンの作成)

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

	-or-

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

=begin original

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

=end original

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

=head1 HTTP COOKIES

(HTTP クッキー)

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=over 4

=item 1. an expiration time

=begin original

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.

=end original

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

=item 2. a domain

=begin original

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.

=end original

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

=item 3. a path

=begin original

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.

=end original

クッキークリプトの 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 スクリプトにクッキーが送信させます。

=item 4. a "secure" flag

=begin original

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.

=end original

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

=back

=begin original

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

=end original

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

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

=begin original

B<cookie()> creates a new cookie.  Its parameters include:

=end original

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

=over 4

=item B<-name>

=begin original

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.

=end original

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

=item B<-value>

=begin original

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:

=end original

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

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

=item B<-path>

=begin original

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

=end original

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

=item B<-domain>

=begin original

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

=end original

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

=item B<-expires>

=begin original

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

=end original

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

	"+1h"  one hour from now

=item B<-secure>

=begin original

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

=end original

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

=back

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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.

=end original

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

=begin original

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:

=end original

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

=begin original

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

=end original

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

  @cookies = cookie();

=begin original

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

=end original

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

=head1 WORKING WITH FRAMES

(フレームの利用)

=begin original

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:

=end original

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

=over 4

=item 1. Create a <Frameset> document

=begin original

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.

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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 C<< <frame> >> documentation for details.

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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.

=end original

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

=back

=begin original

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.

=end original

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

=head1 SUPPORT FOR JAVASCRIPT

(JavaScript 対応)

=begin original

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.

=end original

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

=begin original

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:

=end original

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

=over 4

=item B<onLoad>

=begin original

The browser is loading the current document. Valid in:

=end original

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

     + The HTML <BODY> section only.

=item B<onUnload>

=begin original

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

=end original

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

     + The HTML <BODY> section only.

=item B<onSubmit>

=begin original

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:

=end original

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

     + Forms only.

=item B<onClick>

=begin original

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

=end original

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

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

=item B<onChange>

=begin original

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

=end original

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

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

=item B<onFocus>

=begin original

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

=end original

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

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

=item B<onBlur>

=begin original

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

=end original

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

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

=item B<onSelect>

=begin original

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

=end original

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

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

=item B<onMouseOver>

=begin original

The mouse has moved over an element.

=end original

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

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

=item B<onMouseOut>

=begin original

The mouse has moved off an element.

=end original

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

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

=back

=begin original

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: 

=end original

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

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

=begin original

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.

=end original

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

=begin original

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: 

=end original

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

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

=begin original

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

=end original

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

=head1 LIMITED SUPPORT FOR CASCADING STYLE SHEETS

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

=begin original

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 B<-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 B<-src> or
B<-code>.  B<-src> points to a URL where an externally-defined
stylesheet can be found.  B<-code> points to a scalar value to be
incorporated into a <style> section.  Style definitions in B<-code>
override similarly-named ones in B<-src>, hence the name "cascading."

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

Or define styles on the fly with the B<-style> parameter:

=end original

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

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

=begin original

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

=end original

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

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

=begin original

Note that you must import the ":html3" definitions to have the
B<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.

=end original

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

=begin original

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

=end original

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

=begin original

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:

=end original

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

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

=begin original

This will generate an HTML header that contains this:

=end original

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

=begin original

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

=end original

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

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

=begin original

This will give:

=end original

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

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

=begin original

<p>

=end original

<p>

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=head1 DEBUGGING

(デバッグ)

=begin original

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:

=end original

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

    your_script.pl keyword1 keyword2 keyword3

=begin original

or this:

=end original

あるいは:

   your_script.pl keyword1+keyword2+keyword3

=begin original

or this:

=end original

あるいは:

    your_script.pl name1=value1 name2=value2

=begin original

or this:

=end original

あるいは:

    your_script.pl name1=value1&name2=value2

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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:

=end original

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

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

=begin original

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 (?):

=end original

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

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

=head2 DUMPING OUT ALL THE NAME/VALUE PAIRS

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

=begin original

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:

=end original

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

    print Dump

=begin original

Produces something that looks like:

=end original

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

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

=begin original

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:

=end original

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

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

=head1 FETCHING ENVIRONMENT VARIABLES

(環境変数の取り出し)

=begin original

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

=end original

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

=over 4

=item B<Accept()>

=begin original

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.

=end original

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

=begin original

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

=end original

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

=item B<raw_cookie()>

=begin original

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.

=end original

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

=begin original

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

=end original

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

=item B<user_agent()>

=begin original

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

=end original

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

=item B<path_info()>

=begin original

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

=end original

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

=begin original

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.

=end original

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

=item B<path_translated()>

=begin original

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

=end original

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

=begin original

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

=end original

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

=item B<remote_host()>

=begin original

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

=end original

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

=item B<remote_addr()>

=begin original

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

=end original

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

=item B<script_name()>

=begin original

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

=end original

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

=item B<referer()>

=begin original

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

=end original

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

=item B<auth_type ()>

=begin original

Return the authorization/verification method in use for this
script, if any.

=end original

もしあれば、このスクリプトのために使われた、
authorization/verification (認証/検証) 方法を返します。

=item B<server_name ()>

=begin original

Returns the name of the server, usually the machine's host
name.

=end original

サーバの名前、通常はマシンのホスト名を返します。

=item B<virtual_host ()>

=begin original

When using virtual hosts, returns the name of the host that
the browser attempted to contact

=end original

バーチャルホストを使っているとき、ブラウザがコンタクトしようとしたホストの
名前を返します。

=item B<server_port ()>

=begin original

Return the port that the server is listening on.

=end original

サーバソフトウェアとバージョン番号を返します。

=item B<virtual_port ()>

=begin original

Like server_port() except that it takes virtual hosts into account.
Use this when running with virtual hosts.

=end original

server_port() と似ていますが、これは仮想ホストも考慮に入れます。
仮想ホストで実行しているときに使ってください。

=item B<server_software ()>

=begin original

Returns the server software and version number.

=end original

サーバソフトウェアとバージョン番号を返します。

=item B<remote_user ()>

=begin original

Return the authorization/verification name used for user
verification, if this script is protected.

=end original

このスクリプトが保護されていれば、ユーザ検証に使われた
authorization/verification 名を返します。

=item B<user_name ()>

=begin original

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!

=end original

さまざまな異なる技術を使ってリモートユーザの名前を取得しようとします。
これは Mosaic のような古いブラウザでのみ機能します。
新しいブラウザはプライバシーの理由からユーザ名を報告しません!

=item B<request_method()>

=begin original

Returns the method used to access your script, usually
one of 'POST', 'GET' or 'HEAD'.

=end original

スクリプトにアクセスするために使われたメソッドを返します。
通常は 'POST', 'GET', 'HEAD' のどれかです。

=item B<content_type()>

=begin original

Returns the content_type of data submitted in a POST, generally 
multipart/form-data or application/x-www-form-urlencoded

=end original

POST で送信されてきたデータの content_type を返します。
一般には multipart/form-data または application/x-www-form-urlencoded です。

=item B<http()>

=begin original

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.

=end original

引数なしで呼ばれると、それぞれリクエストでの似たような
HTTP ヘッダフィールドに対応する、HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE,
HTTP_ACCEPT_CHARSET のようなものが入った環境変数のリストを返します。
HTTP ヘッダフィールドの名前付きで呼ばれると、その値を返します。
大文字／小文字、アンダースコアの代わりにハイフンを使うことは区別されません。

=begin original

For example, all three of these examples are equivalent:

=end original

例えば、この三つの例はすべて同値です:

   $requested_language = http('Accept-language');
   $requested_language = http('Accept_language');
   $requested_language = http('HTTP_ACCEPT_LANGUAGE');

=item B<https()>

=begin original

The same as I<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.

=end original

I<http()> と同じ。
しかし SSL プロトコルが有効なときに現れる HTTPS 環境変数を扱います。
SSL がオンになっているかどうかを判定するためにも使うことができます。

=back

=head1 USING NPH SCRIPTS

(NPHスクリプトの使い方)

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=begin original

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, B<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.

=end original

Microsoft Internet Information Server は NPH モードを必要とします。
version 2.30 では、CGI.pm は IIS の元で実行されたとき自動的に検知し、
自分自身でこのモードにします。
手動でこのモードにする必要はありません。
しかしそうしたからといって、何も問題はありません。
しかしながらサービスパック 6 を提供しているのであれば、注意してください。
クッキーが設定されている間、リダイレクトするという機能も含めて、
NPH スクリプトの機能の多くが Microsoft からの特別なパッチなしには IIS では
B<まったく機能しません>。
この 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 アプリケーションからの
解析されないヘッダの除去)

=over 4

=item In the B<use> statement 

=begin original

Simply add the "-nph" pragmato the list of symbols to be imported into
your script:

=end original

スクリプトにインポートされるシンボルのリストに単に "-nph" プラグマを
追加してください:

      use CGI qw(:standard -nph)

=item By calling the B<nph()> method:

=begin original

Call B<nph()> with a non-zero parameter at any point after using CGI.pm in your program.

=end original

CGI.pm をプログラムで使った後のどこかの時点で、非 0 のパラメータで
B<nph()> を呼び出してください。

      CGI->nph(1)

=item By using B<-nph> parameters

=begin original

in the B<header()> and B<redirect()>  statements:

=end original

B<header()> と B<redirect()> 文で:

      print header(-nph=>1);

=back

=head1 Server Push

(サーバープッシュ)

=begin original

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.

=end original

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

=begin original

Here is a simple script that demonstrates server push:

=end original

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

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

=begin original

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

=end original

このスクリプトは B<multipart_init()> を呼ぶことによってサーバプッシュを
初期化しています。
そして B<multipart_start()> を呼ぶことによって新しい
マルチパートセクションを始め、現在のローカルタイムを出力し、
B<multipart_end()> でマルチパートセクションを終わらせているループに
入ります。
そして 1 秒スリープした後、再び開始します。
最後の繰り返しでは B<multipart_end()> ではなく B<multipart_final()> で
マルチパートセクションを終了させています。

=over 4

=item multipart_init()

  multipart_init(-boundary=>$boundary);

=begin original

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.

=end original

マルチパートシステムを初期化します。
-boundary 引数はドキュメントの部分を分割するために使われる
MIME バウンダリ文字列を指定します。
指定されなければ、CGI.pm  はあなたに代わって合理的なバウンダリを選択します。

=item multipart_start()

  multipart_start(-type=>$type)

=begin original

Start a new part of the multipart document using the specified MIME
type.  If not specified, text/html is assumed.

=end original

指定された MIME タイプを使ってマルチパートドキュメントの新しい部分を
開始します。
指定されなければ、text/html が想定されます。

=item multipart_end()

  multipart_end()

=begin original

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().

=end original

部分(part)を終わらせます。
multipart_end() の代わりに multipart_final() を呼ばなければならない
マルチパートドキュメントの最後の部分の終わりを除いて、
multipart_start() を呼ぶ毎に multpart_end() を呼ぶ事を忘れてはいけません。

=item multipart_final()

  multipart_final()

=begin original

End all parts.  You should call multipart_final() rather than
multipart_end() at the end of the last part of the multipart document.

=end original

全ての部分を終了させます。
マルチパートドキュメントの最後の部分の終了のときには
multipart_end() ではなく、multipart_final() を呼ばなければなりません。

=back

=begin original

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

=end original

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

=head1 Avoiding Denial of Service Attacks

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

=begin original

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.

=end original

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

=begin original

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.

=end original

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

=begin original

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 I<limit> or I<ulimit>
commands to put ceilings on CGI resource usage.

=end original

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


=begin original

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:

=end original

CGI.pm もサービス不能攻撃に対するいくかの簡単な組込まれた保護を
持っていますが、使えるようにするには有効にしなければなりません。
これらは CGI 名前空間での二つのグローバル変数の形を取ります:

=over 4

=item B<$CGI::POST_MAX>

=begin original

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.

=end original

負でない整数が設定されると、この変数は POST されるサイズの上限をバイト数で
設定します。
CGI.pm は上限よりも大きい POST を検知すると、エラーメッセージとともにすぐに
exit します。
この値は通常の POST とマルチパート POST の両方に影響を与えます。
つまりファイルアップロードの最大の大きさも制限するということです。
これは 1 メガバイトのように合理的に大きい値を設定しなければいけません。

=item B<$CGI::DISABLE_UPLOADS>

=begin original

If set to a non-zero value, this will disable file uploads
completely.  Other fill-out form values will work as usual.

=end original

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

=back

=begin original

You can use these variables in either of two ways.

=end original

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

=over 4

=item B<1. On a script-by-script basis>

(スクリプト毎に)

=begin original

Set the variable at the top of the script, right after the "use" statement:

=end original

"use" 文のすぐ後に、スクリプトの先頭でその変数を設定します:

    use CGI qw/:standard/;
    use CGI::Carp 'fatalsToBrowser';
    $CGI::POST_MAX=1024 * 100;  # max 100K posts
    $CGI::DISABLE_UPLOADS = 1;  # no uploads

=item B<2. Globally for all scripts>

(全てのスクリプトに対してグローバルに)

=begin original

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().

=end original

CGI.pm を開き $POST_MAX と $DISABLE_UPLOADS のための定義を見つけ、
それを望んでいる値に設定します。
ファイルの先頭の近くinitialize_globals() という名前のサブルーチンの中で
見つけるでしょう。

=back

=begin original

An attempt to send a POST larger than $POST_MAX bytes will cause
I<param()> to return an empty CGI parameter list.  You can test for
this event by checking I<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".

=end original

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

=begin original

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:

=end original

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

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

=begin original

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.

=end original

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

=head1 COMPATIBILITY WITH CGI-LIB.PL

(cgi-lib.pl との互換性)

=begin original

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

=end original

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

=begin original

OLD VERSION

=end original

旧バージョン

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

=begin original

NEW VERSION

=end original

新バージョン

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

=begin original

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.

=end original

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

=begin original

Once you use ReadParse, you can retrieve the query object itself
this way:

=end original

一度 ReadParse を使えば、以下のように問い合わせオブジェクトそれ自身を
取り出すことが出来ます:

    $q = $in{CGI};
    print textfield(-name=>'wow',
			-value=>'does this really work?');

=begin original

This allows you to start using the more interesting features
of CGI.pm without rewriting your old scripts from scratch.

=end original

これにより、古いスクリプトを頭から書きなおすことなく、CGI.pm のより興味深い
機能を使い始めることが出来ます。

=head1 AUTHOR INFORMATION

The CGI.pm distribution is copyright 1995-2007, Lincoln D. Stein.  It is
distributed under GPL and the Artistic License 2.0.

=begin original

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.

=end original

バグレポートとコメントはこちらへ: lstein@cshl.org 。
バグレポートを送るときには CGI.pm のバージョン、Perl のバージョン、
Web サーバの名前とバージョン、そして使用しているオペレーティングシステムの
名前とバージョンを教えてください。
もし問題が離れた場所にあるブラウザにさえも依存していれば、影響される
ブラウザについての情報を教えてください。

=head1 CREDITS

=begin original

Thanks very much to:

=end original

以下の方々に感謝します:

=over 4

=item Matt Heffron (heffron@falstaff.css.beckman.com)

=item James Taylor (james.taylor@srs.gov)

=item Scott Anguish <sanguish@digifix.com>

=item Mike Jewell (mlj3u@virginia.edu)

=item Timothy Shimmin (tes@kbs.citri.edu.au)

=item Joergen Haegg (jh@axis.se)

=item Laurent Delfosse (delfosse@delfosse.com)

=item Richard Resnick (applepi1@aol.com)

=item Craig Bishop (csb@barwonwater.vic.gov.au)

=item Tony Curtis (tc@vcpc.univie.ac.at)

=item Tim Bunce (Tim.Bunce@ig.co.uk)

=item Tom Christiansen (tchrist@convex.com)

=item Andreas Koenig (k@franz.ww.TU-Berlin.DE)

=item Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)

=item Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)

=item Stephen Dahmen (joyfire@inxpress.net)

=item Ed Jordan (ed@fidalgo.net)

=item David Alan Pisoni (david@cnation.com)

=item Doug MacEachern (dougm@opengroup.org)

=item Robin Houston (robin@oneworld.org)

=item ...and many many more...

(…そしてもっともっとたくさんの人々…)

=begin original

for suggestions and bug fixes.

=end original

提案とバグ修正をしてくれました。

=back

=head1 A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT

(単純なフォームベースのスクリプトの完全な例)

	#!/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
	}

=head1 BUGS

=begin original

Please report them.

=end original

どうか報告してください。

=head1 SEE ALSO

=begin original

L<CGI::Carp> - provides a L<Carp> implementation tailored to the CGI environment.

=end original

L<CGI::Carp> - CGI 環境用に仕立てられた L<Carp> 実装を提供します。

=begin original

L<CGI::Fast> - supports running CGI applications under FastCGI

=end original

L<CGI::Fast> - CGI アプリケーションを FastCGI で動作させることをサポートします。

=begin original

L<CGI::Pretty> - pretty prints HTML generated by CGI.pm (with a performance penalty)

=end original

L<CGI::Pretty> - CGI.pm で生成された HTML を (速度を犠牲にして) 整形します。

=begin meta

Translated: 川合孝典 <GCD00051@nifty.ne.jp> (2.89)
Updated: SHIRAKATA Kentaro <argrath@ub32.org> (3.49)
Status: completed

=end meta

=cut