NAME

AnyEvent::YACurl - Yet Another curl binding for AnyEvent

SYNOPSIS

    use AnyEvent;
    use AnyEvent::YACurl ':constants';

    my $client = AnyEvent::YACurl->new({});
    my $condvar = AnyEvent->condvar;
    my $return_data = '';
    $client->request($condvar, {
        CURLOPT_URL => "https://www.perl.org",
        CURLOPT_VERBOSE => 1,
        CURLOPT_WRITEFUNCTION => sub {
            my ($chunk) = @_;
            $return_data .= $chunk;
        },
        CURLOPT_HTTPHEADER => [
            "My-Super-Awesome-Header: forty-two",
        ],
    });

    my ($response, $error) = $condvar->recv;
    my $response_code = $response->getinfo(CURLINFO_RESPONSE_CODE);
    print "Have response code $response_code. Body was $return_data";

DESCRIPTION

This module provides bindings to curl, integrated into AnyEvent.

METHODS

AnyEvent::YACurl

new

Returns a new AnyEvent::YACurl object. This is essentially a binding over curl's "multi" interface.

Its first and only argument is a required hashref containing options to control behavior, such as CURLMOPT_MAX_TOTAL_CONNECTIONS. Refer to the actual curl documentation to find out about other options to pass.

request

Performs a request using the client instantiated via new. Takes a callback and a hashref of curl options (CURLOPT_*). At a minimum CURLOPT_URL must be provided, but it's recommended to pass a few more arguments than that. Refer to the actual curl documentation to find out about other options to pass.

request does not return anything, but will invoke the coderef passed via callback once the request is completed or had an error. The callback is invoked with two arguments, response and error, but only one of the two will be defined.

The response argument to the callback is a AnyEvent::YACurl::Response object, documented later in this pod, unless there was an error. If that was the case, the error argument to the callback will contain a human readable description of what went wrong.

    use Promises qw/deferred/;

    my $deferred = deferred;
    $client->request(
        sub {
            my ($response, $error) = @_;
            if ($error) {
                $deferred->reject($error);
            } else {
                $deferred->resolve($response->getinfo(CURLINFO_RESPONSE_CODE));
            }
        },
        {
            CURLOPT_URL => "https://www.perl.org",
            ...
        }
    );

AnyEvent::YACurl::Response

getinfo

Queries the curl API for information about the response. Refer to the curl documentation for possible CURLINFO_* options.

CURL OPTIONS

curl "multi" options may be passed to AnyEvent::YACurl->new({ ... }), and a list of all options can be found in the curl multi documentation. Most, but not all, options can be passed.

curl "easy" (request) options may be passed to $client->request({ ... }), and a list of all options can be found in the curl easy documentation. Most, but not all, options can be passed.

Some translation between Perl and curl value types has to be done. Many curl options take a number or string, and these will be converted from simple Perl scalars. When a curl option takes a curl_slist structure, a Perl array reference will be converted appropriately, like in the CURLOPT_HTTPHEADER example listed earlier.

Special care has to be taken with curl options that take a function, such as CURLOPT_WRITEFUNCTION. Their Perl signatures are documented below.

CURLOPT_WRITEFUNCTION

(See curl documentation)

Set callback for writing received data. This will be called with one argument, data, containing the received data.

    CURLOPT_WRITEFUNCTION => sub {
        my $data= shift;
        print STDERR $data;
    },

CURLOPT_HEADERFUNCTION

(See curl documentation)

Callback that receives header data. This will be called with one argument, data, containing the received data.

CURLOPT_READFUNCTION

(See curl documentation)

Read callback for data uploads. This will be called with one argument, length, indicating the maximum size of data to be read. The callback should either return a scalar with the data, an empty string to indicate the end of the transfer, or undef to abort the transfer.

    CURLOPT_READFUNCTION => sub {
        my $length= shift;
        return substr($my_data, 0, $length, '');
    },

CURLOPT_DEBUGFUNCTION

(See curl documentation)

Debug callback. Called with two arguments, type and data.

    CURLOPT_DEBUGFUNCTION => sub {
        my ($type, $data)= @_;
        if ($type == CURLINFO_TEXT) {
            print STDERR "curl: $data\n";
        }
    },

CURLOPT_TRAILERFUNCTION

(See curl documentation)

Set callback for sending trailing headers. Called without any arguments, expected output is a reference to an array of scalars representing headers to be sent out. undef may be returned to abort the request.

    CURLOPT_TRAILERFUNCTION => sub {
        return [
            "My-super-awesome-trailer: trailer-stuff",
        ];
    }

AUTHOR

Tom van der Woerdt <tvdw@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Tom van der Woerdt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.