@node LWP/Simple, LWP/Socket, LWP/RobotUA, Module List
@unnumbered Procedural LWP interface


@unnumberedsec NAME

get, head, getprint, getstore, mirror - Procedural LWP interface

@unnumberedsec SYNOPSIS

@example
perl -MLWP::Simple -e @'getprint "http://www.sn.no"@'
@end example

@example
use LWP::Simple;
$content = get("http://www.sn.no/")
if (mirror("http://www.sn.no/", "foo") == RC_NOT_MODIFIED) @{
    ...
@}
if (is_success(getprint("http://www.sn.no/"))) @{
    ...
@}
@end example

@unnumberedsec DESCRIPTION

This interface is intended for those who want a simplified view of the
libwww-perl library.  This interface should also be suitable for
one-liners.  If you need more control or access to the header fields
in the requests sent and responses received you should use the full OO
interface provided by the LWP::UserAgent module.

This following functions are provided (and exported) by this module:

@table @asis
@item get($url)
This function will get the document identified by the given URL.  The
get() function will return the document if successful or @'undef@' if it
fails.  The $url argument can be either a simple string or a reference
to a URI::URL object.

You will not be able to examine the response code or response headers
(like @emph{Content-Type}) when you are accessing the web using this
function.  If you need this you should use the full OO interface.

@item head($url)
Get document headers. Returns the following values if successful:
($content_type, $document_length, $modified_time, $expires, $server)

Returns an empty list if it fails.

@item getprint($url)
Get and print a document identified by a URL. The document is printet
on STDOUT. The error message (formatted as HTML) is printed on STDERR
if the request fails.  The return value is the HTTP response code.

@item getstore($url, $file)
Gets a document identified by a URL and stores it in the file. The
return value is the HTTP response code.

@item mirror($url, $file)
Get and store a document identified by a URL, using
@emph{If-modified-since}, and checking of the @emph{Content-Length}.  Returns
the HTTP response code.

@end table
This module also exports the HTTP::Status constants and
procedures.  These can be used when you check the response code from
getprint(), getstore() and mirror().  The constants are:

@example
RC_CONTINUE
RC_SWITCHING_PROTOCOLS
RC_OK
RC_CREATED
RC_ACCEPTED
RC_NON_AUTHORITATIVE_INFORMATION
RC_NO_CONTENT
RC_RESET_CONTENT
RC_PARTIAL_CONTENT
RC_MULTIPLE_CHOICES
RC_MOVED_PERMANENTLY
RC_MOVED_TEMPORARILY
RC_SEE_OTHER
RC_NOT_MODIFIED
RC_USE_PROXY
RC_BAD_REQUEST
RC_UNAUTHORIZED
RC_PAYMENT_REQUIRED
RC_FORBIDDEN
RC_NOT_FOUND
RC_METHOD_NOT_ALLOWED
RC_NOT_ACCEPTABLE
RC_PROXY_AUTHENTICATION_REQUIRED
RC_REQUEST_TIMEOUT
RC_CONFLICT
RC_GONE
RC_LENGTH_REQUIRED
RC_PRECONDITION_FAILED
RC_REQUEST_ENTITY_TOO_LARGE
RC_REQUEST_URI_TOO_LARGE
RC_UNSUPPORTED_MEDIA_TYPE
RC_INTERNAL_SERVER_ERROR
RC_NOT_IMPLEMENTED
RC_BAD_GATEWAY
RC_SERVICE_UNAVAILABLE
RC_GATEWAY_TIMEOUT
RC_HTTP_VERSION_NOT_SUPPORTED
@end example

The HTTP::Status classification functions are:

@table @asis
@item is_success($rc)
Check if response code indicated successfull request.

@item is_error($rc)
Check if response code indicated that an error occured.

@end table
The module will also export the LWP::UserAgent object as @code{$ua} if you
ask for it explicitly.

The user agent created by this module will identify itself as
"LWP::Simple/0.00" and will initialize its proxy defaults from the
environment (by calling $ua->env_proxy).

@unnumberedsec SEE ALSO

@xref{LWP,LWP},, @xref{LWP/UserAgent,LWP/UserAgent},, @xref{HTTP/Status,HTTP/Status},, @samp{request} in this node, @samp{mirror} in this node

