NAME

Twitter::API::Role::RequestArgs - API request method helpers

VERSION

version 0.0110

SYNOPSIS

    package MyApiMethods;
    use Moo::Role;

    sub timeline {
        shift->request_with_id(get => 'statuses/user_timeline, @_);
    }

Then, in your application code:

    use Twitter::API;

    my $client = Twitter::API->new_with_traits(
        traits => '+MyApiMethods',
        %othe_new_options,
    );

    my $statuses = $client->timeline('semifor');

    # equvalent to:
    my $statuses = $client->get('statuses/user_timeline', {
        screen_name => 'semifor',
    });

DESCRIPTION

Helper methods for implementers of custom traits for creating concise Twitter API methods. Used in Twitter::API::Trait::ApiMethods.

METHODS

request_with_id

Transforms an argument list with a required screen_name or user_id, optionally passed as a leading, positional argument, a hashref argument.

If a hashref follows the optional plain scalar, the user_id or screen_name is added to it. Otherwise a new hashref is created and inserted into @_.

If the optional plain scalar argument is missing, and there is hashref of arguments, or if the hashref does not contain the key screen_name or user_id, request_with_id croaks.

Examples:

    $self->request_with_id(get => 'some/endpoint', 'foo');
    # is transformed to:
    $self->request(get => 'some/endpoint', { screen_name => 'foo' });

    $self->request_with_id(get => 'some/endpoint', 8575429);
    # is transfromed to:
    $self->request(get => 'some/endpoint', { user_id => 8675429 });

    $self->request_with_id(get => 'some/endpoint', {
        screen_name => 'semifor',
    });
    # is transformed to:
    $self->request(get => 'some/endpoint', { screen_name => 'semifor' });

    $self->request_with_id(get => 'some/endpoint', {
        foo => 'bar',
    }); ### croaks ###

request_with_pos_args

Transforms a list of required arguments, optionally provided positionally in a determined order, into a hashref of named arguments. If a hashref follows the positional arguments, the named arguments are added to it. Otherwise, a new hashref in inserted into @_.

Zero or more of the required arguments may be provided positionally, as long as the appear in the specified order. I any of the required arguments are not provided positionally, they must be provided in the hashref or request_with_pos_args croaks.

The positional name :ID is treated specially. It is transformed to user_id if the value it represents contains only digits. Otherwise, it is transformed to screen_name.

Examples:

    $self->request_with_pos_args(
        [ 'id', 'name' ], get => 'some/endpoint',
        '007', 'Bond'
    );
    # is transformed to:
    $self->request(get => 'some/endpoint', {
        id   => '007',
        name => 'Bond',
    });

    $self->request_with_pos_args(
        [ 'id', 'name' ], get => 'some/endpoint',
        '007', { name => 'Bond' }
    );
    # is also transformed to:
    $self->request(get => 'some/endpoint', {
        id   => '007',
        name => 'Bond',
    });

    $self->request_with_pos_args(
        [ ':ID', 'status' ], get => 'some/endpoint',
        'alice', 'down the rabbit hole'
    );
    # is transformed to:
    $self->request(get => 'some/endpoint', {
        sreen_name => 'alice',
        status     => 'down the rabbit hole',
    });

AUTHOR

Marc Mims <marc@questright.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015-2016 by Marc Mims.

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