App::Twirc::Manual - User guide and reference for Twirc
Twirc is a twitter client. More precisely, it is an IRC/Twitter gateway that makes your favorite IRC client a twitter client.
Twirc
You can install twirc just as you would any other CPAN distribution:
twirc
cpan POE::Component::Server::Twirc
Or, you can download and unpack twirc, then run it from a directory of your choice without running make install. That's the way the author runs it. If you choose this option, run make to install twirc's dependencies.
make install
make
Twirc uses Config::Any, so you can configure twirc using XML, YAML, JSON, Apache-style configuration, Windows INI file format, or even Perl code.
Here's a minimal configuration in YAML:
irc_nickname: MyIRCNick twitter_username: my_email_address@example.com twitter_password: secret twitter_screen_name: MyTwitterScreenName
The irc nickname used by the owning user. This is the nickname you will use when you connect to the twirc IRC server.
The username (email address) used to authenticate with Twitter. This is the ID twirc will use to authenticate with Twitter.
The password used to authenticate with Twitter. This is the password twirc will use to authenticate with twitter.
The user's Twitter screen name. This is your screen name on Twitter. It may very well be the same as your irc_nickname, but it certainly doesn't have to be.
irc_nickname
The name of the IRC server. Defaults to twitter.irc. Every IRC server has a name. The IRC server included with twirc isn't intended to be accessed publicly. It is for your own personal use. So, the name is not significant.
twitter.irc
The port number the IRC server binds to. Defaults to 6667.
The local address to bind to. Defaults to all interfaces. You probably want to set this option to 127.0.0.1. That will prevent others from attempting to connect to your twirc IRC server.
127.0.0.1
The IRC user/host mask used to restrict connecting users. Defaults to *@127.0.0.1. If you run twirc on a different system than your IRC client, you will need to provide this configuration option with a suitable mask.
*@127.0.0.1
Password used to authenticate to the IRC server. If you don't provide this option, no password will be required. It adds a bit of security. You may want to set this option if other users have access to your system.
The name of the channel operator bot. Defaults to tweeter. Select a name that does not conflict with friends, followers, or your own IRC nick.
tweeter
When running twirc, you interact with a bot in the channel. The bot carries out commands on your behalf and provides feedback, particularly when there are errors.
Text to be used as the channel operator bot's IRC full name. Defaults to "Your Friendly Twitter Agent". This is the name that will appear in response to an IRC /whois command.
"Your Friendly Twitter Agent"
/whois
The name of the channel where your twitter friends' timelines appear. This is the channel where most of your interaction with twirc occurs. It defaults to &twitter. The IRC convention for channels names is channels local to a single server begin with &. Network channels begin with #. You can use either to name, however & is more appropriate.
&twitter
&
#
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 twitter_retry seconds. Adding "check_replies" and "check_direct_messages" each add an additional API call. Setting twitter_retry too low can cause twirc to exceed the rate limit and delay receipt of messages.
twitter_retry
Use the "rate_limit_status" command to check your available API calls.
The number of seconds to wait before retrying a failed twitter API call in the polling loop. Defaults to 60 (1 minute).
An alias to use for displaying incoming status updates from the owning user. This is necessary if the user's IRC nickname and Twitter screen name are the same. Defaults to me.
me
With the default value me, when twirc reads a status message in your timeline from your Twitter screen name, it will use me in place of your Twitter screen name in the channel.
If false, posts sent by twirc will not be redisplayed when polling the timeline. Defaults to 0 (false).
This option in off, be default, to prevent some unnecessary noise in the channel. When you post a new status message with 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 twirc next polls Twitter for new status messages.
So, why would you ever want echo_posts on? 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 twirc checks for new messages again. With echo_posts on, you will see your message again, in chronological order with the rest of the incoming messages.
echo_posts
How many favorites candidates to display for selection. Defaults to 3.
When you use the "favorite" command, a list of recent status from the friend your a favoriting are displayed for you to choose from. This option tell twirc how many of those messages to display.
When displaying a list tweets for selection, for example, in response to the "favorite" command, they will be truncated to this length to avoid cluttering the screen with long messages that wrap. Defaults to 60.
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.
check_replies adds an API call, counted against Twitter's rate limit every "twitter_retry" seconds.
check_replies
(This also has the effect of adding senders of @replies to the channel, even though they are not followed.)
If true, checks for direct messages in each timeline polling cycle.
check_direct_messages adds an API call, counted against Twitter's rate limit every "twitter_retry" seconds.
check_direct_messages
If specified, twirc will post log messages to this channel. If you set this option to &log, then you can join the &log channel and see the copious debug messages that twirc generates. This may be useful for trouble shooting or problem reporting.
&log
File used to store state information between sessions, including last message read for replies, direct messages, and timelines.
By default, twirc does not save any state information between runs. When you start 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 twirc.
If you use "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 twirc.
If you do provide a state_file name, 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.
state_file
Twirc will still only show the most recent 20 messages on restart, though. The state_file option just prevents redisplaying messages already seen.
Default 0 (off). If set, when a refresh (whether automatic or the result of the "refresh" command) finds no new messages, a notice to that effect will be written to the channel.
To use twirc you first need to start the server:
bin/twirc -c twirc.yml -b
The -b option runs twirc in the background. Drop the -b to see copious log messages to STDERR.
-b
Next, connect to the server from your IRC client. I use irssi (http://www.irssi.org) and my examples will use irssi commands:
irssi
/connect localhost 6667 secret
where secret is the password set in the config file with option "irc_password". Your IRC client may use different commands.
secret
On connection, twirc will automatically join you to the configured channel. The default &twitter will be assumed, here.
Your friends will be automatically joined to the channel. Friends who are also followers are given voice as a visual clue. In irssi they appear with plus sign (+) in front of their names.
To post a new status update, use the "post" command:
post My first tweet from twirc!
In general, you enter a command followed by its arguments, if any, as a public message in the channel. There's a handy exception to that rule for sending replies. An entry that begins with a nick name, followed by a colon is treated as a reply. E.g.:
twirc: you make twitter usable!
Is a shortcut for:
post @twirc you make twitter usable!
By default, twirc checks for updates every 5 minutes. You can have it check immediately using the "refresh" command:
refresh
Twirc will check for messages immediately, then again every 5 minutes.
Use IRC private messaging to send direct messages. In irssi:
/msg friend Watch out, I'm right behind you!
The twirc server stops when you disconnect. This isn't normal IRC behavior, but twirc isn't a normal IRC server. Its only purpose is to interface with Twitter on your behalf and server no useful purpose when you're not connected.
Post a status update. E.g.,
post Now cooking tweets with twirc!
Follow a new Twitter user. This creates a friend relationship and adds the friend to the channel.
Stop following a Twitter friend. This destroys the friend relationship and removes the friend from the channel.
Blocks the Twitter user from receiving your Twitter feed.
Stop blocking a Twitter user.
Displays information about Twitter user. twitter_user can be either a screen name or email address.
twitter_user
Turns device notifications on or off for the list of one or more Twitter friends. The list is space separated.
Mark a friend's tweet as a favorite. Optionally, specify the number of tweets to display for selection with count. (count defaults to 3. The default can be changed with the "favorites_count" option.)
count
Turns reply checking on or off. See "check_replies" in configuration.
Turns direct message checking on or off. See "check_direct_messages" in configuration.
Displays information about the remaining number of API requests available in the current hour. The rate_limit_status command does not count against the limit, itself.
rate_limit_status
Display a simple help message listing the available command names.
Turns verbose_refresh on or off. See "verbose_refresh" in configuration.
verbose_refresh
If you're following a particularly noisy friend, you can of course "unfollow" her. Alternatively, you can use your IRC client's features to ignore the user. In irssi:
/ignore LoudMouth ALL /ignore -except -pattern @YourName LoudMouth ALL
Now, you won't hear from LoudMouth unless she @replies you, and she won't know you're ignoring her (unless she reads this tip!).
Although twirc doesn't currently support multiple accounts, there's nothing stopping you from running multiple instances of twirc, one for each account.
Here's how I do it for accounts semifor (my personal account) and twirc (twirc's feed for update notices, etc.).
semifor
First, the pertinent sections of the configuration files (in YAML format).
# File: semifor.yml irc_server_port: 6667 irc_channel: '&twitter' irc_nickname: semifor twitter_screen_name: semifor state_file: semifor.state # ... # File: twirc.yml irc_server_port: 6668 irc_channel: '&twirc' irc_nickname: twirc twitter_screen_name: twirc state_file: twirc.state # ...
Next, start an instance for each account:
bin/twirc -c semifor.yml -b bin/twirc -c twirc.yml -b
In your IRC client, connect to both instances (irssi here):
/connect localhost 6667 secret_password semifor /connect localhost 6668 secret_password twirc
Now you've got 2 channels, one for each account---in my case, &twitter for semifor and &twirc for twirc.
&twirc
Plugins are modules that are optionally included by specifying them in user configuration file in the plugins section. Some of the plugins included in the distribution are:
plugins
Squashes whitespace in tweets to a single space. See App::Twirc::Plugin::SquashWhiteSpace.
Commands are prefixed with a bang (i.e., exclamation point "!"). Text entered without a bang prefix is posted as a status update. See App::Twirc::Plugin::BangCommands.
Cross-posts status updates to one or more secondary Twitter (or Twitter API compatible, like Identi.ca) accounts. See App::Twirc::Plugin::SecondaryAccount.
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 #twirc channel at irc.perl.org.
irc.perl.org
The code repository with the development branch is located at http://github.com/semifor/twirc. New features, and bug fixes appear there before they hit CPAN, so check the commit log there to see if a problem you've found has been addressed. And feel free to use the development branch.
Marc Mims <marc@questright.com>
I'm semifor on twitter and IRC.
To install POE::Component::Server::Twirc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::Server::Twirc
CPAN shell
perl -MCPAN -e shell install POE::Component::Server::Twirc
For more information on module installation, please visit the detailed CPAN module installation guide.