baconbird

#!/usr/bin/perl

use strict;
use warnings;
use lib "lib";

use Data::Dumper;
use BaconBird::Config;
use BaconBird::Controller;
use BaconBird::Model;
use BaconBird::View;
use BaconBird::Shortener;
use BaconBird::KeyMap;

$0 = 'baconbird';
my $cfg = BaconBird::Config->new;
my $keymap = BaconBird::KeyMap->new(config => $cfg);
my $shortener = BaconBird::Shortener->new(config => $cfg);

my $ctrl = BaconBird::Controller->new({ keymap => $keymap, shortener => $shortener, config => $cfg });

$ctrl->model(BaconBird::Model->new(ctrl => $ctrl, config => $cfg));
$ctrl->view(BaconBird::View->new(ctrl => $ctrl, config => $cfg));

$ctrl->run;

__END__

=head1 Documentation for Baconbird, a Twitter Client

Andreas Krennmair <L<ak@synflood.at>>

=head2 Introduction

Baconbird is a Twitter client for text terminals. Twitter is a popular 
microblogging service, allowing users to publish their own short messages 
called "tweets". Baconbird is intended to run on any Unix-like platform
that is supported by the programming language Perl and the STFL library.

=head2 Installation

=head3 Downloading Baconbird

You can download baconbird releases from the baconbird website: L<http://synflood.at/baconbird.html>
The latest source code can be found on GitHub: L<http://github.com/akrennmair/baconbird>

=head3 Dependencies

Baconbird depends on a number of packages and libraries to work correctly, as 
listed below:

=over 12

=item * Perl 5.10 or newer: L<http://www.perl.org/>

=item * STFL: L<http://www.clifford.at/stfl/>

=item * Perl modules:

=over 12

=item * Moose

=item * Net::Twitter

=item * WWW::Shorten

=item * URI::Find

=item * HTML::Strip

=item * IO::Socket::SSL

=item * Config::General

=back

=back

Debian comes with ready-to-use packages for these dependencies and is thus the 
recommended distribution to use.

=head3 Installation

Installing baconbird is as simple as:

	perl Makefile.PL
	make
	make install

The first command will generate a Makefile and check BaconBird's dependencies. 
The second command will prepare BaconBird for installation and generate 
documentation, while the third command will install BaconBird.

When using "make install", you have the usual parameters "prefix" and "DESTDIR" 
available to control where your program will be installed and where the 
installation files will be copied to.

=head2 Using Baconbird

The first time you start, baconbird, it will inform you to authenticate with 
Twitter. Login to Twitter, then open the URL as printed on the screen, confirm 
that you want to allow Baconbird access to your Twitter account, and then enter 
the shown PIN into the baconbird prompt.

After you successfully accomplished that, baconbird's main screen will open. It 
is divided into several main components. The topmost line shows the program 
name and version, the view in which you currently are ("Home Timeline" by 
default), and on the top right corner, when the API rate limit is reset, how 
many API calls you still have available, and how many how have available in 
total per cycle. Don't worry, unless you send several hundred tweets or do 
several hundred searches by hour, baconbird will make sure that you never run 
out of API calls to the Twitter servers.

Below the topmost line, the screen is dominated by the list that displays the 
tweets of the currently selected timeline. Below that, you have additional 
information about the currently selected tweet, such as sender, the time when 
it was posted, and the original URL.

Below that, you have a quick reminder about the most important keystrokes that 
baconbird understands. Below that you find the "last line", which displays 
information about operations that are currently ongoing and where prompts are 
presented to the user.

=head3 Timelines

=head4 Home Timeline

The Home Timeline is selected by default, and shows your own tweets and the 
tweets of those users you are subscribed to. It can be selected by pressing 
C<1>.

=head4 Mentions

The Mentions timeline shows the tweets where your username is mentioned (i.e. 
prefixed with C<@>). It can be selected by pressing C<2>.

=head4 Direct Messages

Twitter allows sending and receiving non-public direct messages between users. 
The Direct Messages timeline shows the latest direct messages. It can be 
selected by pressing C<3>.

=head4 Search Results

Baconbird offers the ability to run search queries. A user can do this by 
pressing the C</> key, and entering a search query. A list of matches is then 
presented and continuously updated. A user can then select another timeline, 
and switch back to the search result timeline by pressing C<4>. The updates on 
the search results are then continued.

=head4 User Timeline

There are two ways of showing an user's timeline. You can press C<u> while
having selected a tweet, and that user's timeline will be displayed. Also, you
can press C<l>, and a field to enter a user's screen name will appear. Once you
press C<ENTER>, and if that uses exists, that user's timeline will be loaded.

=head4 Favorites

You can see all your favorites by pressing C<V>. These are the tweets that
you've marked as favorites.

=head4 My Retweets

By pressing C<6>, you will load a timeline that shows all the tweets that you
have retweeted.

=head4 Retweets of Me

C<7> will show you a timeline with all the tweets that you've posted that have
been retweeted.

=head4 My Timeline

If you want to see all your tweets, you can press C<8>.

=head4 Friends

To see your friends (users you follow), press C<I>.

=head4 Followers

To see who follows you, press C<E>.

=head3 Functions

=head4 Automatic Reloads

The currently selected timeline is continuously updated, there is no need for 
the user to trigger such updates in any way.

=head4 Sending Tweets

To send a new tweet, a user simply needs to press the C<ENTER> key. An input 
field will then open in the last line, where the user can then enter the text.  
On the right side, the number of remaining characters is displayed. The user is 
additionally warned by colors when the number of characters becomes more than 
what is allowed with Twitter.

To make tweets that contain URLs shorter, baconbird contains integration with 
the URL shortening service L<http://is.gd/>. Users whose tweets contain URLs 
can press C<Ctrl-O>, and all URLs in the tweet will be shortened. Baconbird 
always makes sure that the tweet doesn't get longer through this URL. Also, 
URLs that already are shortened by a previous operation will not be shortened 
again. This allows that users can press C<Ctrl-O> more than once while posting 
a tweet.

In the Direct Messages timeline, the C<ENTER> key will send a new direct 
message, first asking for the recipient and then for the message.

=head4 Retweeting

To retweet another user's tweet to your own timeline, a user only needs to
select this tweet and press C<Ctrl-R>. Direct messages can't be retweeted.
Retweets will be marked with a "R" in the second leftmost column of the screen.

=head4 Replies

When a user presses C<r> (reply) or C<R> (public reply), baconbird will open a 
prompt to enter a reply to the currently selected tweet. It will prefix the 
message by addressing the sender of the tweet to which you reply. The 
difference between "regular" and public replies is that public replies are 
additionally prefixed with a dot (".") so that all your followers, even those who 
don't follow the addressed user, can read the reply.

=head4 Searching

As mentioned above, baconbird allows searching for phrases by pressing C</>.
The search results will then be regularly updated. The latest result for the
last search can be always retrieved by pressing C<5>.

=head4 Detail View

To see a complete, more detailed view of a tweet, press C<v> and a panel will
pop up on the lower part of the screen. Not only will it show the complete text
of the tweet (line-wrapped, in case your terminal is not wide enough), you will
also find additional information about the author, including name, screen name,
location, description, URL and number of tweets, followers and friends.
Pressing C<v> again hides the detail view.

=head4 Favorites

If you want to favorite a tweet, you can select it and press C<Ctrl-F>.
Favorite tweets will be marked with a "!" in the leftmost column of the
screen. To unfavorite a favorite tweet, press C<Ctrl-F> again.

=head4 Following and Unfollowing

There are two ways to follow another user. You can either follow the author of
the currently selected tweet or direct message (just press C<F>), or you can
follow any user by pressing C<f> and entering the desired screen name.

To unfollow a user, select a tweet or direct message and press C<U>.

=head4 Highlighting

You can highlight expressions on the screen by adding these terms to the
configuration file. (See L</Configuration>). You can press C<h> and a prompt
will be shown where you can enter an expression to be highlighted.
L<Regular expressions|perlre> are accepted. To stop highlighting those
expressions again, you can press C<e> again and enter the same expression.

=head4 Hiding

You can hide tweets that match a certain expression by adding the terms that you
want hidden to the configuration file. (See L</Configuration>). You can also
press C<e> to enter the expression you want hidden. To show those expressions
again, you can press C<e> again and enter the same expression.

=head4 Saved Searches

You can save a search by pressing C<s> once you've searched for something. You
can later press C<l> to see what your saves search expressions are. You can
reload a saved search by pressing C<ENTER> or C<y> over a saved search query.
You can delete a saved search by pressing C<d>. You can cancel by pressing
C<ESC> or C<n>.

=head2 Keybindings

These are the default keybindings. You can always type C<?> to display the
current bindings. The lower-case identifiers in parentheses beside the keys can 
be used to customize the key map in the configuration file (see below).

=over 12

=item * C<q> (quit): Quit baconbird.

=item * C<ENTER> (send): Send a new tweet or direct message.

=item * C<Ctrl-R> (retweet): Reteet currently selected tweet.

=item * C<r> (reply): Reply to currently selected tweet or direct message.

=item * C<R> (public_reply): Publicly reply to currently selected tweet.

=item * C<Ctrl-O> (shorten): Shorten all URLs in the current input field.

=item * C<1> (home_timeline): Go to home timeline.

=item * C<2> (mentions): Go to mentions.

=item * C<3> (direct_messages): Go to direct messages.

=item * C<4> (search_results): Go to search results (if search function was used before).

=item * C<5> (user_timeline): Go to user timeline (if show user function was used before).

=item * C<6> (retweeted_by_me): Show tweets retweeted by me.

=item * C<7> (retweets_of_me): Show my tweets that were retweeted.

=item * C<8> (my_timeline): Show my tweets.

=item * C<V> (favorites): Show favorite tweets.

=item * C<g> (goto_user): Go to a given user timeline.

=item * C</> (search): Start new search.

=item * C<u> (show_user): Show timeline of currently selected tweet's author.

=item * C<Ctrl-F> (toggle_favorite): Toggle favorite flag of currently selected tweet.

=item * C<?> (help): Show help.

=item * C<F> (follow): Follow author of currently selected tweet.

=item * C<U> (unfollow): Unfollow author of currently selected tweet.

=item * C<f> (follow_user): Follow a user. You will be asked for the user name.

=item * C<v> (view): Toggle detail view of currently selected tweet.

=item * C<o> (open_url): Open URLs in tweet in default browser.

=item * C<Ctrl-L> (redraw): Redraw screen.

=item * C<h> (enter_highlight): Enter an expression to highlight. Enter it again to un-highlight.

=item * C<e> (enter_hide): Enter an expression to hide. Enter it again to show.

=item * C<s> (save_search): Save current sought for expression

=item * C<l> (load_search): Load saved search.

=item * C<d> (delete): Delete item.

=item * C<Ctrl-T> (edit_external): Edit tweet in an external editor.

=back

=head2 Configuration

baconbird is configured by $HOME/.baconbird/config. The following configuration
options are supported:

=over

=item * browser

	browser = "links %u"

=item * editor

	editor = 'vim'

=item * filters

	<filters>
		highlight "foobar"             # highlights all occurences of "foobar"
		highlight "https?://[^ ]*"     # highlights all URLs
		hide "@someuser"               # hides tweets containing "@someuser"
		hide "quux"                    # hides tweets containing "quux"
	</filters>

=item * keymap

In this configuration section you can modify the default keybinding by 
specifying the key that shall be modified (by using the identifier as listed 
above) and a key or key combination. Regular single alpha-numeric and symbolic 
keys are written as themselves, the return key is written as ENTER, the Esc key 
is written as ESC, while key combinations involving the control key are written 
as "^" plus another key, e.g. "^G" for C<Ctrl-G>.

	<keymap>
		edit_external ^I               # remaps "edit_external" to Ctrl-I
	</keymap>

=item * timeline_format

This configuration option makes it possible to specify a custom format in the 
timeline overview. This is done by specifying a format string similar to printf().

The following format identifiers are available:

=over

=item * %d: creation date/time of the tweet. This format identifier needs an additional strftime(3)-style format string in curly brackets before the d in %d (see below for an example).

=item * %i: position index of the tweet

=item * %F: favorite flag

=item * %R: retweeted flag

=item * %u: user name

=item * %t: tweet text

=back

All these format can be aligned left or right by prepending a positive or negative field size.

	timeline_format = "%F%R[%16u] %t"             # default configuration
	timeline_format = "%4i %{%H:%M}d [%16u] %t"   # example showing the use of %d

=back

=head2 License

MIT/X Consortium License

(C)opyright 2010-2011 Andreas Krennmair E<lt>ak@synflood.atE<gt>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

=cut