NAME

Net::Twitter::Loader - repeat loading Twitter statuses up to a certain point

SYNOPSIS

    use Net::Twitter::Loader;
    use Net::Twitter;
    
    my $loader = Net::Twitter::Loader->new(
        backend => Net::Twitter->new(
            traits => [qw(OAuth API::RESTv1_1)],
            consumer_key => "YOUR_CONSUMER_KEY_HERE",
            consumer_secret => "YOUR_CONSUMER_SECRET_HERE",
            access_token => "YOUR_ACCESS_TOKEN_HERE",
            access_token_secret => "YOUR_ACCESS_TOKEN_SECRET_HERE",
            ssl => 1,
    
            #### If you access to somewhere other than twitter.com,
            #### set the apiurl option
            ## apiurl => "http://example.com/api/",
        ),
        filepath => 'next_since_ids.json',
        logger => sub {
            my ($level, $msg) = @_;
            warn "$level: $msg\n";
        },
    );
    
    ## First call to home_timeline
    my $arrayref_of_statuses = $loader->home_timeline();
    
    ## The latest loaded status ID is saved to next_since_ids.json
    
    ## Subsequent calls to home_timeline automatically load
    ## all statuses that have not been loaded yet.
    $arrayref_of_statuses = $loader->home_timeline();
    
    
    ## You can load other timelines as well.
    $arrayref_of_statuses = $loader->user_timeline({screen_name => 'hoge'});
    
    
    foreach my $status (@$arrayref_of_statuses) {
        printf("%s: %s\n", $status->{user}{screen_name}, Encode::encode('utf8', $status->{text}));
    }

DESCRIPTION

This module is a wrapper for Net::Twitter (or Net::Twitter::Lite) to make it easy to load a lot of statuses from timelines.

FEATURES

• It repeats requests to load a timeline that expands over multiple pages. max_id param for each request is adjusted automatically.

• Optionally it saves the latest status ID to a file. The file will be read to set since_id param for the next request, so that it can always load all the unread statuses.

CLASS METHODS

$loader = Net::Twitter::Loader->new(%options);

Creates the object with the following %options.

backend => OBJECT (mandatory)

Backend Net::Twitter object. Net::Twitter::Lite object can be used, too.

filepath => FILEPATH (optional)

File path for saving and loading the next since_id. If this option is not specified, no file will be created or loaded.

page_max => INT (optional, default: 10)

Maximum number of pages this module tries to load when since_id is given.

page_max_no_since_id => INT (optional, default: 1)

Maximum number of pages this module tries to load when no since_id is given.

page_next_delay => NUMBER (optional, default: 0)

Delay in seconds before loading the next page. Fractional number can be used.

logger => CODE (optional)

A code-ref for logging. If specified, it is called to log what this module is doing.

    $logger->($level, $message)

The logger is called with $level and $message. $level is the log level string (e.g. "debug", "error" ...) and $message is the log message.

If logger is omitted, the log is suppressed.

OBJECT METHODS

$status_arrayref = $loader->home_timeline($options_hashref)

$status_arrayref = $loader->user_timeline($options_hashref)

$status_arrayref = $loader->list_statuses($options_hashref)

$status_arrayref = $loader->public_statuses($options_hashref)

$status_arrayref = $loader->favorites($options_hashref)

$status_arrayref = $loader->mentions($options_hashref)

$status_arrayref = $loader->retweets_of_me($options_hashref)

Wrapper methods for corresponding Net::Twitter methods. See Net::Twitter for specification of $options_hashref.

Note that Net::Twitter accepts non-hashref arguments for convenience, but this is not supported by Net::Twitter::Loader. You always need to give a hash-ref to these methods.

If since_id is given in $options_hashref or it is loaded from the file specified by filepath option, these wrapper methods repeatedly call Net::Twitter's corresponding methods to load a complete timeline newer than since_id. If filepath option is enabled, the latest ID of the loaded status is saved to the file.

The max number of calling the backend Net::Twitter methods is limited to page_max option if since_id is specified or loaded from the file. The max number is limited to page_max_no_since_id option if since_id is not specified.

If the operation succeeds, the return value of these methods is an array-ref of unique status objects.

If something is wrong (e.g. network failure), these methods throw an exception. In this case, the error is logged if logger is specified in the constructor.

$status_arrayref = $loader->search($options_hashref)

Same as other timeline methods, but note that it returns only the statuses of the search result.

Original Twitter API returns other fields such as "search_metadata", but those are discarded.

$backend = $loader->backend()

Get the backend Net::Twitter or Net::Twitter::Lite object.

SEE ALSO

• Net::Twitter

• Net::Twitter::Lite

REPOSITORY

https://github.com/debug-ito/Net-Twitter-Loader

BUGS AND FEATURE REQUESTS

Please report bugs and feature requests to my Github issues https://github.com/debug-ito/Net-Twitter-Loader/issues.

Although I prefer Github, non-Github users can use CPAN RT https://rt.cpan.org/Public/Dist/Display.html?Name=Net-Twitter-Loader. Please send email to bug-Net-Twitter-Loader at rt.cpan.org to report bugs if you do not have CPAN RT account.

AUTHOR

Toshio Ito, <toshioito at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2014 Toshio Ito.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm Net::Twitter::Loader

perl -MCPAN -e shell
install Net::Twitter::Loader