=begin pod

=head1 NAME

LibCurl::Easy

=head1 SYNOPSIS

  use LibCurl::Easy;

  my $curl = LibCurl::Easy.new(URL => 'http://example.com');

  $curl.setopt(:verbose, :followlocation);

  $curl.perform;

  say $curl.response-code;

=head1 DESCRIPTION

This is a high-level interface to
L<libcurl|https://curl.haxx.se/libcurl>, a free and easy-to-use
client-side URL transfer library.

It wraps the low-level interface provided in L<LibCurl::EasyHandle> in
some high level constructs that make it a little easier to work with
libcurl from Perl.

=head2 class B<LibCurl::Easy>

The main class for C<LibCurl::Easy>.

=item method B<new>(*%options) returns LibCurl::Easy

Creates a new C<LibCurl::Easy> object and sets up a bunch of default
stuff.

You can optionally pass in options and they will get passed directly
to C<.setopt> after object creation.

=item method B<version>() returns Str

Returns human readable version of the curl library.  Can be called on
a C<LibCurl::Easy> object:

  say $curl.version;

or on the LibCurl::Easy type directly as a class method:

  say LibCurl::Easy.version;

=item method B<set-header>(*%headers) returns LibCurl::Easy

Set header => 'value' pairs in headers to be sent with a request

=item method B<clear-header>() returns LibCurl::Easy

Clear 'extra' outgoing headers.

=item method B<setopt>(*%options) returns LibCurl::Easy

Pass options and parameters.  See ... for a description of the
options.

=item method B<perform>() returns LibCurl::Easy

Perform the transaction for this handle.  As an alternative, the
C<LibCurl::Easy> handle can be added to a C<LibCurl::Multi> object in
which case you don't call perform directly.

=item method B<buf>() returns Buf

Received content as a Buf.

=item method B<content>($encoding = 'utf-8') returns Str

Received content decoded to a Str.

=item method B<error>() returns Str

Human readable
L<"extra"|https://curl.haxx.se/libcurl/c/CURLOPT_ERRORBUFFER.html>
error information that may or may not be available after an error
condition.

=item method B<receivedheaders>() returns Hash

A Hash of all received headers from the last transaction.

=item method B<get-header>(Str $field) returns Str

Get a single from the received headers.

=item method B<success>() returns Bool

Is the HTTP response-code 2xx?

=item multi method B<getinfo>(Str $info)

Returns a single info object.  See ... for a description of all the
info fields.

=item multi method B<getinfo>(*@fields) returns Hash

Get a hash of specific info fields.

=item multi method B<getinfo>() returns Hash

Get all info fields into a Hash.

=item method B<cleanup>()

Finish with the handle.  If you don't call this explicitly, it will be
taken care of with a C<DESTROY> handler by the garbage collector, but
the timing of that event is uncertain.

Some things, such as the writing of the cookiejar file happen only on
cleanup, so it may be useful to explicitly call.

You can use Perl 6 phasers to make calling this easy:

    {
        my $curl will leave { .cleanup } = LibCurl::Easy.new;
    }

As soon as the scope ends, the LEAVE phaser will call the cleanup
method on the LibCurl::Easy object.  This happens even if an exception
causes premature exit from the scope.

=item method B<FALLBACK>()

There is a convenience FALLBACK method that catches other methods.  It
checks for three things:

Is the method an OPTION?  If so, call C<$curl.setopt()>.

Is the method a received header?  If so, return it.

Is the method an INFO field?  If so call C<$curl.getinfo()>.

This makes it very easy to do things like:

   $curl.URL("http://example.com");
   $curl.download('myfile');

   say $curl.Content-Type;
   say $curl.ETag;
   say $curl.Date;
   say $curl.speed-download;

See ... or ... for the lists.

=head1 OPTIONS

...TODO...

=head1 INFO fields

...TODO...

=end pod
