UserAgent
NAME
HTTP::UserAgent - Web user agent class
SYNOPSIS
use HTTP::UserAgent;
my $ua = HTTP::UserAgent.new;
$ua.timeout = 10;
my $response = $ua.get("URL");
if $response.is-success {
say $response.content;
} else {
die $response.status-line;
}
DESCRIPTION
This module provides functionality to crawling the web with a handling cookies and correct User-Agent value.
It has TLS/SSL support.
METHODS
method new
method new(HTTP::UserAgent:U: :$!useragent, Bool :$!throw-exceptions, :$!max-redirects = 5, :$!debug) returns HTTP::UserAgent
Default constructor.
There are four optional named arguments:
useragent
A string that specifies what will be provided in the User-Agent header in
the request. A number of standard user agents are described in
HTTP::UserAgent::Common, but a string that is not specified there will be
used verbatim.
throw-exceptions
By default the request method will not throw an exception if the
response from the server indicates that the request was unsuccesful, in
this case you should check is-success to determine the status of the
HTTP::Response returned. If this is specified then an exception will
be thrown if the request was not a success, however you can still retrieve
the response from the response attribute of the exception object.
max-redirects
This is the maximum number of redirects allowed for a single request, if
this is exceeded then an exception will be thrown (this is not covered by
no-exceptions above and will always be throw,) the default value is 5.
debug
It can etheir be a Bool like simply :debug or you can pass it a IO::Handle
or a file name. Eg :debug($*ERR) will ouput on stderr :debug("mylog.txt")
will ouput on the file.
method auth
method auth(HTTP::UserAgent:, Str $login, Str $password)
Sets username and password needed to HTTP Auth.
method get
multi method get(Str $url is copy, :bin?, *%headers) returns HTTP::Response
multi method get(URI $uri, :bin?, *%headers) returns HTTP::Response
Requests the $url site, returns HTTP::Response, except if throw-exceptions is set as described above whereby an exception will be thrown if the response indicates that the request wasn't successfull.
If the Content-Type of the response indicates that the content is text the
content of the Response will be a decoded string, otherwise it will be
left as a Blob.
If the ':bin' adverb is supplied this will force the response content to
always be an undecoded Blob
Any additional named arguments will be applied as headers in the request.
method post
multi method post(URI $uri, %form, *%header ) -> HTTP::Response
multi method post(Str $uri, %form, *%header ) -> HTTP::Response
Make a POST request to the specified uri, with the provided Hash of %form data in the body encoded as "application/x-www-form-urlencoded" content. Any additional named style arguments will be applied as headers in the request.
An HTTP::Response will be returned, except if throw-exceptions has been set and the response indicates the request was not successfull.
If the Content-Type of the response indicates that the content is text the
content of the Response will be a decoded string, otherwise it will be
left as a Blob.
If the ':bin' adverb is supplied this will force the response content to
always be an undecoded Blob
If greater control over the content of the request is required you should create an HTTP::Request directly and populate it as needed,
method request
method request(HTTP::Request $request, :bin?) returns HTTP::Response
Performs the request described by the supplied HTTP::Request, returns a HTTP::Response, except if throw-exceptions is set as described above whereby an exception will be thrown if the response indicates that the request wasn't successful.
If the response has a 'Content-Encoding' header that indicates that the content was compressed, then it will attempt to inflate the data using Compress::Zlib, if the module is not installed then an exception will be thrown. If you do not have or do not want to install Compress::Zlib then you should be able to send an 'Accept-Encoding' header with a value of 'identity' which should cause a well behaved server to send the content verbatim if it is able to.
If the Content-Type of the response indicates that the content is text the
content of the Response will be a decoded string, otherwise it will be
left as a Blob. The content-types that are always considered to be
binary (and thus left as a Blob ) are those with the major-types of
'image','audio' and 'video', certain 'application' types are considered to
be 'text' (e.g. 'xml', 'javascript', 'json').
If the ':bin' adverb is supplied this will force the response content to
always be an undecoded Blob
You can use the helper subroutines defined in HTTP::Request::Common to create the HTTP::Request for you or create it yourself if you have more complex requirements.
routine get :simple
sub get(Str $url) returns Str is export(:simple)
Like method get, but returns decoded content of the response.
routine head :simple
sub head(Str $url) returns Parcel is export(:simple)
Returns values of following header fields:
Content-Type
Content-Length
Last-Modified
Expires
Server
routine getstore :simple
sub getstore(Str $url, Str $file) is export(:simple)
Like routine get but writes the content to a file.
routine getprint :simple
sub getprint(Str $url) is export(:simple)
Like routine get but prints the content and returns the response code.