BusyBird::Manual::Config - how to configure BusyBird
In your ~/.busybird/config.psgi
use BusyBird; busybird->set_config( timeline_list_per_page => 100, time_zone => "UTC", time_locale => "en_US", ); timeline("home")->set_config( time_zone => "+0900" ); end;
By default, BusyBird reads the file ~/.busybird/config.psgi for configuration. If it doesn't exist, busybird command automatically generates it.
~/.busybird/config.psgi
You can use an arbitrary config file by specifying it to busybird command.
$ busybird another_config.psgi
The configuration file is just a Perl script (actually it's PSGI application script). Its basic structure is:
use BusyBird; ## Your configuration here end;
Leave every statement busybird command generated unless you know what you're doing.
To create a timeline, call timeline() function.
timeline()
timeline("timeline A"); timeline("timeline B");
timeline() function returns a BusyBird::Timeline object. You can call its methods to manipulate the timeline.
my $timeline = timeline("timeline A"); $timeline->add({text => "Hello."});
Timeline names are unique. If you call timeline() the second time with the same timeline name, it just returns the existing timeline.
Global config parameters are set by busybird->set_config() method.
busybird->set_config()
busybird->set_config(time_zone => "UTC");
A global config parameter affects all timelines and the overall behavior of the BusyBird instance.
Per-timeline config parameters are set by timeline(...)->set_config() method.
timeline(...)->set_config()
busybird->set_config(time_zone => "UTC"); timeline("foobar")->set_config(time_zone => "+0900");
Per-timeline config parameters always take precedence over global ones. Any per-timeline config parameter can be set as a global config parameter.
Config parameters are stored in BusyBird::Main and BusyBird::Timeline objects. The keyword busybird is a function that returns the singleton object of BusyBird::Main class. See "AS A MODULE" in BusyBird for detail.
busybird
When BusyBird needs some config parameters, it reads them by calling get_config() and get_timeline_config() methods on BusyBird::Main.
get_config()
get_timeline_config()
Below is the complete list of the global config parameters.
Internally, those config parameters are accepted by BusyBird::Main.
default_status_storage
Default: BusyBird::StatusStorage::SQLite object at ~/.busybird/statuses.sqlite3
~/.busybird/statuses.sqlite3
A StatusStorage object used for Timelines by default.
A StatusStorage is an object where timelines save their statuses. When a timeline is created by BusyBird::Main's timeline() method, the default StatusStorage is used for the timeline.
Note that the default StatusStorage object is referred to only when creating timelines via timeline() method. Existing timelines are not affected by changing the default StatusStorage object.
A StatusStorage object is an implementation of BusyBird::StatusStorage interface. For example, the following modules can be used as StatusStorage.
BusyBird::StatusStorage::SQLite - storage backed by SQLite database
BusyBird::StatusStorage::Memory - storage in the process memory
See each module's documentation for details.
sharedir_path
Default: sharedir in your BusyBird installation directory
File path to "share" directory.
"share" directory contains static files used by BusyBird, which include HTML templates, JavaScript files and image files.
See BusyBird::Manual::Config::Advanced for an example to use this parameter.
timeline_list_per_page
Default: 30
Number of timelines shown in a single page of the timeline list.
timeline_list_pager_entry_max
Default: 7
Maximum number of page entries shown in the pagination of the timeline list page.
Below is the complete list of the per-timeline config parameters.
Note that any of the per-timeline config parameters can be used as a global config parameter, too.
Internally, those config parameters are accepted by BusyBird::Main and BusyBird::Timeline.
time_zone
Default: "local"
"local"
Timezone used to render status timestamps. TIMEZONE_STR accepts various timezone names such as "UTC", "America/Chicago", "+0900", "-0300". See DateTime::TimeZone and DateTime::TimeZone::Catalog for the list of valid timezone names.
TIMEZONE_STR
"UTC"
"America/Chicago"
"+0900"
"-0300"
You can set special value "local" to TIMEZONE_STR. This means the timezone of the local environment is used.
time_format
Default: "%x (%a) %X %Z"
"%x (%a) %X %Z"
Format used to render status timestamps. The format string conforms to the strftime(3) specification.
strftime(3)
time_locale
Default: LC_TIME environment variable or "C"
LC_TIME
"C"
Locale used to render status timestamps.
LOCALE_STR is a valid locale string such as "en_US", "ja_JP" etc.
LOCALE_STR
"en_US"
"ja_JP"
post_button_url
Default: "https://twitter.com/intent/tweet"
"https://twitter.com/intent/tweet"
Link URL attached to the "Post" button in the navigation bar.
status_permalink_builder
Default: return $status->{busybird}{status_permalink}, or build permalink to the status page of twitter.com, or return undef
$status->{busybird}{status_permalink}
undef
Subroutine reference that is supposed to build permalink URL to the status.
The builder subroutine reference is called with the status object, as in:
$url_str = $builder->($status)
$url_str is a string. If the result $url_str is undef or does not look like a valid URL, it is ignored.
$url_str
urls_entity_url_builder
Default: return $entity->{url}
$entity->{url}
media_entity_url_builder
user_mentions_entity_url_builder
Default: build URL to the user page of twitter.com
hashtags_entity_url_builder
Default build URL to the hashtag search page of twitter.com
The above four configurations specify how Twitter Entities in a status object generate link URLs attached to the status text.
The builder subroutine reference is called in the following way
$url_str = $builder->($text, $entity, $status)
where $text is the segment of status text the entity is attached to, $entity is the Twitter Entity object, and $status is the whole status object. $url_str is a string.
$text
$entity
$status
If the result $url_str is undef or does not look like a valid URL, it is ignored, i.e., the text is not linked.
urls_entity_text_builder
Default: return $entity->{display_url}
$entity->{display_url}
media_entity_text_builder
user_mentions_entity_text_builder
Default: return $text
hashtags_entity_text_builder
The above four configurations specify how Twitter Entities in a status object convert status texts to be displayed.
$text_to_be_displayed = $builder->($text, $entity, $status)
where $text is the segment of status text the entity is attached to, $entity is the Twitter Entity object, and $status is the whole status object. $text_to_be_displayed is a string.
$text_to_be_displayed
If $text_to_be_displayed is undef, the original $text is used for display.
If a *_entity_url_builder subroutine reference returns non-URL for the $entity, the text is not linked and the corresponding *_entity_text_builder is not called.
*_entity_url_builder
*_entity_text_builder
Status timestamps are rendered using time_zone, time_format, time_locale parameters. By default BusyBird guesses the "correct" config for your system.
busybird->set_config( time_zone => 'America/Los_Angeles', time_format => '%Y-%m-%d %A %H:%M:%S %Z', time_locale => 'en_US', );
By default BusyBird renders Twitter Entities in status objects just like Twitter does, but you can customize this behavior by changing *_entity_url_builder and *_entity_text_builder parameters.
For example, Twitter truncates the displayed text for urls and media entites. If you want to see fully expanded URLs in statuses, do the following.
urls
media
my $builder_expanded_url = sub { my ($text, $entity) = @_; return $entity->{expanded_url}; }; busybird->set_config( urls_entity_text_builder => $builder_expanded_url, media_entity_text_builder => $builder_expanded_url, );
By default, BusyBird stores statuses in the file ~/.busybird/statuses.sqlite3.
To change the storage file location, change default_status_storage global config parameter.
use BusyBird::StatusStorage::SQLite; busybird->set_config( default_status_storage => BusyBird::StatusStorage::SQLite->new( path => "$ENV{HOME}/.busybird/another_statuses.sqlite3" ) );
The example uses ~/.busybird/another_statuses.sqlite3 for the status storage. See BusyBird::StatusStorage::SQLite for detail.
~/.busybird/another_statuses.sqlite3
Note that you should change default_status_storage parameter before you call timeline() function.
Advanced topics about configuring BusyBird.
Toshio Ito <toshioito [at] cpan.org>
<toshioito [at] cpan.org>
To install BusyBird, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BusyBird
CPAN shell
perl -MCPAN -e shell install BusyBird
For more information on module installation, please visit the detailed CPAN module installation guide.