April 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.

Kamaelia.Protocol.IRC.IRCClient

Kamaelia IRC Interface

IRC_Client provides an IRC interface for Kamaelia components.

SimpleIRCClientPrefab is a handy prefab that links IRC_Client and TCPClient to each other and IRC_Client's "talk" and "heard" boxes to the prefab's "inbox" and "outbox" boxes, respectively. SimpleIRCClientPrefab does not terminate.

The functions informat, outformat, channelInformat, and channelOutformat can be used to format incoming and outgoing messages.

Example Usage

To link IRC_Client to the web with console input and output:

client = Graphline(irc = IRC_Client(),
              tcp = TCPClient(host, port),
              linkages = {("self", "inbox") : ("irc" , "talk"),
                          ("irc", "outbox") : ("tcp" , "inbox"),
                          ("tcp", "outbox") : ("irc", "inbox"),
                          ("irc", "heard") : ("self", "outbox"),
                          })
Pipeline(ConsoleReader(),
         PureTransformer(channelInformat("#kamtest")),
         client,
         PureTransformer(channelOutformat("#kamtest")),
         ConsoleEchoer(),
).run()

Note: The user needs to enter:

/nick aNickName
/user uname server host realname

into the console before doing anything else in the above example. Be quick before the connection times out.

Then try IRC commands preceded by a slash. Messages to the channel need not be preceded by anything:

>>> /join #kamtest
>>> /msg nickserv identify secretpassword
>>> /topic #kamtest Testing IRC client
>>> Hello everyone.
>>> /part #kamtest
>>> /quit

This example sends all plaintext to #kamtest by default. To send to another channel by default, change the arguments of channelInformat and channelOutformat to the name of a different channel. (E.g. "#python")

For a more comprehensive example, see Logger.py in Tools.

How does it work?

Sending messages over IRC

IRC_Client accepts commands arriving at its "talk" inbox. A command is a list/tuple and is in the form ('cmd', [arg1] [,arg2] [,arg3...]). IRC_Client retransmits these as full-fledged IRC commands to its "outbox". Arguments following the command are per RFC 1459 and RFC 2812.

For example,

  • ('NICK', 'Zorknpals')
  • ('USER', 'jlei', 'nohost', 'noserver', 'Kamaelia IRC Client')
  • ('JOIN', '#kamaelia')
  • ('PRIVMSG', '#kamtest', 'hey, how's it going?')
  • ('TOPIC', '#cheese', "Mozzerella vs.┬áParmesan")
  • ('QUIT')
  • ('QUIT', "Konversation terminated!")
  • ('BERSERKER', "Lvl. 10")

Note that "BERSERKER" is not a recognized IRC command. IRC_Client will not complain about this, as it treats commands uniformly, but you might get an error 421, "ERR_UNKNOWNCOMMAND" back from the server.

Sending CTCP commands

IRC_Client also handles a few CTCP commands:

ACTION: ("ME", channel-or-user, the-action-that-you-do).
MSG: If you use the outformat function defined here, 'MSG' commands are treated as 'PRIVMSGs'.

No other CTCP commands are implemented.

Receiving messages

IRC_Client's "inbox" takes messages from an IRC server and retransmits them to its "heard" outbox in tuple format. Currently each tuple has fields (command, sender, receiver, rest). This method has worked well so far.

Example output:

('001', 'heinlein.freenode.net', 'jinnaslogbot', ' Welcome to the freenode IRC Network jinnaslogbot')

('NOTICE', '', 'jinnaslogbot', '***Checking ident')

('PRIVMSG', 'jlei', '#kamtest', 'stuff')

('PART', 'kambot', '#kamtest', 'see you later)

('ACTION', 'jinnaslogbot', '#kamtest', 'does the macarena')

To stop IRC_Client, send a shutdownMicroprocess or a producerFinished to its "control" box. The higher-level client must send a login itself and respond to pings. IRC_Client will not do this automatically.

Known Issues

The prefab does not terminate. (?) Sometimes messages from the server are split up. IRC_Client does not recognize these messages and flags them as errors.


Feedback

Got a problem with the documentation? Something unclear that could be clearer? Want to help improve it? Constructive criticism is very welcome - especially if you can suggest a better rewording!

Please leave you feedback here in reply to the documentation thread in the Kamaelia blog.

-- Automatic documentation generator, 05 Jun 2009 at 03:01:38 UTC/GMT