BusyBird::Filter::Twitter - filters for statuses imported from Twitter


    use BusyBird;
    use BusyBird::Filter::Twitter qw(:all);
    use BusyBird::Filter qw(filter_each);
    ## or alternatively,
    timeline("home")->add_filter(filter_each sub {
        my ($status) = @_;


This module provides transformations and filters that you should apply to statuses imported from Twitter. Basically it does the following transformation to the input statuses.

  • Convert status IDs to include the source of the statuses. This prevents ID conflict between statuses from different sources.

  • Add BusyBird-specific fields to the statuses.

  • Normalize status objects from Search API v1.0.

  • HTML-unescape text content so that BusyBird can render it appropriately.

Note that this module does not help you import statuses from Twitter. For that purpose, I recommend Net::Twitter::Loader.

By default, this module exports nothing. You can import the following functions individually and/or by tags. Import ":all" to import all functions at once.

:transform TAG FUNCTIONS

These functions transform a single status object and return the result. The transformation is destructive.

$status = trans_twitter_all($status, [$api_url])

Applies all transformations described below to the given $status.

Argument $api_url is optional. See trans_twitter_status_id() function below.

$status = trans_twitter_search_status($status)

Transforms the $status returned by Twitter's Search API v1.0 into something more like a normal status object.

$status = trans_twitter_status_id($status, [$api_url])

Transforms the $status's ID fields so that they include API URL of the source. This transformation is recommended when you load statuses from multiple sources, e.g. and

Argument $api_url is optional. By default it is "". You should set it appropriately if you import statuses from other sites.

The original IDs are saved under $status->{busybird}{original}

$status = trans_twitter_unescape($status)

Unescapes some HTML entities in the $status's text field.

HTML-unescape is necessary because automatically HTML-escapes some special characters, AND BusyBird also HTML-escapes status texts when it renders them. This results in double HTML-escapes.

The transformation changes the status's text length. "indices" fields in the status's Twitter Entities are adjusted appropriately.

The transformation is applied recursively to the status's retweeted_status, if any.


These functions generate a synchronous status filter corresponding to the trans_twitter_* functions.

All filters are non-destructive. That is, they won't modify input statuses. Transformation is done to their clones.

$filter = filter_twitter_all([$api_url])

$filter = filter_twitter_search_status()

$filter = filter_twitter_status_id([$api_url])

$filter = filter_twitter_unescape()



Toshio Ito <toshioito [at]>