Permalink
Browse files

Documentation changes and some restructuring

  • Loading branch information...
1 parent ec93f00 commit edb064e49798f66d6413cc15453771aec76ee202 @semifor committed May 8, 2012
Showing with 111 additions and 249 deletions.
  1. +0 −1 Makefile.PL
  2. +23 −3 lib/App/Twirc.pm
  3. +21 −158 lib/App/Twirc/Manual.pod
  4. +67 −87 lib/POE/Component/Server/Twirc.pm
View
@@ -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';
View
@@ -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 => (
@@ -37,6 +40,7 @@ has state_file => (
isa => 'Str',
is => 'ro',
predicate => 'has_state_file',
+ documentation => 'state file name',
);
has debug => (
@@ -45,6 +49,7 @@ has debug => (
isa => 'Bool',
is => 'ro',
default => 0,
+ documentation => 'set logging level to DEBUG',
);
sub run {
@@ -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
@@ -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
View
@@ -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
@@ -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.
@@ -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
@@ -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.
@@ -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>:
@@ -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
@@ -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
@@ -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:
@@ -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>.
@@ -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
Oops, something went wrong.

0 comments on commit edb064e

Please sign in to comment.