Skip to content

Commit

Permalink
Documentation changes and some restructuring
Browse files Browse the repository at this point in the history
  • Loading branch information
@semifor
semifor committed May 8, 2012
1 parent ec93f00 commit edb064e
Show file tree
Hide file tree
Showing 4 changed files with 111 additions and 249 deletions.
1 change: 0 additions & 1 deletion Makefile.PL
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ install_script 'bin/twirc';

requires 'AnyEvent::Twitter::Stream';
requires 'Config::Any';
requires 'Email::Valid' => 0;
requires 'Encode';
requires 'FindBin';
requires 'HTML::Entities';
Expand Down
26 changes: 23 additions & 3 deletions lib/App/Twirc.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,24 @@ has configfile => (
cmd_aliases => 'c',
isa => 'Str',
is => 'ro',
documentation => 'configration file name',
);

has background => (
metaclass => 'Getopt',
cmd_aliases => 'b',
isa => 'Bool',
is => 'ro',
documentation => 'run as daemon',
);

has authenticate => (
metaclass => 'Getopt',
cmd_aliases => [qw/a auth/],
isa => 'Bool',
is => 'ro',
default => 0
default => 0,
documentation => 'force Twitter authentication',
);

has state_file => (
Expand All @@ -37,6 +40,7 @@ has state_file => (
isa => 'Str',
is => 'ro',
predicate => 'has_state_file',
documentation => 'state file name',
);

has debug => (
Expand All @@ -45,6 +49,7 @@ has debug => (
isa => 'Bool',
is => 'ro',
default => 0,
documentation => 'set logging level to DEBUG',
);

sub run {
Expand Down Expand Up @@ -137,8 +142,8 @@ App::Twirc - IRC is my twitter client
use App::Twirc;
my $twirc = App::Twirc->new_with_options();
$twirc->run;
my $app = App::Twirc->new_with_options();
$app->run;
=head1 DESCRIPTION
Expand All @@ -159,6 +164,21 @@ Required. The name of the configuration file containing options for L<POE::Comp
Boolean value to determine whether to run in the foreground (0), or background (1).
=item authenticate
Forces OAuth authentication with Twitter, supplying a URL for Twitter OAuth
authentication and prompting for the OAuth verifier PIN. Use this method
re-authenticate with Twitter, if necessary.
=item state_file
Specifies a file name for loading/storing state information, including a list
of friends, followers_ids, and OAuth access tokens.
=item debug
Boolean, when set to 1, enables DEBUG level logging.
=back
=head1 METHODS
Expand Down
179 changes: 21 additions & 158 deletions lib/App/Twirc/Manual.pod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,42 +39,15 @@ you choose this option, run C<make> to install C<twirc>'s dependencies.
C<Twirc> uses L<Config::Any>, so you can configure C<twirc> using XML, YAML,
JSON, Apache-style configuration, Windows INI file format, or even Perl code.

Here's a minimal configuration in YAML:
A configuration file is not necessary, but is recommended.

irc_nickname: MyIRCNick
twitter_username: my_email_address@example.com
twitter_password: secret
twitter_screen_name: MyTwitterScreenName
Here's an example configuration in YAML:

state_file: twirc.state
log_level: INFO

=head2 REQUIRED CONFIGURATION OPTIONS

=over 4

=item irc_nickname

The irc nickname used by the owning user. This is the nickname I<you> will use
when you connect to the C<twirc> IRC server.

=item twitter_username

The username (email address) used to authenticate with Twitter. This is the ID
C<twirc> will use to authenticate with Twitter.

=item twitter_password

The password used to authenticate with Twitter. This is the password C<twirc>
will use to authenticate with twitter.

=item twitter_screen_name

The user's Twitter screen name. This is I<your> screen name on Twitter. It may
very well be the same as your C<irc_nickname>, but it certainly doesn't have to
be.

=back

=head2 OPTIONAL CONFIGURATION OPTIONS
=head2 CONFIGURATION OPTIONS

=over

Expand Down Expand Up @@ -129,23 +102,6 @@ to C<&twitter>. The IRC convention for channels names is channels local to a
single server begin with C<&>. Network channels begin with C<#>. You can use
either to name, however C<&> is more appropriate.

=item twitter_retry

The number of seconds between polls for new status updates, replies, and direct
messages. Defaults to 300 (5 minutes). Twitter imposes a rate limit of 100
API calls per hour. By default, after initial start up, twirc makes a single
API call every C<twitter_retry> seconds. Adding L</"check_replies"> and
L</"check_direct_messages"> each add an additional API call. Setting
C<twitter_retry> too low can cause twirc to exceed the rate limit and delay
receipt of messages.

Use the L</"rate_limit_status"> command to check your available API calls.

=item twitter_retry_on_error

The number of seconds to wait before retrying a failed twitter API call in the
polling loop. Defaults to 60 (1 minute).

=item twitter_alias

An alias to use for displaying incoming status updates from the owning user.
Expand All @@ -156,60 +112,17 @@ With the default value C<me>, when C<twirc> reads a status message in your
timeline from your Twitter screen name, it will use C<me> in place of your
Twitter screen name in the channel.

=item echo_posts

If false, posts sent by C<twirc> will not be redisplayed when polling the
timeline. Defaults to 0 (false).
=item selection_count

This option in off, be default, to prevent some unnecessary noise in the
channel. When you post a new status message with C<twirc>, you will see your
post command, including your status message in the channel. Tweeter, the bot,
will send your status update to twitter, and then set the channel topic to your
message. If your IRC client displays notices, you will see your message a
second time in status change. If this option is set to true, you will see it a
third time, when C<twirc> next polls Twitter for new status messages.

So, why would you ever want C<echo_posts> on? C<Twirc> polls Twitter for new
messages every 5 minutes, by default. So, there may be messages waiting and
other messages received after your status update, but before C<twirc> checks
for new messages again. With C<echo_posts> on, you will see your message
again, in chronological order with the rest of the incoming messages.

=item favorites_count

How many favorites candidates to display for selection. Defaults to 3.

When you use the L</"favorite"> command, a list of recent status from the
friend your a favoriting are displayed for you to choose from. This option
tell C<twirc> how many of those messages to display.
How many status messages to display for selection when favoriting, replying, or
retweeting. Defaults to 3.

=item truncate_to

When displaying a list tweets for selection, for example, in response to the
L</"favorite"> command, they will be truncated to this length to avoid
cluttering the screen with long messages that wrap. Defaults to 60.

=item check_replies

Defaults to 0 (off). If set to 1 (on), checks for @replies when polling for
friends' timeline updates and merges them with normal status updates.
Normally, only replies from friends you are following are displayed, just like
your home page on Twitter. This provides the display of @replies from users
not followed.

C<check_replies> adds an API call, counted against Twitter's rate limit
every L</"twitter_retry"> seconds.

(This also has the effect of adding senders of @replies to the channel,
even though they are not followed.)

=item check_direct_messages

If true, checks for direct messages in each timeline polling cycle.

C<check_direct_messages> adds an API call, counted against Twitter's rate limit
every L</"twitter_retry"> seconds.

=item log_channel

If specified, twirc will post log messages to this channel. If you set this
Expand All @@ -219,52 +132,25 @@ shooting or problem reporting.

=item state_file

File used to store state information between sessions, including last message read for
replies, direct messages, and timelines.

By default, C<twirc> does not save any state information between runs. When
you start C<twirc> it grabs the most recent 20 messages in the timeline and
displays them, even if they are the same 20 messages it displayed last time
your ran C<twirc>.

If you use L</"check_direct_messages"> you will definitely want to use a state
file so that you do not receive the same batch of direct messages every time
you start C<twirc>.

If you do provide a C<state_file> name, C<twirc> will save the last message ID
it processed of each type (friends_timeline, user_timeline, replies, and direct
messages). It won't redisplay messages it as already displayed on a previous
run.

C<Twirc> will still only show the most recent 20 messages on restart, though.
The C<state_file> option just prevents redisplaying messages already seen.

=item verbose_refresh

Default 0 (off). If set, when a refresh (whether automatic or the result of
the L</"refresh"> command) finds no new messages, a notice to that effect will
be written to the channel.

=cut
File used to store state information between sessions, including Twitter OAuth
access tokens, friends, and followers_ids.

=back

=head1 USING

To use C<twirc> you first need to start the server:

bin/twirc -c twirc.yml -b
bin/twirc -b --state_file=twirc.state

The C<-b> option runs C<twirc> in the background. Drop the C<-b> to see
copious log messages to STDERR.
The C<-b> option runs C<twirc> in the background. Drop the C<-b> to see log
messages to STDERR. (The author runs twirc and his irc client in screen,
L<http://www.gnu.org/software/screen/>, to monitor log messages to STDERR.)

Next, connect to the server from your IRC client. I use C<irssi>
(L<http://www.irssi.org>) and my examples will use C<irssi> commands:

/connect localhost 6667 secret

where C<secret> is the password set in the config file with option
L</"irc_password">. Your IRC client may use different commands.
/connect localhost

On connection, C<twirc> will automatically join you to the configured channel.
The default C<&twitter> will be assumed, here.
Expand All @@ -288,12 +174,7 @@ Is a shortcut for:

post @twirc you make twitter usable!

By default, C<twirc> checks for updates every 5 minutes. You can have it check
immediately using the L</"refresh"> command:

refresh

C<Twirc> will check for messages immediately, then again every 5 minutes.
C<twirc> uses the Twitter User Streams API to recieve updates in real-time.

Use IRC private messaging to send direct messages. In C<irssi>:

Expand Down Expand Up @@ -349,14 +230,6 @@ Mark a friend's tweet as a favorite. Optionally, specify the number of tweets
to display for selection with C<count>. (C<count> defaults to 3. The default
can be changed with the L</"favorites_count"> option.)

=item check_replies on|off

Turns reply checking on or off. See L</"check_replies"> in configuration.

=item check_direct_messages on|off

Turns direct message checking on or off. See L</"check_direct_messages"> in configuration.

=item rate_limit_status

Displays information about the remaining number of API requests available in
Expand All @@ -367,10 +240,6 @@ limit, itself.

Display a simple help message listing the available command names.

=item verbose_refresh on|off

Turns C<verbose_refresh> on or off. See L</"verbose_refresh"> in configuration.

=back

=head1 TIPS AND TRICKS
Expand Down Expand Up @@ -400,19 +269,13 @@ First, the pertinent sections of the configuration files (in YAML format).

# File: semifor.yml
irc_server_port: 6667
irc_password: secret
irc_channel: '&twitter'
irc_nickname: semifor
twitter_screen_name: semifor
state_file: semifor.state
# ...

# File: twirc.yml
irc_server_port: 6668
irc_password: secret
irc_channel: '&twirc'
irc_nickname: twirc
twitter_screen_name: twirc
state_file: twirc.state
# ...

Next, start an instance for each account:

Expand All @@ -421,8 +284,8 @@ Next, start an instance for each account:

In your IRC client, connect to both instances (C<irssi> here):

/connect localhost 6667 secret_password semifor
/connect localhost 6668 secret_password twirc
/connect localhost 6667 secret semifor
/connect localhost 6668 secret twirc

Now you've got 2 channels, one for each account---in my case, C<&twitter> for
C<semifor> and C<&twirc> for C<twirc>.
Expand Down Expand Up @@ -455,7 +318,7 @@ compatible, like Identi.ca) accounts. See L<App::Twirc::Plugin::SecondaryAccoun

C<Twirc> is free open source software with no warranty of any kind. That said,
it's used by some competent perl coders who may be able to help if you have
trouble. Try the #net-twitter channel at C<irc.perl.org>.
trouble. Try the C<#net-twitter> channel at C<irc.perl.org>.

The code repository with the development branch is located at
L<http://github.com/semifor/twirc>. New features, and bug fixes appear there
Expand Down
Loading

0 comments on commit edb064e

Please sign in to comment.