view release on metacpan or  search on metacpan

lib/BusyBird/Manual/Tutorial.pod  view on Meta::CPAN

=pod

=head1 NAME

BusyBird::Manual::Tutorial - Tutorial to use BusyBird

=head1 Installation

First you need C<gcc>, C<make>, C<curl> and C<cpanm> command.
In Ubuntu Linux, for example, you can install them by

    $ sudo apt-get install build-essential curl cpanminus

These commands should be available in most other platforms, too.
If you have trouble installing C<cpanm>, see L<App::cpanminus>.

To install L<BusyBird>, type

    $ cpanm -n BusyBird

This may take time because it also installs many modules L<BusyBird> depends on.

If you are new to C<cpanm>, set the following environment variables.

    $ export PERL5LIB="$HOME/perl5/lib/perl5:$PERL5LIB"
    $ export PATH="$HOME/perl5/bin:$PATH"

These are necessary for perl to find the modules installed in C<~/perl5> directory.
Be sure to write them in C<~/.profile>, too.

=head1 Start BusyBird

After installing L<BusyBird> successfully, type

    $ busybird
    Twiggy: Accepting connections at http://127.0.0.1:5000/

Then, access the URL ( http://127.0.0.1:5000/ ) by your Web browser.
If you can see the top page, congraturations! L<BusyBird> has successfully started.

Note that if you already use the TCP port 5000, C<busybird> command fails with "Address already in use" error.
In that case, try another port by C<-p> option.

    $ busybird -p 4444

You can see complete list of options by C<-h> option.

    $ busybird -h

=head1 Input Statuses

By default, your L<BusyBird> instance has a timeline called "home", but the timeline has no status yet.
It won't magically import statuses out of nowhere.
You must input statuses to it.

To input statuses, you can use L<BusyBird>'s Web API.

    $ curl -d '{"text":"hello, world!"}' http://127.0.0.1:5000/timelines/home/statuses.json

C<< POST /timelines/home/statuses.json >> endpoint inputs statuses to the "home" timeline.
Statuses are in the HTTP request body, encoded in JSON.

You can input more than one statuses by posting an array of statuses. Here is a bit more complicated example.

    $ curl \
      -d '[{"text":"Hello, Bob!", "user":{"screen_name":"Alice"}}, {"text":"Hello, Alice!", "user":{"screen_name":"Bob"}}]' \
      http://127.0.0.1:5000/timelines/home/statuses.json

This time, the statuses have C<user.screen_name> fields.
L<BusyBird> renders this field as the person or object that created the status.

=head2 Import RSS/Atom Feeds

You now understand how to input statuses to L<BusyBird>, but it is boring to create statuses by hand.
So let's import RSS/Atom feeds into L<BusyBird>. It's very easy!

=over

=item 1.

Install another module L<BusyBird::Input::Feed>.

    $ cpanm BusyBird::Input::Feed

=item 2.

Then, run L<busybird_input_feed> command bundled with the module.

    $ busybird_input_feed https://metacpan.org/feed/recent -p http://127.0.0.1:5000/timelines/home/statuses.json

=back

After that, you can see the imported feed items (in this case, Perl modules recently uploaded) on L<BusyBird>.

Try repeating the command above.
You will see that L<BusyBird> only accepts the new statuses that are not yet in L<BusyBird>'s timeline.
In a L<BusyBird> timeline, all statuses must have unique C<id> field.
If you input a status that is already in the timeline, that status is ignored.

This means you can repeat the above command without worrying about duplicate statuses.
Register the command with C<cron>, then the L<BusyBird> timeline is automatically synchronized to
the latest state of the feed.


=head2 Import Statuses from Twitter

Next, let's import statuses (tweets) from L<Twitter|https://twitter.com/> and view them on L<BusyBird>.
That's a bit more tricky than importing feeds because it requires authentication.

To import tweets from Twitter via its API, you have to get the B<tokens> first. Here is how to get the tokens.

=over

=item 1.

Access L<https://apps.twitter.com/>.

=item 2.

"Sign in" with your Twitter account.

lib/BusyBird/Manual/Tutorial.pod  view on Meta::CPAN

        return $statuses;
    });

A status filter is just a subroutine reference in Perl.
It is called like

    $result_arrayref = $filter->($arrayref_of_statuses)

where C<$arrayref_of_statuses> is an array-ref of input statuses.

In the above example, the filter inspects each status's C<text> field.
If it finds your screen name ("@my_name"), it increments the status's level, meaning that it's important.
Then the filter returns the array of modified statuses.

A timeline can have more than one filters.
Those filters are executed in the order they are added, and the output of one filter becomes the input of the next filter.

    timeline("home")->add_filter(sub {
        my ($statuses) = @_;
        foreach my $status (@$statuses) {
            if($status->{text} =~ /\@my_name/) {
                $status->{busybird}{level}++;
            }
        }
        return $statuses;
    });
    timeline("home")->add_filter(sub {
        my ($statuses) = @_;
        return [grep { $_->{busybird}{level} > 4 } @$statuses];
    });

In the above example, the second filter extracts statuses whose level is higher than 4.

Inspecting statuses one by one is a typical pattern in status filters.
L<BusyBird::Filter> defines some functions useful for that purpose.

See L<BusyBird::Timeline> and L<BusyBird::Filter> for more about status filters.

=head2 Pre-defined Filter for Twitter

We have a pre-defined status filter named L<BusyBird::Filter::Twitter> for statuses imported from Twitter.

    timeline("home");
    
    use BusyBird::Filter::Twitter qw(:filter);
    timeline("home")->add_filter(filter_twitter_all);

It's not mandatory to use this filter, but we recommend it.
The filter fixes a bug where the status text is HTML-escaped twice.

For detail, see L<BusyBird::Filter::Twitter>.

=head1 What's Next?

For advanced and more detailed topics, see also the following documents.

=over

=item L<BusyBird::Manual::WebAPI>

Reference manual of L<BusyBird> Web API, including endpoints that get, post or ack statuses.

=item L<BusyBird::Manual::Status>

Object structure of L<BusyBird> statuses.

=item L<BusyBird::Manual::Config>

Full list of configuration items.

=item L<BusyBird::Filter>

Functions useful when writing status filters.

=item L<BusyBird::Main>

The class of the object returned by C<busybird> keyword in config.psgi.

=item L<BusyBird::Timeline>

The class of the object returned by C<timeline(...)> keyword in config.psgi.
It has various methods to manipuate statuses in it.

=back


=head1 AUTHOR

Toshio Ito C<< <toshioito [at] cpan.org> >>

=cut