=encoding euc-jp =head1 NAME =begin original HTML::Form - Class that represents an HTML form element =end original HTML::Form - HTML フォーム要素を表現するクラス =head1 SYNOPSIS use HTML::Form; $form = HTML::Form->parse($html, $base_uri); $form->value(query => "Perl"); use LWP::UserAgent; $ua = LWP::UserAgent->new; $response = $ua->request($form->click); =head1 DESCRIPTION =begin original Objects of the C class represents a single HTML CformE ... E/formE> instance. A form consists of a sequence of inputs that usually have names, and which can take on various values. The state of a form can be tweaked and it can then be asked to provide C objects that can be passed to the request() method of C. =end original C クラスのオブジェクトは一つの HTML の CformE ... E/formE> 実体を表現します。 一つのフォームは、普通は名前の付いている、様々な値を取ることができる いくつかの入力で構成されます。 フォームの状態は修正でき、それから C の request() メソッドに 渡せる C オブジェクトを取得できます。 =begin original The following methods are available: =end original 以下のメソッドが利用可能です: =over 4 =item @forms = HTML::Form->parse( $response ) =item @forms = HTML::Form->parse( $html_document, $base ) =item @forms = HTML::Form->parse( $html_document, %opt ) =begin original The parse() class method will parse an HTML document and build up C objects for each
element found. If called in scalar context only returns the first . Returns an empty list if there are no forms to be found. =end original parse() クラスメソッドは HTML 文書をパースして、 要素が見つかる毎に C オブジェクトを構築します。 スカラコンテキストで呼び出すと、最初の だけが返されます。 フォームが見つからなかった場合は空リストが返されます。 =begin original The $base is the URI used to retrieve the $html_document. It is needed to resolve relative action URIs. If the document was retrieved with LWP then this this parameter is obtained from the $response->base() method, as shown by the following example: =end original $base は $html_document の取得に使われた URI です。 これは相対アクション URI を解決するのに必要です。 LWP を使って文書が取得されると、以下の例のように、 この引数が $response->base() から取られます: my $ua = LWP::UserAgent->new; my $response = $ua->get("http://www.example.com/form.html"); my @forms = HTML::Form->parse($response->decoded_content, $response->base); =begin original The parse() method can parse from an C object directly, so the example above can be more conveniently written as: =end original parse() メソッドは C オブジェクトから直接パースすることも できるので、上述の例は以下のようにしてより便利になります: my $ua = LWP::UserAgent->new; my $response = $ua->get("http://www.example.com/form.html"); my @forms = HTML::Form->parse($response); =begin original Note that any object that implements a decoded_content() and base() method with similar behaviour as C will do. =end original C と同じような振る舞いをする decoded_content() メソッドと base() メソッドが実装されているどのような オブジェクトでも行えることに注意してください。 =begin original Finally options might be passed in to control how the parse method behaves. The following options are currently recognized: =end original 最後に、どのようにパースメソッドが振る舞うかを制御するオプションを 渡せます。 現在以下のオプションを認識します: =over =item C =begin original Another way to provide the base URI. =end original ベース URI を提供するもう一つの方法です。 =item C =begin original Print messages to STDERR about any bad HTML form constructs found. =end original 悪い HTML フォーム構造を見つけると、STDERR にメッセージを出力します。 =back =item $method = $form->method =item $form->method( $new_method ) =begin original This method is gets/sets the I name used for the C generated. It is a string like "GET" or "POST". =end original このメソッドは、C が生成されるときに使われる I<メソッド> 名を 取得/設定します。 これは "GET" や "POST" のような文字列です。 =item $action = $form->action =item $form->action( $new_action ) =begin original This method gets/sets the URI which we want to apply the request I to. =end original このメソッドはリクエスト I<メソッド> を適用したい URI を取得/設定します。 =item $enctype = $form->enctype =item $form->enctype( $new_enctype ) =begin original This method gets/sets the encoding type for the form data. It is a string like "application/x-www-form-urlencoded" or "multipart/form-data". =end original このメソッドはフォームデータのエンコーディングタイプを取得/設定します。 これは "application/x-www-form-urlencoded" や "multipart/form-data" のような 文字列です。 =item $value = $form->attr( $name ) =item $form->attr( $name, $new_value ) =begin original This method give access to the original HTML attributes of the tag. The $name should always be passed in lower case. =end original このメソッドは元の タグの HTML 属性へのアクセスを提供します。 $name は常に小文字で渡す必要があります。 =begin original Example: =end original 例: @f = HTML::Form->parse( $html, $foo ); @f = grep $_->attr("id") eq "foo", @f; die "No form named 'foo' found" unless @f; $foo = shift @f; =item @inputs = $form->inputs =begin original This method returns the list of inputs in the form. If called in scalar context it returns the number of inputs contained in the form. See L for what methods are available for the input objects returned. =end original このメソッドはフォームの入力のリストを返します。 スカラコンテキストで呼ばれると、フォームに含まれている入力の数を返します。 返された入力オブジェクトで利用可能なメソッドについては L を参照してください。 =item $input = $form->find_input( $name ) =item $input = $form->find_input( $name, $type ) =item $input = $form->find_input( $name, $type, $index ) =begin original This method is used to locate specific inputs within the form. All inputs that match the arguments given are returned. In scalar context only the first is returned, or C if none match. =end original このメソッドはフォーム内の特定の入力の位置を知るために使われます。 与えられた引数にマッチングする入力全てが返されます。 スカラコンテキストでは、マッチングしなければ C を、 マッチングすれば最初のものだけを返します。 =begin original If $name is specified, then the input must have the indicated name. =end original $name が指定された場合、入力は指示された名前を持たなければなりません。 =begin original If $type is specified, then the input must have the specified type. The following type names are used: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" and "option". =end original $type が指定された場合、有力は指定された種類でなければなりません。 以下の種類が使われます: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox", "option" =begin original The $index is the sequence number of the input matched where 1 is the first. If combined with $name and/or $type then it select the Ith input with the given name and/or type. =end original $index はマッチングする入力のシーケンス番号(1 が先頭)です。 $name や $type と組み合わせると、与えられた名前や種類の I 番目が選択されます。 =item $value = $form->value( $name ) =item $form->value( $name, $new_value ) =begin original The value() method can be used to get/set the value of some input. If no input has the indicated name, then this method will croak. =end original value() メソッドは特定の入力の値を取得/設定するために使われます。 指定された名前の入力がない場合、このメソッドは croak します。 =begin original If multiple inputs have the same name, only the first one will be affected. =end original 同じ名前の入力が複数ある場合、最初のものだけが影響します。 =begin original The call: =end original 以下の呼び出し: $form->value('foo') =begin original is a short-hand for: =end original は以下のものの短縮形です: $form->find_input('foo')->value; =item @names = $form->param =item @values = $form->param( $name ) =item $form->param( $name, $value, ... ) =item $form->param( $name, \@values ) =begin original Alternative interface to examining and setting the values of the form. =end original フォームの値の調査と設定を行うためのもう一つのインターフェースです。 =begin original If called without arguments then it returns the names of all the inputs in the form. The names will not repeat even if multiple inputs have the same name. In scalar context the number of different names is returned. =end original 引数なしで呼ばれると、フォームの全ての入力の名前を返します。 同じ名前の入力が複数あっても一度しか現れません。 スカラコンテキストでは、異なる名前の数が返されます。 =begin original If called with a single argument then it returns the value or values of inputs with the given name. If called in scalar context only the first value is returned. If no input exists with the given name, then C is returned. =end original 引数一つで呼び出されると、与えられた名前の入力の値を返します。 スカラコンテキストで呼び出されると、最初の値のみが返されます。 与えられた名前の入力がない場合は、C が返されます。 =begin original If called with 2 or more arguments then it will set values of the named inputs. This form will croak if no inputs have the given name or if any of the values provided does not fit. Values can also be provided as a reference to an array. This form will allow unsetting all values with the given name as well. =end original 2 以上の引数で呼び出されると、名前のある入力の値を設定します。 この形式は、もし与えられた名前がなかったり、提供された値が適合しない場合は croak します。 値は配列へのリファレンスででも提供できます。 この形式は与えられた名前の全ての値をクリアすることも出来ます。 =begin original This interface resembles that of the param() function of the CGI module. =end original このインターフェースは CGI モジュールの param() 関数と似ています。 =item $form->try_others( \&callback ) =begin original This method will iterate over all permutations of unvisited enumerated values (, , ) の 順列に対して反復し、それぞれに対して callback を起動します。 callback は引数として $form が渡されます。 callback からの返り値は無視され、try_others() メソッド自身は何も 返しません。 =item $request = $form->make_request =begin original Will return an C object that reflects the current setting of the form. You might want to use the click() method instead. =end original フォームの現在の設定を反映した C を返します。 代わりに click() メソッドを使いたいかも知れません。 =item $request = $form->click =item $request = $form->click( $name ) =item $request = $form->click( $x, $y ) =item $request = $form->click( $name, $x, $y ) =begin original Will "click" on the first clickable input (which will be of type C or C). The result of clicking is an C object that can then be passed to C if you want to obtain the server response. =end original クリックできる入力 (型が C または C のもの) を 「クリック」します。 クリックの結果は、もしサーバレスポンスがほしい場合は後で C に 渡せる C オブジェクトです。 =begin original If a $name is specified, we will click on the first clickable input with the given name, and the method will croak if no clickable input with the given name is found. If $name is I specified, then it is ok if the form contains no clickable inputs. In this case the click() method returns the same request as the make_request() method would do. =end original $name が指定されると、与えられた名前を持つ最初のクリック可能な入力が クリックされ、もし与えられた名前のクリック可能な入力が見付からなかった場合は croak します。 $name が指定 I<されない> 場合は、フォームにクリック可能な入力がなくても 問題ありません。 この場合、click() メソッドは make_request() メソッドと同じリクエストを 返します。 =begin original If there are multiple clickable inputs with the same name, then there is no way to get the click() method of the C to click on any but the first. If you need this you would have to locate the input with find_input() and invoke the click() method on the given input yourself. =end original 同じ名前で複数のクリック可能な入力がある場合、最初のもの以外が クリックされたことを C の click() メソッドで知る方法は ありません。 これが必要なら、find_input() で入力の位置を探して、得られた入力自身に 対して click() メソッドを起動する必要があります。 =begin original A click coordinate pair can also be provided, but this only makes a difference if you clicked on an image. The default coordinate is (1,1). The upper-left corner of the image is (0,0), but some badly coded CGI scripts are known to not recognize this. Therefore (1,1) was selected as a safer default. =end original クリック座標の組も提供されますが、画像をクリックされたときにのみ 違いがあります。 デフォルトの座標は (1,1) です。 画像の左上の隅は (0,0) ですが、間違ってコーディングされた CGI スクリプトには これを認識しないことが知られています。 従って (1,1) はより安全なデフォルトとして選択されました。 =item @kw = $form->form =begin original Returns the current setting as a sequence of key/value pairs. Note that keys might be repeated, which means that some values might be lost if the return values are assigned to a hash. =end original 現在の設定をキー/値の組として返します。 キーは繰り返されるかもしれないので、返り値をハッシュに代入すると 値の一部が失われるかもしれないことに注意してください。 =begin original In scalar context this method returns the number of key/value pairs generated. =end original スカラコンテキストではこのメソッドは生成されるキー/値の組の数を返します。 =item $form->dump =begin original Returns a textual representation of current state of the form. Mainly useful for debugging. If called in void context, then the dump is printed on STDERR. =end original フォームの現在の状態のテキスト表現を返します。 主にデバッグに有用です。 無効コンテキストで呼び出されると、ダンプは STDERR に出力されます。 =back =head1 INPUTS (入力) =begin original An C objects contains a sequence of I. References to the inputs can be obtained with the $form->inputs or $form->find_input methods. =end original C オブジェクトは I<入力>(input) の組を含みます。 入力へのリファレンスは $form->inputs メソッドや $form->find_input メソッドで 得られます。 =begin original Note that there is I a one-to-one correspondence between input I and EinputE I in the HTML document. An input object basically represents a name/value pair, so when multiple HTML elements contribute to the same name/value pair in the submitted form they are combined. =end original 入力 I<オブジェクト> と、HTML 文書の EinputE I<要素> は 1 対 1 で I<対応しない> ことに注意してください。 入力オブジェクトは基本的に一つの名前/値の組を表現するので、同じ名前/値の 組を提供する複数の HTML 要素は結合されます。 =begin original The input elements that are mapped one-to-one are "text", "textarea", "password", "hidden", "file", "image", "submit" and "checkbox". For the "radio" and "option" inputs the story is not as simple: All Einput type="radio"E elements with the same name will contribute to the same input radio object. The number of radio input objects will be the same as the number of distinct names used for the Einput type="radio"E elements. For a EselectE element without the C attribute there will be one input object of type of "option". For a Eselect multipleE element there will be one input object for each contained EoptionE element. Each one of these option objects will have the same name. =end original 1 対 1 でマッピングされる入力要素は "text", "textarea", "password", "hidden", "file", "image", "submit", "checkbox" です。 "radio" と "option" 入力では話はそれほど簡単ではありません: 同じ名前を持つ全ての Einput type="radio"E 要素は同じ入力 radio オブジェクトに提供されます。 radio 入力オブジェクトの数は Einput type="radio"E 要素で使われている 異なる名前の数と同じです。 C 属性のない EselectE 要素の場合、"option" 型の 一つの入力オブジェクトです。 Eselect multipleE 要素の場合、それぞれに EoptionE 要素を 含んだ一つの入力オブジェクトです。 これらの option オブジェクトのそれぞれは同じ名前を持ちます。 =begin original The following methods are available for the I objects: =end original 以下のメソッドが I オブジェクトで利用可能です: =over 4 =item $input->type =begin original Returns the type of this input. The type is one of the following strings: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" or "option". =end original この入力の種類を返します。 種類は以下の文字列の一つです: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox", "option"。 =item $name = $input->name =item $input->name( $new_name ) =begin original This method can be used to get/set the current name of the input. =end original このメソッドは入力の現在の名前を取得/設定できます。 =item $value = $input->value =item $input->value( $new_value ) =begin original This method can be used to get/set the current value of an input. =end original このメソッドは入力の現在の値を取得/設定できます。 =begin original If the input only can take an enumerated list of values, then it is an error to try to set it to something else and the method will croak if you try. =end original 入力が列挙された値のリストうちの一つだけを取る場合、違う値を 設定しようとすることはエラーであり、そうしようとするとメソッドは croak します。 =begin original You will also be able to set the value of read-only inputs, but a warning will be generated if running under C. =end original また、読み込み専用入力の値を設定することもできますが、 C で実行されている場合は警告が発生します。 =item $input->possible_values =begin original Returns a list of all values that an input can take. For inputs that do not have discrete values, this returns an empty list. =end original 入力が取ることができる全ての値のリストを返します。 離散値を取る入力でない場合は、空リストを返します。 =item $input->other_possible_values =begin original Returns a list of all values not tried yet. =end original まだ試していない全ての値のリストを返します。 =item $input->value_names =begin original For some inputs the values can have names that are different from the values themselves. The number of names returned by this method will match the number of values reported by $input->possible_values. =end original 一部の入力では、値に値自身と違う名前を付けられます。 このメソッドで返される名前の数は $input->possible_values で報告される 値の数と一致します。 =begin original When setting values using the value() method it is also possible to use the value names in place of the value itself. =end original value() メソッドを使って値を設定するとき、値自身の代わりに値の名前を 使うことも可能です。 =item $bool = $input->readonly =item $input->readonly( $bool ) =begin original This method is used to get/set the value of the readonly attribute. You are allowed to modify the value of readonly inputs, but setting the value will generate some noise when warnings are enabled. Hidden fields always start out readonly. =end original このメソッドは読み込み専用(readonly)属性の値を取得/設定するために使います。 読み込み専用の入力の値を変えることもできますが、値を設定すると 警告が有効の時には警告が出力されます。 hidden フィールドは常に読み込み専用で始まります。 =item $bool = $input->disabled =item $input->disabled( $bool ) =begin original This method is used to get/set the value of the disabled attribute. Disabled inputs do not contribute any key/value pairs for the form value. =end original このメソッドは無効(disabled)属性の値を取得/設定するために使われます。 無効の入力はフォームの値のためにキー/値の組を提供しません。 =item $input->form_name_value =begin original Returns a (possible empty) list of key/value pairs that should be incorporated in the form value from this input. =end original この入力からのフォームの値と連携しているキー/値の組のリスト (空かもしれません)を返します。 =item $input->check =begin original Some input types represent toggles that can be turned on/off. This includes "checkbox" and "option" inputs. Calling this method turns this input on without having to know the value name. If the input is already on, then nothing happens. =end original 一部の入力はオン/オフできるトグルを表現しています。 これは "checkbox" と "option" を含みます。 このメソッドを呼び出すと、この入力の現在の値を知らなくてもオンになります。 入力が既にオンなら、何も起きません。 =begin original This has the same effect as: =end original これは以下と同じ効果です: $input->value($input->possible_values[1]); =begin original The input can be turned off with: =end original 入力は以下のようにしてオフにできます: $input->value(undef); =item $input->click($form, $x, $y) =begin original Some input types (currently "submit" buttons and "images") can be clicked to submit the form. The click() method returns the corresponding C object. =end original 一部の入力 (現在のところ "submit" ボタンと "images") はフォームを 送信するためにクリックできます。 click() メソッドは対応する C オブジェクトを返します。 =back =begin original If the input is of type C, then it has these additional methods: =end original 入力の種類が C の場合、追加のメソッドがあります: =over 4 =item $input->file =begin original This is just an alias for the value() method. It sets the filename to read data from. =end original これは単に value() メソッドの別名です。 データを読み込むファイル名を設定します。 =item $filename = $input->filename =item $input->filename( $new_filename ) =begin original This get/sets the filename reported to the server during file upload. This attribute defaults to the value reported by the file() method. =end original これはファイルアップロード中にサーバに報告されるファイル名を設定/取得します。 この属性のデフォルトは file() メソッドで報告される値です。 =item $content = $input->content =item $input->content( $new_content ) =begin original This get/sets the file content provided to the server during file upload. This method can be used if you do not want the content to be read from an actual file. =end original これはファイルアップロード中にサーバに提供されるファイルの内容を 取得/設定します。 このメソッドは、実際のファイルから内容を読み込みたくない場合に使えます。 =item @headers = $input->headers =item input->headers($key => $value, .... ) =begin original This get/set additional header fields describing the file uploaded. This can for instance be used to set the C reported for the file. =end original これはアップロードされたファイルを表現する追加のヘッダフィールドを 取得/設定します。 これは例えばファイルのために報告する C の設定に使います。 =back =head1 SEE ALSO L, L, L =head1 COPYRIGHT Copyright 1998-2005 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =begin meta Translated: Kentaro SHIRAKATA (5.813) =end meta =cut