=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( $html_document, $base_uri ) =item @forms = HTML::Form->parse( $html_document, base => $base_uri, %opt ) =item @forms = HTML::Form->parse( $response, %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 required arguments is the HTML document to parse ($html_document) and the URI used to retrieve the document ($base_uri). The base URI is needed to resolve relative action URIs. The provided HTML document should be a Unicode string (or US-ASCII). =end original 必要な引数はパースする HTML 文書 ($html_document) と、 文書の取得に使われた URI ($base_uri) です。 ベース URI は相対アクション URI を解決するのに必要です。 指定された HTML 文書は Unicode (または US-ASCII) 文字列である 必要があります。 =begin original By default HTML::Form assumes that the original document was UTF-8 encoded and thus encode forms that don't specify an explict I as UTF-8. The charset assumed can be overridden by providing the C option to parse(). It's a good idea to be explict about this parameter as well, thus the recommended simplest invocation becomes: =end original デフォルトでは、HTML::Form は元文書が UTF-8 でエンコードされていることを 仮定するので、明示的な I が指定されないフォームは UTF-8 としてエンコードします。 仮定した文字集合は parse() の C オプションを指定することで 上書きできます。 この引数についても明示的にするのは良い考えです; 従って推奨するもっとも単純な起動方法は次のようになります: my @forms = HTML::Form->parse( Encode::decode($encoding, $html_document_bytes), base => $base_uri, charset => $encoding, ); =begin original If the document was retrieved with LWP then the response object provide methods to obtain a proper value for C and C: =end original LWP を使って文書が取得されると、レスポンスオブジェクトは C と C の適切な値を得るためのメソッドを提供します: my $ua = LWP::UserAgent->new; my $response = $ua->get("http://www.example.com/form.html"); my @forms = HTML::Form->parse($response->decoded_content, base => $response->base, charset => $response->content_charset, ); =begin original In fact, 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(), base() and content_charset() method with similar behaviour as C will do. =end original C と同じような振る舞いをする decoded_content(), base(), content_charset() メソッドが実装されている どのようなオブジェクトでも行えることに注意してください。 =begin original Additional options might be passed in to control how the parse method behaves. The following are all the options currently recognized: =end original どのようにパースメソッドが振る舞うかを制御する追加のオプションを 渡せます。 以下は現在認識するオプションの全てです: =over =item C<< base => $uri >> =begin original This is the URI used to retrive the original document. This option is not optional ;-) =end original これは元文書を取得するために使われた URI です。 このオプションはオプションではありません ;-) =item C<< charset => $str >> =begin original Specify what charset the original document was encoded in. This is used as the default for accept_charset. If not provided this defaults to "UTF-8". =end original 元文書がどの文字集合でエンコードされているかを指定します。 これは accept_charset のデフォルトとして使われます。 指定されなかった場合、デフォルトは "UTF-8" です。 =item C<< verbose => $bool >> =begin original Warn (print messages to STDERR) about any bad HTML form constructs found. You can trap these with $SIG{__WARN__}. =end original 悪い HTML フォーム構造を見つけると、警告します (STDERR にメッセージを出力します)。 これは $SIG{__WARN__} でトラップできます。 =item C<< strict => $bool >> =begin original Initialize any form objects with the given strict attribute. =end original 指定された厳密性属性でフォームオブジェクトを初期化します。 =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 $accept = $form->accept_charset =item $form->accept_charset( $new_accept ) =begin original This method gets/sets the list of charset encodings that the server processing the form accepts. Current implementation supports only one-element lists. Default value is "UNKNOWN" which we interpret as a request to use document charset as specified by the 'charset' parameter of the parse() method. To encode character strings you should have modern perl with Encode module. On older perls the setting of this attribute has no effect. =end original このメソッドは、フォームを処理するサーバが受け付ける文字集合エンコーディングの 一覧を取得/設定します。 現在の実装は 1 要素のリストのみに対応しています。 デフォルト値は "UNKNOWN" で、parse() メソッドの 'charset' パラメータによって 指定された文書の文字集合を使うことを要求すると解釈します。 文字単位の文字列をエンコードするには、Encode モジュールのある モダンな perl を使う必要があります。 より古い perl では、この属性を設定しても効果はありません。 =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 $bool = $form->strict =item $form->strict( $bool ) =begin original Gets/sets the strict attribute of a form. If the strict is turned on the methods that change values of the form will croak if you try to set illegal values or modify readonly fields. The default is not to be strict. =end original フォームの厳密性属性を取得/設定します。 厳密性がオンになっている場合、フォームの値を変更するメソッドは、 不正な値を設定しようとしたり、読み込み専用のフィールドを 変更しようとしたりすると、croak します。 デフォルトは厳密ではありません。 =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( $selector ) =item $input = $form->find_input( $selector, $type ) =item $input = $form->find_input( $selector, $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 $selector is specified, then the input's name, id, class attribute must match. A selector prefixed with '#' must match the id attribute of the input. A selector prefixed with '.' matches the class attribute. A selector prefixed with '^' or with no prefix matches the name attribute. =end original $selector が指定された場合、入力の name, id, class 属性は マッチングしなければなりません。 '#' が前置されたセレクタは入力の id 属性にマッチングしなければなりません。 '.' が前置されたセレクタは入力の class 属性にマッチングしなければなりません。 '^' が前置されたセレクタは入力の 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( $selector ) =item $form->value( $selector, $new_value ) =begin original The value() method can be used to get/set the value of some input. If strict is enabled and 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 basically 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( $selector ) =item $request = $form->click( $x, $y ) =item $request = $form->click( $selector, $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 $selector is specified, we will click on the first clickable input matching the selector, and the method will croak if no matching clickable input is found. If $selector 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. See description of the find_input() method above for how the $selector is specified. =end original $selector が指定されると、選択子にマッチングする最初のクリック可能な入力が クリックされ、もしマッチングするクリック可能な入力が見付からなかった場合は croak します。 $selector が指定 I<されない> 場合は、フォームにクリック可能な入力がなくても 問題ありません。 この場合、click() メソッドは make_request() メソッドと同じリクエストを 返します。 $selector をどのように指定するかについては、 前述の find_input() メソッドの記述を参照してください。 =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 $input->id =item $input->class =begin original These methods can be used to get/set the current id or class attribute for the input. =end original これらのメソッドは、入力の現在の id または class 属性を取得/設定するために 使われます。 =item $input->selected( $selector ) =begin original Returns TRUE if the given selector matched the input. See the description of the find_input() method above for a description of the selector syntax. =end original 与えられたセレクタが入力にマッチングしたときに真を返します。 セレクタの文法の記述については、前述の find_input() メソッドの記述を参照してください。 =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 strict is enabled and 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() メソッドの別名です。 データを読み込むファイル名を設定します。 =begin original For security reasons this field will never be initialized from the parsing of a form. This prevents the server from triggering stealth uploads of arbitrary files from the client machine. =end original セキュリティ上の理由により、このフィールドはフォームのパースから 初期化されることはありません。 これは、サーバがクライアントマシンから任意のファイルの内密な アップロードを引き起こすことを防ぎます。 =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-2008 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =begin meta Translate: SHIRAKATA Kentaro Status: completed =end meta =cut