argra****@users*****
argra****@users*****
2009年 3月 13日 (金) 20:43:38 JST
Index: docs/modules/libwww-perl-5.813/LWP/UserAgent.pod
diff -u /dev/null docs/modules/libwww-perl-5.813/LWP/UserAgent.pod:1.1
--- /dev/null Fri Mar 13 20:43:38 2009
+++ docs/modules/libwww-perl-5.813/LWP/UserAgent.pod Fri Mar 13 20:43:38 2009
@@ -0,0 +1,1331 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+LWP::UserAgent - Web user agent class
+
+=end original
+
+LWP::UserAgent - Web ユーザエージェントクラス
+
+=head1 SYNOPSIS
+
+ require LWP::UserAgent;
+
+ my $ua = LWP::UserAgent->new;
+ $ua->timeout(10);
+ $ua->env_proxy;
+
+ my $response = $ua->get('http://search.cpan.org/');
+
+ if ($response->is_success) {
+ print $response->content; # or whatever
+ }
+ else {
+ die $response->status_line;
+ }
+
+=head1 DESCRIPTION
+
+=begin original
+
+The C<LWP::UserAgent> is a class implementing a web user agent.
+C<LWP::UserAgent> objects can be used to dispatch web requests.
+
+=end original
+
+C<LWP::UserAgent> は web ユーザエージェントを実装するクラスです。
+C<LWP::UserAgent> オブジェクトは web リクエストを発行(dispatch)するために
+使えます。
+
+=begin original
+
+In normal use the application creates an C<LWP::UserAgent> object, and
+then configures it with values for timeouts, proxies, name, etc. It
+then creates an instance of C<HTTP::Request> for the request that
+needs to be performed. This request is then passed to one of the
+request method the UserAgent, which dispatches it using the relevant
+protocol, and returns a C<HTTP::Response> object. There are
+convenience methods for sending the most common request types: get(),
+head() and post(). When using these methods then the creation of the
+request object is hidden as shown in the synopsis above.
+
+=end original
+
+通常の使用では、アプリケーションは C<LWP::UserAgent> クラスを作成し、
+タイムアウト、プロキシ、名前などのための値でそれを設定します。
+それから実行される必要があるリクエストのために C<HTTP::Request> の
+インスタンスを作成します。
+そしてこのリクエストは UserAgent のリクエストメソッドの一つに渡されます;
+これは対応するプロトコルを使ってそれを発行し、
+C<HTTP::Response> オブジェクトを返します。
+There are
+convenience methods for sending the most common request types: get(),
+head() and post(). When using these methods then the creation of the
+request object is hidden as shown in the synopsis above.
+(TBT)
+
+=begin original
+
+The basic approach of the library is to use HTTP style communication
+for all protocol schemes. This means that you will construct
+C<HTTP::Request> objects and receive C<HTTP::Response> objects even
+for non-HTTP resources like I<gopher> and I<ftp>. In order to achieve
+even more similarity to HTTP style communications, gopher menus and
+file directories are converted to HTML documents.
+
+=end original
+
+このライブラリの基本的なアプローチは、HTTP 式通信をすべての
+プロトコルスキームに使うことです。
+つまり I<gopher> や I<ftp> のような非 HTTP リソースでも
+C<HTTP::Request> オブジェクトを構築して
+C<HTTP::Response> オブジェクトを受け取るということです。
+より HTTP 式通信に似せるため、gopher メニューとファイルディレクトリは
+HTML ドキュメントに変換されます。
+
+=head1 CONSTRUCTOR METHODS
+
+=begin original
+
+The following constructor methods are available:
+
+=end original
+
+以下のコンストラクタメソッドが利用可能です:
+
+=over 4
+
+=item $ua = LWP::UserAgent->new( %options )
+
+=begin original
+
+This method constructs a new C<LWP::UserAgent> object and returns it.
+Key/value pair arguments may be provided to set up the initial state.
+The following options correspond to attribute methods described below:
+
+=end original
+
+This method constructs a new C<LWP::UserAgent> object and returns it.
+Key/value pair arguments may be provided to set up the initial state.
+The following options correspond to attribute methods described below:
+(TBT)
+
+ KEY DEFAULT
+ ----------- --------------------
+ agent "libwww-perl/#.##"
+ from undef
+ conn_cache undef
+ cookie_jar undef
+ default_headers HTTP::Headers->new
+ max_size undef
+ max_redirect 7
+ parse_head 1
+ protocols_allowed undef
+ protocols_forbidden undef
+ requests_redirectable ['GET', 'HEAD']
+ timeout 180
+
+=begin original
+
+The following additional options are also accepted: If the
+C<env_proxy> option is passed in with a TRUE value, then proxy
+settings are read from environment variables (see env_proxy() method
+below). If the C<keep_alive> option is passed in, then a
+C<LWP::ConnCache> is set up (see conn_cache() method below). The
+C<keep_alive> value is passed on as the C<total_capacity> for the
+connection cache.
+
+=end original
+
+The following additional options are also accepted: If the
+C<env_proxy> option is passed in with a TRUE value, then proxy
+settings are read from environment variables (see env_proxy() method
+below). If the C<keep_alive> option is passed in, then a
+C<LWP::ConnCache> is set up (see conn_cache() method below). The
+C<keep_alive> value is passed on as the C<total_capacity> for the
+connection cache.
+(TBT)
+
+=item $ua->clone
+
+=begin original
+
+Returns a copy of the LWP::UserAgent object.
+
+=end original
+
+Returns a copy of the LWP::UserAgent object.
+(TBT)
+
+=back
+
+=head1 ATTRIBUTES
+
+=begin original
+
+The settings of the configuration attributes modify the behaviour of the
+C<LWP::UserAgent> when it dispatches requests. Most of these can also
+be initialized by options passed to the constructor method.
+
+=end original
+
+The settings of the configuration attributes modify the behaviour of the
+C<LWP::UserAgent> when it dispatches requests. Most of these can also
+be initialized by options passed to the constructor method.
+(TBT)
+
+=begin original
+
+The following attributes methods are provided. The attribute value is
+left unchanged if no argument is given. The return value from each
+method is the old attribute value.
+
+=end original
+
+The following attributes methods are provided. The attribute value is
+left unchanged if no argument is given. The return value from each
+method is the old attribute value.
+(TBT)
+
+=over
+
+=item $ua->agent
+
+=item $ua->agent( $product_id )
+
+=begin original
+
+Get/set the product token that is used to identify the user agent on
+the network. The agent value is sent as the "User-Agent" header in
+the requests. The default is the string returned by the _agent()
+method (see below).
+
+=end original
+
+ネットワーク上でユーザエージェントを識別するために使われる
+製品トークン(product token)を取得または設定します。
+エージェントの値はリクエストの "User-Agent" ヘッダとして送信されます。
+デフォルトは _agent() メソッド(後述)で返される文字列です。
+
+=begin original
+
+If the $product_id ends with space then the _agent() string is
+appended to it.
+
+=end original
+
+If the $product_id ends with space then the _agent() string is
+appended to it.
+(TBT)
+
+=begin original
+
+The user agent string should be one or more simple product identifiers
+with an optional version number separated by the "/" character.
+Examples are:
+
+=end original
+
+ユーザエージェント文字列は、オプションで "/" 文字で
+区切られたバージョン番号がついた、一つもしくはそれ以上の単純な
+製品トークンです。
+例を以下に示します:
+
+ $ua->agent('Checkbot/0.4 ' . $ua->_agent);
+ $ua->agent('Checkbot/0.4 '); # same as above
+ $ua->agent('Mozilla/5.0');
+ $ua->agent(""); # don't identify
+
+=item $ua->_agent
+
+=begin original
+
+Returns the default agent identifier. This is a string of the form
+"libwww-perl/#.##", where "#.##" is substituted with the version number
+of this library.
+
+=end original
+
+Returns the default agent identifier. This is a string of the form
+"libwww-perl/#.##", where "#.##" is substituted with the version number
+of this library.
+(TBT)
+
+=item $ua->from
+
+=item $ua->from( $email_address )
+
+=begin original
+
+Get/set the e-mail address for the human user who controls
+the requesting user agent. The address should be machine-usable, as
+defined in RFC 822. The C<from> value is send as the "From" header in
+the requests. Example:
+
+=end original
+
+リクエストしているユーザーエージェントを制御している人間であるユーザの
+e-mail アドレスを取得または設定します。
+アドレスは RFC で定義されているように、機械で利用できなければなりません。
+C<from> の値はリクエストでの "From" ヘッダとして送信されます。
+例:
+
+ $ua->from('gaas****@cpan*****');
+
+=begin original
+
+The default is to not send a "From" header. See the default_headers()
+method for the more general interface that allow any header to be defaulted.
+
+=end original
+
+The default is to not send a "From" header. See the default_headers()
+method for the more general interface that allow any header to be defaulted.
+(TBT)
+
+=item $ua->cookie_jar
+
+=item $ua->cookie_jar( $cookie_jar_obj )
+
+=begin original
+
+Get/set the cookie jar object to use. The only requirement is that
+the cookie jar object must implement the extract_cookies($request) and
+add_cookie_header($response) methods. These methods will then be
+invoked by the user agent as requests are sent and responses are
+received. Normally this will be a C<HTTP::Cookies> object or some
+subclass.
+
+=end original
+
+利用するためにクッキー瓶(cookie jar)オブジェクトを取得または設定します。
+The only requirement is that
+the cookie jar object must implement the extract_cookies($request) and
+add_cookie_header($response) methods. These methods will then be
+invoked by the user agent as requests are sent and responses are
+received. Normally this will be a C<HTTP::Cookies> object or some
+subclass.
+(TBT)
+
+=begin original
+
+The default is to have no cookie_jar, i.e. never automatically add
+"Cookie" headers to the requests.
+
+=end original
+
+デフォルトではクッキー瓶を使いません;
+つまり自動的には "Cookie" ヘッダをリクエストに追加しません。
+
+=begin original
+
+Shortcut: If a reference to a plain hash is passed in as the
+$cookie_jar_object, then it is replaced with an instance of
+C<HTTP::Cookies> that is initialized based on the hash. This form also
+automatically loads the C<HTTP::Cookies> module. It means that:
+
+=end original
+
+Shortcut: If a reference to a plain hash is passed in as the
+$cookie_jar_object, then it is replaced with an instance of
+C<HTTP::Cookies> that is initialized based on the hash. This form also
+automatically loads the C<HTTP::Cookies> module. It means that:
+(TBT)
+
+ $ua->cookie_jar({ file => "$ENV{HOME}/.cookies.txt" });
+
+=begin original
+
+is really just a shortcut for:
+
+=end original
+
+is really just a shortcut for:
+(TBT)
+
+ require HTTP::Cookies;
+ $ua->cookie_jar(HTTP::Cookies->new(file => "$ENV{HOME}/.cookies.txt"));
+
+=item $ua->default_headers
+
+=item $ua->default_headers( $headers_obj )
+
+=begin original
+
+Get/set the headers object that will provide default header values for
+any requests sent. By default this will be an empty C<HTTP::Headers>
+object. Example:
+
+=end original
+
+Get/set the headers object that will provide default header values for
+any requests sent. By default this will be an empty C<HTTP::Headers>
+object. Example:
+(TBT)
+
+ $ua->default_headers->push_header('Accept-Language' => "no, en");
+
+=item $ua->default_header( $field )
+
+=item $ua->default_header( $field => $value )
+
+=begin original
+
+This is just a short-cut for $ua->default_headers->header( $field =>
+$value ). Example:
+
+=end original
+
+This is just a short-cut for $ua->default_headers->header( $field =>
+$value ). Example:
+(TBT)
+
+ $ua->default_header('Accept-Language' => "no, en");
+
+=item $ua->conn_cache
+
+=item $ua->conn_cache( $cache_obj )
+
+=begin original
+
+Get/set the C<LWP::ConnCache> object to use. See L<LWP::ConnCache>
+for details.
+
+=end original
+
+Get/set the C<LWP::ConnCache> object to use. See L<LWP::ConnCache>
+for details.
+(TBT)
+
+=item $ua->credentials( $netloc, $realm, $uname, $pass )
+
+=begin original
+
+Set the user name and password to be used for a realm. It is often more
+useful to specialize the get_basic_credentials() method instead.
+
+=end original
+
+あるレルムのために使われるユーザ名、パスワードを設定します。
+代わりに get_basic_credentials() メソッドを特殊化するのにより便利です。
+
+=begin original
+
+The $netloc a string of the form "<host>:<port>". The username and
+password will only be passed to this server. Example:
+
+=end original
+
+The $netloc a string of the form "<host>:<port>". The username and
+password will only be passed to this server. Example:
+(TBT)
+
+ $ua->credentials("www.example.com:80", "Some Realm", "foo", "secret");
+
+=item $ua->max_size
+
+=item $ua->max_size( $bytes )
+
+=begin original
+
+Get/set the size limit for response content. The default is C<undef>,
+which means that there is no limit. If the returned response content
+is only partial, because the size limit was exceeded, then a
+"Client-Aborted" header will be added to the response. The content
+might end up longer than C<max_size> as we abort once appending a
+chunk of data makes the length exceed the limit. The "Content-Length"
+header, if present, will indicate the length of the full content and
+will normally not be the same as C<< length($res->content) >>.
+
+=end original
+
+レスポンスの内容(content)の大きさの制限を取得または設定します。
+デフォルトは C<undef> で、これは制限なしを意味します。
+大きさの制限を越えているために、戻されたレスポンスの内容が
+一部だけであれば、"Client-Aborted" ヘッダがレスポンスに追加されます。
+The content
+might end up longer than C<max_size> as we abort once appending a
+chunk of data makes the length exceed the limit. The "Content-Length"
+header, if present, will indicate the length of the full content and
+will normally not be the same as C<< length($res->content) >>.
+(TBT)
+
+=item $ua->max_redirect
+
+=item $ua->max_redirect( $n )
+
+=begin original
+
+This reads or sets the object's limit of how many times it will obey
+redirection responses in a given request cycle.
+
+=end original
+
+This reads or sets the object's limit of how many times it will obey
+redirection responses in a given request cycle.
+(TBT)
+
+=begin original
+
+By default, the value is 7. This means that if you call request()
+method and the response is a redirect elsewhere which is in turn a
+redirect, and so on seven times, then LWP gives up after that seventh
+request.
+
+=end original
+
+By default, the value is 7. This means that if you call request()
+method and the response is a redirect elsewhere which is in turn a
+redirect, and so on seven times, then LWP gives up after that seventh
+request.
+(TBT)
+
+=item $ua->parse_head
+
+=item $ua->parse_head( $boolean )
+
+=begin original
+
+Get/set a value indicating whether we should initialize response
+headers from the E<lt>head> section of HTML documents. The default is
+TRUE. Do not turn this off, unless you know what you are doing.
+
+=end original
+
+HTML ドキュメントの E<lt>head> セクションからレスポンスヘッダを
+初期化すべきかどうかを示す値を取得または設定します。
+デフォルトは TRUE です。
+何をしているのかわからなければ、これをオフにしないで下さい。
+
+=item $ua->protocols_allowed
+
+=item $ua->protocols_allowed( \@protocols )
+
+=begin original
+
+This reads (or sets) this user agent's list of protocols that the
+request methods will exclusively allow. The protocol names are case
+insensitive.
+
+=end original
+
+This reads (or sets) this user agent's list of protocols that the
+request methods will exclusively allow. The protocol names are case
+insensitive.
+(TBT)
+
+=begin original
+
+For example: C<$ua-E<gt>protocols_allowed( [ 'http', 'https'] );>
+means that this user agent will I<allow only> those protocols,
+and attempts to use this user agent to access URLs with any other
+schemes (like "ftp://...") will result in a 500 error.
+
+=end original
+
+For example: C<$ua-E<gt>protocols_allowed( [ 'http', 'https'] );>
+means that this user agent will I<allow only> those protocols,
+and attempts to use this user agent to access URLs with any other
+schemes (like "ftp://...") will result in a 500 error.
+(TBT)
+
+=begin original
+
+To delete the list, call: C<$ua-E<gt>protocols_allowed(undef)>
+
+=end original
+
+To delete the list, call: C<$ua-E<gt>protocols_allowed(undef)>
+(TBT)
+
+=begin original
+
+By default, an object has neither a C<protocols_allowed> list, nor a
+C<protocols_forbidden> list.
+
+=end original
+
+By default, an object has neither a C<protocols_allowed> list, nor a
+C<protocols_forbidden> list.
+(TBT)
+
+=begin original
+
+Note that having a C<protocols_allowed> list causes any
+C<protocols_forbidden> list to be ignored.
+
+=end original
+
+Note that having a C<protocols_allowed> list causes any
+C<protocols_forbidden> list to be ignored.
+(TBT)
+
+=item $ua->protocols_forbidden
+
+=item $ua->protocols_forbidden( \@protocols )
+
+=begin original
+
+This reads (or sets) this user agent's list of protocols that the
+request method will I<not> allow. The protocol names are case
+insensitive.
+
+=end original
+
+This reads (or sets) this user agent's list of protocols that the
+request method will I<not> allow. The protocol names are case
+insensitive.
+(TBT)
+
+=begin original
+
+For example: C<$ua-E<gt>protocols_forbidden( [ 'file', 'mailto'] );>
+means that this user agent will I<not> allow those protocols, and
+attempts to use this user agent to access URLs with those schemes
+will result in a 500 error.
+
+=end original
+
+For example: C<$ua-E<gt>protocols_forbidden( [ 'file', 'mailto'] );>
+means that this user agent will I<not> allow those protocols, and
+attempts to use this user agent to access URLs with those schemes
+will result in a 500 error.
+(TBT)
+
+=begin original
+
+To delete the list, call: C<$ua-E<gt>protocols_forbidden(undef)>
+
+=end original
+
+To delete the list, call: C<$ua-E<gt>protocols_forbidden(undef)>
+(TBT)
+
+=item $ua->requests_redirectable
+
+=item $ua->requests_redirectable( \@requests )
+
+=begin original
+
+This reads or sets the object's list of request names that
+C<$ua-E<gt>redirect_ok(...)> will allow redirection for. By
+default, this is C<['GET', 'HEAD']>, as per RFC 2616. To
+change to include 'POST', consider:
+
+=end original
+
+This reads or sets the object's list of request names that
+C<$ua-E<gt>redirect_ok(...)> will allow redirection for. By
+default, this is C<['GET', 'HEAD']>, as per RFC 2616. To
+change to include 'POST', consider:
+(TBT)
+
+ push @{ $ua->requests_redirectable }, 'POST';
+
+=item $ua->timeout
+
+=item $ua->timeout( $secs )
+
+=begin original
+
+Get/set the timeout value in seconds. The default timeout() value is
+180 seconds, i.e. 3 minutes.
+
+=end original
+
+秒単位のタイムアウト値を取得または設定します。
+デフォルトの timeout() の値は 180 秒、つまり 3 分です。
+
+=begin original
+
+The requests is aborted if no activity on the connection to the server
+is observed for C<timeout> seconds. This means that the time it takes
+for the complete transaction and the request() method to actually
+return might be longer.
+
+=end original
+
+The requests is aborted if no activity on the connection to the server
+is observed for C<timeout> seconds. This means that the time it takes
+for the complete transaction and the request() method to actually
+return might be longer.
+(TBT)
+
+=back
+
+=head2 Proxy attributes
+
+=begin original
+
+The following methods set up when requests should be passed via a
+proxy server.
+
+=end original
+
+The following methods set up when requests should be passed via a
+proxy server.
+(TBT)
+
+=over
+
+=item $ua->proxy(\@schemes, $proxy_url)
+
+=item $ua->proxy($scheme, $proxy_url)
+
+=begin original
+
+Set/retrieve proxy URL for a scheme:
+
+=end original
+
+そのスキームのためのプロキシ URL を設定または取得します:
+
+ $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/');
+ $ua->proxy('gopher', 'http://proxy.sn.no:8001/');
+
+=begin original
+
+The first form specifies that the URL is to be used for proxying of
+access methods listed in the list in the first method argument,
+i.e. 'http' and 'ftp'.
+
+=end original
+
+最初の形式はその URL がメソッドの最初に引数のリストに入っている
+アクセスメソッド、つまり 'http' と 'ftp' のプロキシのために
+使われることを指定します。
+
+=begin original
+
+The second form shows a shorthand form for specifying
+proxy URL for a single access scheme.
+
+=end original
+
+2 番目の形式は一つのアクセス機能のためのプロキシ URL を
+指定するための短縮した形式を示しています。
+
+=item $ua->no_proxy( $domain, ... )
+
+=begin original
+
+Do not proxy requests to the given domains. Calling no_proxy without
+any domains clears the list of domains. Eg:
+
+=end original
+
+与えられたドメインへのリクエストをプロキシしません。
+何もドメインを指定しないで no_proxy を呼ぶと、ドメインのリストを
+クリアします。
+例:
+
+ $ua->no_proxy('localhost', 'no', ...);
+
+=item $ua->env_proxy
+
+=begin original
+
+Load proxy settings from *_proxy environment variables. You might
+specify proxies like this (sh-syntax):
+
+=end original
+
+*_proxy 環境変数からプロキシ設定をロードします。
+以下のように指定するかもしれません(sh での書き方):
+
+ gopher_proxy=http://proxy.my.place/
+ wais_proxy=http://proxy.my.place/
+ no_proxy="localhost,my.domain"
+ export gopher_proxy wais_proxy no_proxy
+
+=begin original
+
+csh or tcsh users should use the C<setenv> command to define these
+environment variables.
+
+=end original
+
+csh または tcsh のユーザは、これらの環境変数を定義するために
+C<setenv> コマンドを使わなければなりません。
+
+=begin original
+
+On systems with case insensitive environment variables there exists a
+name clash between the CGI environment variables and the C<HTTP_PROXY>
+environment variable normally picked up by env_proxy(). Because of
+this C<HTTP_PROXY> is not honored for CGI scripts. The
+C<CGI_HTTP_PROXY> environment variable can be used instead.
+
+=end original
+
+On systems with case insensitive environment variables there exists a
+name clash between the CGI environment variables and the C<HTTP_PROXY>
+environment variable normally picked up by env_proxy(). Because of
+this C<HTTP_PROXY> is not honored for CGI scripts. The
+C<CGI_HTTP_PROXY> environment variable can be used instead.
+(TBT)
+
+=back
+
+=head1 REQUEST METHODS
+
+=begin original
+
+The methods described in this section are used to dispatch requests
+via the user agent. The following request methods are provided:
+
+=end original
+
+The methods described in this section are used to dispatch requests
+via the user agent. The following request methods are provided:
+(TBT)
+
+=over
+
+=item $ua->get( $url )
+
+=item $ua->get( $url , $field_name => $value, ... )
+
+=begin original
+
+This method will dispatch a C<GET> request on the given $url. Further
+arguments can be given to initialize the headers of the request. These
+are given as separate name/value pairs. The return value is a
+response object. See L<HTTP::Response> for a description of the
+interface it provides.
+
+=end original
+
+This method will dispatch a C<GET> request on the given $url. Further
+arguments can be given to initialize the headers of the request. These
+are given as separate name/value pairs. The return value is a
+response object. See L<HTTP::Response> for a description of the
+interface it provides.
+(TBT)
+
+=begin original
+
+Fields names that start with ":" are special. These will not
+initialize headers of the request but will determine how the response
+content is treated. The following special field names are recognized:
+
+=end original
+
+Fields names that start with ":" are special. These will not
+initialize headers of the request but will determine how the response
+content is treated. The following special field names are recognized:
+(TBT)
+
+ :content_file => $filename
+ :content_cb => \&callback
+ :read_size_hint => $bytes
+
+=begin original
+
+If a $filename is provided with the C<:content_file> option, then the
+response content will be saved here instead of in the response
+object. If a callback is provided with the C<:content_cb> option then
+this function will be called for each chunk of the response content as
+it is received from the server. If neither of these options are
+given, then the response content will accumulate in the response
+object itself. This might not be suitable for very large response
+bodies. Only one of C<:content_file> or C<:content_cb> can be
+specified. The content of unsuccessful responses will always
+accumulate in the response object itself, regardless of the
+C<:content_file> or C<:content_cb> options passed in.
+
+=end original
+
+If a $filename is provided with the C<:content_file> option, then the
+response content will be saved here instead of in the response
+object. If a callback is provided with the C<:content_cb> option then
+this function will be called for each chunk of the response content as
+it is received from the server. If neither of these options are
+given, then the response content will accumulate in the response
+object itself. This might not be suitable for very large response
+bodies. Only one of C<:content_file> or C<:content_cb> can be
+specified. The content of unsuccessful responses will always
+accumulate in the response object itself, regardless of the
+C<:content_file> or C<:content_cb> options passed in.
+(TBT)
+
+=begin original
+
+The C<:read_size_hint> option is passed to the protocol module which
+will try to read data from the server in chunks of this size. A
+smaller value for the C<:read_size_hint> will result in a higher
+number of callback invocations.
+
+=end original
+
+The C<:read_size_hint> option is passed to the protocol module which
+will try to read data from the server in chunks of this size. A
+smaller value for the C<:read_size_hint> will result in a higher
+number of callback invocations.
+(TBT)
+
+=begin original
+
+The callback function is called with 3 arguments: a chunk of data, a
+reference to the response object, and a reference to the protocol
+object. The callback can abort the request by invoking die(). The
+exception message will show up as the "X-Died" header field in the
+response returned by the get() function.
+
+=end original
+
+The callback function is called with 3 arguments: a chunk of data, a
+reference to the response object, and a reference to the protocol
+object. The callback can abort the request by invoking die(). The
+exception message will show up as the "X-Died" header field in the
+response returned by the get() function.
+(TBT)
+
+=item $ua->head( $url )
+
+=item $ua->head( $url , $field_name => $value, ... )
+
+=begin original
+
+This method will dispatch a C<HEAD> request on the given $url.
+Otherwise it works like the get() method described above.
+
+=end original
+
+This method will dispatch a C<HEAD> request on the given $url.
+Otherwise it works like the get() method described above.
+(TBT)
+
+=item $ua->post( $url, \%form )
+
+=item $ua->post( $url, \@form )
+
+=item $ua->post( $url, \%form, $field_name => $value, ... )
+
+=item $ua->post( $url, $field_name => $value,... Content => \%form )
+
+=item $ua->post( $url, $field_name => $value,... Content => \@form )
+
+=item $ua->post( $url, $field_name => $value,... Content => $content )
+
+=begin original
+
+This method will dispatch a C<POST> request on the given $url, with
+%form or @form providing the key/value pairs for the fill-in form
+content. Additional headers and content options are the same as for
+the get() method.
+
+=end original
+
+This method will dispatch a C<POST> request on the given $url, with
+%form or @form providing the key/value pairs for the fill-in form
+content. Additional headers and content options are the same as for
+the get() method.
+(TBT)
+
+=begin original
+
+This method will use the POST() function from C<HTTP::Request::Common>
+to build the request. See L<HTTP::Request::Common> for a details on
+how to pass form content and other advanced features.
+
+=end original
+
+This method will use the POST() function from C<HTTP::Request::Common>
+to build the request. See L<HTTP::Request::Common> for a details on
+how to pass form content and other advanced features.
+(TBT)
+
+=item $ua->mirror( $url, $filename )
+
+=begin original
+
+This method will get the document identified by $url and store it in
+file called $filename. If the file already exists, then the request
+will contain an "If-Modified-Since" header matching the modification
+time of the file. If the document on the server has not changed since
+this time, then nothing happens. If the document has been updated, it
+will be downloaded again. The modification time of the file will be
+forced to match that of the server.
+
+=end original
+
+This method will get the document identified by $url and store it in
+file called $filename. If the file already exists, then the request
+will contain an "If-Modified-Since" header matching the modification
+time of the file. If the document on the server has not changed since
+this time, then nothing happens. If the document has been updated, it
+will be downloaded again. The modification time of the file will be
+forced to match that of the server.
+(TBT)
+
+=begin original
+
+The return value is the the response object.
+
+=end original
+
+The return value is the the response object.
+(TBT)
+
+=item $ua->request( $request )
+
+=item $ua->request( $request, $content_file )
+
+=item $ua->request( $request, $content_cb )
+
+=item $ua->request( $request, $content_cb, $read_size_hint )
+
+=begin original
+
+This method will dispatch the given $request object. Normally this
+will be an instance of the C<HTTP::Request> class, but any object with
+a similar interface will do. The return value is a response object.
+See L<HTTP::Request> and L<HTTP::Response> for a description of the
+interface provided by these classes.
+
+=end original
+
+This method will dispatch the given $request object. Normally this
+will be an instance of the C<HTTP::Request> class, but any object with
+a similar interface will do. The return value is a response object.
+See L<HTTP::Request> and L<HTTP::Response> for a description of the
+interface provided by these classes.
+(TBT)
+
+=begin original
+
+The request() method will process redirects and authentication
+responses transparently. This means that it may actually send several
+simple requests via the simple_request() method described below.
+
+=end original
+
+The request() method will process redirects and authentication
+responses transparently. This means that it may actually send several
+simple requests via the simple_request() method described below.
+(TBT)
+
+=begin original
+
+The request methods described above; get(), head(), post() and
+mirror(), will all dispatch the request they build via this method.
+They are convenience methods that simply hides the creation of the
+request object for you.
+
+=end original
+
+The request methods described above; get(), head(), post() and
+mirror(), will all dispatch the request they build via this method.
+They are convenience methods that simply hides the creation of the
+request object for you.
+(TBT)
+
+=begin original
+
+The $content_file, $content_cb and $read_size_hint all correspond to
+options described with the get() method above.
+
+=end original
+
+The $content_file, $content_cb and $read_size_hint all correspond to
+options described with the get() method above.
+(TBT)
+
+=begin original
+
+You are allowed to use a CODE reference as C<content> in the request
+object passed in. The C<content> function should return the content
+when called. The content can be returned in chunks. The content
+function will be invoked repeatedly until it return an empty string to
+signal that there is no more content.
+
+=end original
+
+You are allowed to use a CODE reference as C<content> in the request
+object passed in. The C<content> function should return the content
+when called. The content can be returned in chunks. The content
+function will be invoked repeatedly until it return an empty string to
+signal that there is no more content.
+(TBT)
+
+=item $ua->simple_request( $request )
+
+=item $ua->simple_request( $request, $content_file )
+
+=item $ua->simple_request( $request, $content_cb )
+
+=item $ua->simple_request( $request, $content_cb, $read_size_hint )
+
+=begin original
+
+This method dispatches a single request and returns the response
+received. Arguments are the same as for request() described above.
+
+=end original
+
+このメソッドは 1 回のリクエストを発行し、受信したレスポンスを返します。
+引数は上述の request() のものと同じです。
+
+=begin original
+
+The difference from request() is that simple_request() will not try to
+handle redirects or authentication responses. The request() method
+will in fact invoke this method for each simple request it sends.
+
+=end original
+
+The difference from request() is that simple_request() will not try to
+handle redirects or authentication responses. The request() method
+will in fact invoke this method for each simple request it sends.
+(TBT)
+
+=item $ua->is_protocol_supported( $scheme )
+
+=begin original
+
+You can use this method to test whether this user agent object supports the
+specified C<scheme>. (The C<scheme> might be a string (like 'http' or
+'ftp') or it might be an URI object reference.)
+
+=end original
+
+このユーザーエージェントが指定された C<scheme> を
+サポートしているかどうかを調べるために使うことができます。
+(C<scheme> には ('http' や 'ftp' のような）文字列や、
+URI オブジェクトリファレンスを指定できます。)
+
+=begin original
+
+Whether a scheme is supported, is determined by the user agent's
+C<protocols_allowed> or C<protocols_forbidden> lists (if any), and by
+the capabilities of LWP. I.e., this will return TRUE only if LWP
+supports this protocol I<and> it's permitted for this particular
+object.
+
+=end original
+
+Whether a scheme is supported, is determined by the user agent's
+C<protocols_allowed> or C<protocols_forbidden> lists (if any), and by
+the capabilities of LWP. I.e., this will return TRUE only if LWP
+supports this protocol I<and> it's permitted for this particular
+object.
+(TBT)
+
+=back
+
+=head2 Callback methods
+
+=begin original
+
+The following methods will be invoked as requests are processed. These
+methods are documented here because subclasses of C<LWP::UserAgent>
+might want to override their behaviour.
+
+=end original
+
+The following methods will be invoked as requests are processed. These
+methods are documented here because subclasses of C<LWP::UserAgent>
+might want to override their behaviour.
+(TBT)
+
+=over
+
+=item $ua->prepare_request( $request )
+
+=begin original
+
+This method is invoked by simple_request(). Its task is to modify the
+given $request object by setting up various headers based on the
+attributes of the user agent. The return value should normally be the
+$request object passed in. If a different request object is returned
+it will be the one actually processed.
+
+=end original
+
+This method is invoked by simple_request(). Its task is to modify the
+given $request object by setting up various headers based on the
+attributes of the user agent. The return value should normally be the
+$request object passed in. If a different request object is returned
+it will be the one actually processed.
+(TBT)
+
+=begin original
+
+The headers affected by the base implementation are; "User-Agent",
+"From", "Range" and "Cookie".
+
+=end original
+
+The headers affected by the base implementation are; "User-Agent",
+"From", "Range" and "Cookie".
+(TBT)
+
+=item $ua->redirect_ok( $prospective_request, $response )
+
+=begin original
+
+This method is called by request() before it tries to follow a
+redirection to the request in $response. This should return a TRUE
+value if this redirection is permissible. The $prospective_request
+will be the request to be sent if this method returns TRUE.
+
+=end original
+
+このメソッドは、$response のリクエストのリダイレクションに
+従おうとする前に、request() によって呼ばれます。
+This should return a TRUE
+value if this redirection is permissible. The $prospective_request
+will be the request to be sent if this method returns TRUE.
+(TBT)
+
+=begin original
+
+The base implementation will return FALSE unless the method
+is in the object's C<requests_redirectable> list,
+FALSE if the proposed redirection is to a "file://..."
+URL, and TRUE otherwise.
+
+=end original
+
+The base implementation will return FALSE unless the method
+is in the object's C<requests_redirectable> list,
+FALSE if the proposed redirection is to a "file://..."
+URL, and TRUE otherwise.
+(TBT)
+
+=item $ua->get_basic_credentials( $realm, $uri, $isproxy )
+
+=begin original
+
+This is called by request() to retrieve credentials for documents
+protected by Basic or Digest Authentication. The arguments passed in
+is the $realm provided by the server, the $uri requested and a boolean
+flag to indicate if this is authentication against a proxy server.
+
+=end original
+
+基本認証またはダイジェスト認証により保護されている文書のための
+証明物 (credentials) の取得のために request() によって呼ばれます。
+The arguments passed in
+is the $realm provided by the server, the $uri requested and a boolean
+flag to indicate if this is authentication against a proxy server.
+(TBT)
+
+=begin original
+
+The method should return a username and password. It should return an
+empty list to abort the authentication resolution attempt. Subclasses
+can override this method to prompt the user for the information. An
+example of this can be found in C<lwp-request> program distributed
+with this library.
+
+=end original
+
+このメソッドはユーザ名とパスワードを返します。
+認証解決の試みを中断させるためには空リストを返します。
+サブクラスはユーザに情報を尋ねるためにこのモジュールを上書きできます。
+この例はこのライブラリと一緒に配布される
+C<lwp-request> プログラムにあります。
+
+=begin original
+
+The base implementation simply checks a set of pre-stored member
+variables, set up with the credentials() method.
+
+=end original
+
+The base implementation simply checks a set of pre-stored member
+variables, set up with the credentials() method.
+(TBT)
+
+=item $ua->progress( $status, $request_or_response )
+
+=begin original
+
+This is called frequently as the response is received regardless of
+how the content is processed. The method is called with $status
+"begin" at the start of processing the request and with $state "end"
+before the request method returns. In between these $status will be
+the fraction of the response currently received or the string "tick"
+if the fraction can't be calculated.
+
+=end original
+
+This is called frequently as the response is received regardless of
+how the content is processed. The method is called with $status
+"begin" at the start of processing the request and with $state "end"
+before the request method returns. In between these $status will be
+the fraction of the response currently received or the string "tick"
+if the fraction can't be calculated.
+(TBT)
+
+=begin original
+
+When $status is "begin" the second argument is the request object,
+otherwise it is the response object.
+
+=end original
+
+When $status is "begin" the second argument is the request object,
+otherwise it is the response object.
+(TBT)
+
+=back
+
+=head1 SEE ALSO
+
+=begin original
+
+See L<LWP> for a complete overview of libwww-perl5. See L<lwpcook>
+and the scripts F<lwp-request> and F<lwp-download> for examples of
+usage.
+
+=end original
+
+libwww-perl5 の一通りの概要は L<LWP> を参照してください。
+使い方の例については、L<lwpcook> および
+F<lwp-request> と F<lwp-mirror> のスクリプトを参照してください。
+
+=begin original
+
+See L<HTTP::Request> and L<HTTP::Response> for a description of the
+message objects dispatched and received. See L<HTTP::Request::Common>
+and L<HTML::Form> for other ways to build request objects.
+
+=end original
+
+See L<HTTP::Request> and L<HTTP::Response> for a description of the
+message objects dispatched and received. See L<HTTP::Request::Common>
+and L<HTML::Form> for other ways to build request objects.
+(TBT)
+
+=begin original
+
+See L<WWW::Mechanize> and L<WWW::Search> for examples of more
+specialized user agents based on C<LWP::UserAgent>.
+
+=end original
+
+See L<WWW::Mechanize> and L<WWW::Search> for examples of more
+specialized user agents based on C<LWP::UserAgent>.
+(TBT)
+
+=head1 COPYRIGHT
+
+Copyright 1995-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
+
+Translated: Hippo2000 <GCD00****@nifty*****> (5.48)
+Updated: Kentaro SHIRAKATA <argra****@ub32*****> (5.813)
+
+=end meta
+