=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('some','contents');

some contents

h1({-align=>left});

h1({-align=>left},'contents');

contents

=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. This will (re)initialize the default CGI object from the indicated file handle. =end original 関数指向インターフェースを使っていて、CGI 状態をファイルハンドルで 初期化したければ、Bでおこないます。 これはデフォルトの 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 search, the parsed keywords can be obtained as an array using the keywords() method. =end original 検索の結果としてスクリプトが呼び出されれば、解析されたキーワードは 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 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()メソッドはパラメータ名をリストで返します。 もしスクリプトがスクリプトとして呼び出され、アンパサンドのない 文字列が入っていれば (例えば、"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. As of version 2.20, this name has been removed completely to avoid conflict with the built-in Perl module B operator. =end original 注意 2: 古いバージョンでは、このメソッドは B と呼ばれていました。 バージョン 2.20 から、組み込みの Perl モジュール B 演算子と ぶつかることを避けるため、この名前は完全に削除されました。 =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 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 を呼び出すことにより、それへの 直接のリファレンスを取得出来ます。 これは名前付きパラメータへの配列リファレンスを返し、これは好きなように 操作できます。 =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. 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 を呼ぶことにより、複数のレコードを書き出し、読み戻すことが 出来ます。 追記 (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. =end original 関数指向 (非OO) からこの関数を使いたいのであれば、エクスポートされる このメソッドの名前は B です。 =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 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 関数を使って調べることが出来ます。 エラーメッセージは 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. Be ready for this! =end original 関数指向インターフェース (次のセクションをご覧下さい) を使うとき、エラーは 最初に I を呼んだときにだけ発生します。 これに備えてください! =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 ; =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 and B methods, and then use them directly: =end original リストに入れられたメソッドは現在のパッケージにインポートされます; CGI オブジェクトを最初に作成することなく直接呼び出すことが出来ます。 この例ではどのように B と B メソッドをインポートし、 それらを直接使うかを示しています: 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, B and the like. =end original B, B のような、CGI を扱うすべてのメソッドを インポートします。 =item B<:form> =begin original Import all fill-out form generating methods, such as B. =end original B のような、フォームを作成するメソッドをインポートします。 =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 , and ). =end original HTML 3.0 標準要素を作成するすべてのメソッドをインポートします。 (
, , のような) =item B<:html4> =begin original Import all methods that generate HTML 4 elements (such as , and ). =end original HTML 4 標準要素を作成するすべてのメソッドをインポートします。 (, , のような) =item B<:netscape> =begin original Import the , and
tags. =end original , ,
タグをインポートします。 =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 (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 は という新しいタグを発表したとします (これはマシンをリブートするまで、ユーザのデスクトップを回転する斜線で いっぱいにします)。 これをすぐに使い始めるのに、新しいバージョンの 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 use the standard L syntax for specifying load symbols. This may change in the future. =end original 実行スピードの点から、CGI.pm はロードシンボルを指定するための標準の L の書式を使わないことに注意してください。 これは将来変更されるかもしれません。 =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, B, B 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, B, B などが含まれます。 (直接 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, 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 HTML extension. This lets you go wild with new and unsupported tags: =end original I を使うとき、問い合わせオブジェクトが理解しない全ての メソッドは HTML タグとして解釈されます。 これにより次の I<アドホックな> HTML 拡張をサポートすることが出来ます。 これは新しく、まだサポートされていないタグを自由に使わせてくれます: use CGI qw(-any); $q=CGI->new; print $q->gradient({speed=>'fast',start=>'red',end=>'blue'}); =begin original Since using any causes any mistyped method name to be interpreted as an HTML tag, use it with care or not at all. =end original any を使うと打ち間違えたどんなメソッド名も 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 for this feature. =end original デフォルトでは、CGI.pm バージョン 2.69 以降は XHTML (http://www.w3.org/TR/xhtml1/) を出力します。 -no_xhtml プラグマは、この機能を止めます。 この機能について Michalis Kabrianis に感謝します。 =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 when I<-autoload> is in effect, you cannot use "poetry mode" (functions without the parenthesis). Use I rather than I
, or add something like I to the top of your script. =end original プログラム内の理解されないすべての関数が可能な評価のために CGI.pm が 参照されるよう autoloader をオーバーライドします。 これにより、それらをシンボルテーブルに加えることなく、すべての CGI.pm 関数を 使うことが出来ます。 これはメモリ消費を心配するmod_perlユーザに関連します。 I<警告:> I<-autoload> が有効なとき"詩的モード(poetry mode)" (かっこのない 関数) を使うことは出来ません。 I
ではなくI を使うか、I のようなものを スクリプトの先頭に加えてください。 =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 は 以下のものを作成します。

Level 1 Header

=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 and end_I, 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 and end_I functions are not generated automatically when you I. However, you can specify the tags you want to generate I functions for by putting an asterisk in front of their name, or, alternatively, requesting either "start_I" or "end_I" in the import list. =end original いくつかの例外がありますが (下記で説明)、start_I<タグ名> と end_I<タグ名>関数は I したときに自動的に作成されません。 しかし、その名前の前にアスタリスクを置くか、あるいは代わりに "start_I<タグ名>" や "end_I<タグ名>" をインポートリストに 要求することによって、I 関数を作成したいタグを 指定することができます。 =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
tag) =item 2. end_table() (generates a
tag) =item 3. start_ul() (generates a
    tag) =item 4. end_ul() (generates a
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 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 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 tag. Additional parameters must be proceeded by a hyphen. =end original このメソッドは閉じられた HTML ヘッダと開かれた タグを返します。 全てのパラメータはオプションです。 名前付きパラメータ形式で、理解されるパラメータは -title, -author, -base, -xbase, -target です (下記の説明をご覧ください) 。 非公式の BGCOLOR 属性ような、指定されたすべての追加のパラメータは タグに追加されます。 追加のパラメータは前にハイフンをつけなければいけません。 =begin original The argument B<-xbase> allows you to provide an HREF for the tag different from the current location, as in =end original 引数 B<-xbase> は以下のように、 タグを現在の位置から変えるために 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 =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 tags that look something like this: =end original すべての相対リンクはこのタグのからの相対だと解釈されます。 B<-meta> 引数でヘッダに任意のメタ情報を追加します。 この引数はメタ情報の名前/値の組が入ったハッシュへのリファレンスを想定します。 これらは以下のような、ヘッダでの一連の タグに変わります: =begin original To create an HTTP-EQUIV type of tag, use B<-head>, described below. =end original タグの 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 tag. For example: =end original B<-lang> 引数は タグに 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 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 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> 引数が使われると、 宣言が HTML ヘッダの 先頭に置かれます。 この宣言の唯一の目的は文字集合エンコーディングを宣言することです。 -declare_xml なしの場合、出力される HTML にはエンコーディングを指定した タグが含まれ、HTML が多くのバリデータを通過するようにします。 -declare_xml のデフォルトは偽です。 =begin original You can place other arbitrary HTML elements to the section with the B<-head> tag. For example, to place the rarely-used element in the head section, use this: =end original B<-head> タグで他の任意の HTML 要素を セクションに置くことができます。 例えば、あまり使われない 要素を HEAD セクションに置くためには、 これを使ってください: print start_html(-head=>Link({-rel=>'next', -href=>'http://www.capricorn.com/s2.html'})); =begin original To incorporate multiple HTML elements into the section, just pass an array reference: =end original 複数の HTML 要素を セクションに入れるためには、単に配列リファレンスを 渡してください: 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 tag: =end original そして、これが HTTP-EQIV タグの作成方法です: 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