Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grinnz/http-simple

HTTP::Simple - Simple procedural interface to HTTP::Tiny
https://github.com/grinnz/http-simple

Last synced: 5 days ago
JSON representation

HTTP::Simple - Simple procedural interface to HTTP::Tiny

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



HTTP::Simple - Simple procedural interface to HTTP::Tiny



=head1 SYNOPSIS



  perl -MHTTP::Simple -e'getprint(shift)' 'https://example.com'



  use HTTP::Simple;



  my $content = get 'https://example.com';



  if (mirror('https://example.com', '/path/to/file.html') == 304) { ... }



  if (is_success(getprint 'https://example.com')) { ... }



  postform('https://example.com', {foo => ['bar', 'baz']});



  postjson('https://example.com', [{bar => 'baz'}]);



  postfile('https://example.com', '/path/to/file.png');



=head1 DESCRIPTION



This module is a wrapper of L that provides simplified functions

for performing HTTP requests in a similar manner to L, but with

slightly more useful error handling. For full control of the request process

and response handling, use L directly.



L is required for HTTPS requests with L.



Request methods that return the body content of the response will return a byte

string suitable for directly printing, but that may need to be

L for text operations.



The L object used by these functions to make requests can be

accessed as C<$HTTP::Simple::UA> (for example, to configure the timeout, or

replace it with a compatible object like L).



The JSON encoder used by the JSON functions can be accessed as

C<$HTTP::Simple::JSON>, and defaults to a L object if

L 4.11+ is installed, and otherwise a L object. If

replaced with a new object, it should have UTF-8 encoding/decoding enabled

(usually the C option). If it is set to a string, it will be used as a

module name that is expected to have C and C

functions.



=head1 FUNCTIONS



All functions are exported by default. Functions can also be requested

individually or with the tags C<:request>, C<:status>, or C<:all>.



=head2 get



  my $contents = get($url);



Retrieves the document at the given URL with a GET request and returns it as a

byte string. Throws an exception on connection or HTTP errors.



=head2 getjson



  my $data = getjson($url);



Retrieves the JSON document at the given URL with a GET request and decodes it

from JSON to a Perl structure. Throws an exception on connection, HTTP, or JSON

errors.



=head2 head



  my $headers = head($url);



Retrieves the headers at the given URL with a HEAD request and returns them as

a hash reference. Header field names are normalized to lower case, and values

may be an array reference if the header is repeated. Throws an exception on

connection or HTTP errors.



=head2 getprint



  my $status = getprint($url);



Retrieves the document at the given URL with a GET request and prints it as it

is received. Returns the HTTP status code. Throws an exception on connection

errors.



=head2 getstore



  my $status = getstore($url, $path);



Retrieves the document at the given URL with a GET request and stores it to the

given file path. Returns the HTTP status code. Throws an exception on

connection or filesystem errors.



=head2 mirror



  my $status = mirror($url, $path);



Retrieves the document at the given URL with a GET request and mirrors it to

the given file path, using the C headers to short-circuit if

the file exists and is new enough, and the C header to set its

modification time. Returns the HTTP status code. Throws an exception on

connection, HTTP, or filesystem errors.



=head2 postform



  my $contents = postform($url, $form);



Sends a POST request to the given URL with the given hash or array reference of

form data serialized to C. Returns the

response body as a byte string. Throws an exception on connection or HTTP

errors.



=head2 postjson



  my $contents = postjson($url, $data);



Sends a POST request to the given URL with the given data structure encoded to

JSON. Returns the response body as a byte string. Throws an exception on

connection, HTTP, or JSON errors.



=head2 postfile



  my $contents = postfile($url, $path);

  my $contents = postfile($url, $path, $content_type);



Sends a POST request to the given URL, streaming the contents of the given

file. The content type is passed as C if not

specified. Returns the response body as a byte string. Throws an exception on

connection, HTTP, or filesystem errors.



=head2 is_info



  my $bool = is_info($status);



Returns true if the status code indicates an informational response (C<1xx>).



=head2 is_success



  my $bool = is_success($status);



Returns true if the status code indicates a successful response (C<2xx>).



=head2 is_redirect



  my $bool = is_redirect($status);



Returns true if the status code indicates a redirection response (C<3xx>).



=head2 is_error



  my $bool = is_error($status);



Returns true if the status code indicates an error response (C<4xx> or C<5xx>).



=head2 is_client_error



  my $bool = is_client_error($status);



Returns true if the status code indicates a client error response (C<4xx>).



=head2 is_server_error



  my $bool = is_server_error($status);



Returns true if the status code indicates a server error response (C<5xx>).



=head1 BUGS



Report any issues on the public bugtracker.



=head1 AUTHOR



Dan Book 



=head1 COPYRIGHT AND LICENSE



This software is Copyright (c) 2019 by Dan Book.



This is free software, licensed under:



  The Artistic License 2.0 (GPL Compatible)



=head1 SEE ALSO



L, L, L



=cut