picoirc(n)						  Simple embeddable IRC interface						picoirc(n)

__________________________________________________________________________________________________________________________________________________

NAME

       picoirc - Small and simple embeddable IRC client.

SYNOPSIS

       package require Tcl

       package require picoirc	?0.5?

       ::picoirc::connect callback nick url

       ::picoirc::post context channel message

       ::picoirc::splituri uri

       ::picoirc::send context line

_________________________________________________________________

DESCRIPTION

       This  package provides a general purpose minimal IRC client suitable for embedding in other applications. All communication with the parent
       application is done via an application provided callback procedure.  Each connection has its own state so you can hook up multiple  servers
       in a single application instance.

       To  initiate  an  IRC  connection  you must call picoirc::connect with a callback procedure, a nick-name to use on IRC and the IRC URL that
       describes the connection. This will return a variable name that is the irc connection context. See CALLBACK for details.

       This package is a fairly simple IRC client. If you need something with more capability investigate the irc package.

COMMANDS

       ::picoirc::connect callback nick url
	      Create a new irc connection to the server specified by url and login using the nick as the username. The callback must be as  speci-
	      fied in CALLBACK. Returns a package-specific variable that is used when calling other commands in this package.

       ::picoirc::post context channel message
	      This should be called to process user input and send it to the server. A number of commands are recognised when prefixed with a for-
	      ward-slash (/). Such commands are converted to IRC command sequences and then sent.

       ::picoirc::splituri uri
	      Splits an IRC scheme uniform resource indicator into its component parts. Returns a list of server, port and  channel.  The  default
	      port is 6667 and there is no default channel.

       ::picoirc::send context line
	      This  command  is where all raw output to the server is handled. The default action is to write the line to the irc socket. However,
	      before this happens the callback is called with "debug write". This permits the application author to inspect the raw IRC  data  and
	      if  desired  to  return a break error code to halt further processing. In this way the application can override the default send via
	      the callback procedure.

CALLBACK

       The callback must look like:

       proc Callback {context state args} {
       }

       where context is the irc context variable name (in case you need to pass it back to a picoirc procedure). state	is  one  of  a	number	of
       states as described below.

       init   called just before the socket is created

       connect
	      called once we have connected, before we join any channels

       close  called when the socket gets closed, before the context is deleted. If an error occurs before we get connected the only argument will
	      be the socket error message.

       userlist channel nicklist
	      called to notify the application of an updated userlist. This is generated when the output of the NAMES irc  command  is	seen.  The
	      package  collects  the  entire output which can span a number of output lines from the server and calls this callback when they have
	      all been received.

       chat target nick message type
	      called when a message arrives. target is the identity that the message was targetted for. This can be the logged in nick or a  chan-
	      nel  name.  nick	is the name of the sender of the message.  message is the message text. type is set to "ACTION" if the message was
	      sent as a CTCP ACTION

       system channel message
	      called when a system message is received

       topic channel topic
	      called when the channel topic string is seen. topic is the text of the channel topic.

       traffic action channel nick ?newnick?
	      called when users join, leave or change names.  action is either entered, left or nickchange and nick is the user doing the  action.
	      newnick is the new name if action is nickchange.

	      NOTE:  channel  is often empty for these messages as nick activities are global for the irc server. You will have to manage the nick
	      for all connected channels yourself.

       version
	      This is called to request a version string to use to override the internal version. If  implemented,  you  should  return  as  colon
	      delimited string as

	      Appname:Appversion:LibraryVersion

	      For example, the default is

	      PicoIRC:[package provide picoirc]:Tcl [info patchlevel]

       debug type raw
	      called  when data is either being read or written to the network socket. type is set to read when reading data and write if the data
	      is to be written. raw is the unprocessed IRC protocol data.

	      In both cases the application can return a break error code to interrupt further processing of the raw data. If this is a read oper-
	      ation  then  the package will not handle this line. If the operation is write then the package will not send the data. This callback
	      is intended for debugging protocol issues but could be used to redirect all input and output if desired.

SEE ALSO

       rfc 1459

KEYWORDS

       chat, irc

irc									0.5								picoirc(n)