NAME

NAME
App::Twirc::Manual - User guide and reference for Twirc

DESCRIPTION
"Twirc" is a twitter client. More precisely, it is an IRC/Twitter
gateway that makes your favorite IRC client a twitter client.

FEATURES
Follow friends timelines
Receive replies from friends and non-friends
Post status updates
Send and receive direct messages
Follow, un-follow, block, unblock, and use most other twitter commands

INSTALLATION
You can install "twirc" just as you would any other CPAN distribution:

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.

CONFIGURATION
"Twirc" uses Config::Any, so you can configure "twirc" using XML, YAML,
JSON, Apache-style configuration, Windows INI file format, or even Perl
code.

A configuration file is not necessary, but is recommended.

Here's an example configuration in YAML:

state_file: twirc.state
log_level: INFO

CONFIGURATION OPTIONS
irc_server_name
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.

irc_server_port
The port number the IRC server binds to. Defaults to 6667.

irc_server_bindaddr
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.

irc_mask
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.

irc_password
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.

irc_botname
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.

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.

irc_botircname
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.

irc_channel
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_alias
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".

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.

selection_count
How many status messages to display for selection when favoriting,
replying, or retweeting. Defaults to 3.

truncate_to
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.

log_channel
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_level
Twirc supports "log_level" values OFF, FATAL, ERROR, WARN, INFO,
DEBUG, and TRACE. The default is WARN.

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

USING
To use "twirc" you first need to start the server:

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

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

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

/connect localhost

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!

"twirc" uses the Twitter User Streams API to receive updates in
real-time.

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.

COMMAND REFERENCE
post status
Post a status update. E.g.,

post Now cooking tweets with twirc!

follow twitter_screen_name
Follow a new Twitter user. This creates a friend relationship and
adds the friend to the channel.

unfollow twitter_screen_name
Stop following a Twitter friend. This destroys the friend
relationship and removes the friend from the channel.

block twitter_screen_name
Blocks the Twitter user from receiving your Twitter feed.

unblock twitter_screen_name
Stop blocking a Twitter user.

whois twitter_user
Displays information about Twitter user. "twitter_user" can be
either a screen name or email address.

notify on|off twitter_screen_name...
Turns device notifications on or off for the list of one or more
Twitter friends. The list is space separated.

favorite friend [ count ]
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.)

rate_limit_status
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.

help
Display a simple help message listing the available command names.

TIPS AND TRICKS
Ignoring
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!).

Multiple accounts
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.).

First, the pertinent sections of the configuration files (in YAML
format).

# File: semifor.yml
irc_server_port: 6667
irc_password: secret
irc_channel: '&twitter'

# File: twirc.yml
irc_server_port: 6668
irc_password: secret
irc_channel: '&twirc'

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 semifor
/connect localhost 6668 secret twirc

Now you've got 2 channels, one for each account---in my case, &twitter
for "semifor" and &twirc for "twirc".

PLUGINS
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:

SquashWhiteSpace
Squashes whitespace in tweets to a single space. See
App::Twirc::Plugin::SquashWhiteSpace.

BangCommands
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.

SecondaryAccount
Cross-posts status updates to one or more secondary Twitter (or
Twitter API compatible, like Identi.ca) accounts. See
App::Twirc::Plugin::SecondaryAccount.

SUPPORT
"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 "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.

AUTHOR
Marc Mims <[email protected]>

I'm "semifor" on twitter and IRC.