<html><head>
<title>picoirc - Simple embeddable IRC interface</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.toc,UL.toc UL, UL.toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.section, LI.subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.requirements LI, UL.syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
--></style>
</head>
<! -- Generated from file 'picoirc.man' by tcllib/doctools with format 'html'
-->
<! -- CVS: $Id$ picoirc.n
-->
<body><div class="doctools">
<hr> [
<a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<h1 class="title">picoirc(n) 0.5 tcllib "Simple embeddable IRC interface"</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>picoirc - Small and simple embeddable IRC client.</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">COMMANDS</a></li>
<li class="section"><a href="#section3">CALLBACK</a></li>
<li class="section"><a href="#see-also">See Also</a></li>
<li class="section"><a href="#keywords">Keywords</a></li>
<li class="section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="requirements">
<li>package require <b class="pkgname">Tcl</b></li>
<li>package require <b class="pkgname">picoirc <span class="opt">?0.5?</span></b></li>
</ul>
<ul class="syntax">
<li><a href="#1"><b class="cmd">::picoirc::connect</b> <i class="arg">callback</i> <i class="arg">nick</i> <i class="arg">url</i></a></li>
<li><a href="#2"><b class="cmd">::picoirc::post</b> <i class="arg">context</i> <i class="arg">channel</i> <i class="arg">message</i></a></li>
<li><a href="#3"><b class="cmd">::picoirc::splituri</b> <i class="arg">uri</i></a></li>
<li><a href="#4"><b class="cmd">::picoirc::send</b> <i class="arg">context</i> <i class="arg">line</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>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.</p>
<p>To initiate an IRC connection you must call <b class="cmd">picoirc::connect</b>
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 <span class="sectref"><a href="#section3">CALLBACK</a></span> for details.</p>
<p>This package is a fairly simple IRC client. If you need something with
more capability investigate the <b class="package"><a href="irc.html">irc</a></b> package.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="definitions">
<dt><a name="1"><b class="cmd">::picoirc::connect</b> <i class="arg">callback</i> <i class="arg">nick</i> <i class="arg">url</i></a></dt>
<dd><p>Create a new irc connection to the server specified by <i class="arg">url</i> and
login using the <i class="arg">nick</i> as the username. The <i class="arg">callback</i> must be
as specified in <span class="sectref"><a href="#section3">CALLBACK</a></span>. Returns a package-specific variable
that is used when calling other commands in this package.</p></dd>
<dt><a name="2"><b class="cmd">::picoirc::post</b> <i class="arg">context</i> <i class="arg">channel</i> <i class="arg">message</i></a></dt>
<dd><p>This should be called to process user input and send it to the
server. A number of commands are recognised when prefixed with a
forward-slash (/). Such commands are converted to IRC command
sequences and then sent.</p></dd>
<dt><a name="3"><b class="cmd">::picoirc::splituri</b> <i class="arg">uri</i></a></dt>
<dd><p>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.</p></dd>
<dt><a name="4"><b class="cmd">::picoirc::send</b> <i class="arg">context</i> <i class="arg">line</i></a></dt>
<dd><p>This command is where all raw output to the server is handled. The
default action is to write the <i class="arg">line</i> 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.</p></dd>
</dl>
</div>
<div id="section3" class="section"><h2><a name="section3">CALLBACK</a></h2>
<p>The callback must look like:</p>
<pre class="example">
proc Callback {context state args} {
}
</pre>
<p>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.</p>
<dl class="options">
<dt><b class="option">init</b></dt>
<dd><p>called just before the socket is created</p></dd>
<dt><b class="option">connect</b></dt>
<dd><p>called once we have connected, before we join any channels</p></dd>
<dt><b class="option">close</b></dt>
<dd><p>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.</p></dd>
<dt><b class="option">userlist</b> <i class="arg">channel</i> <i class="arg">nicklist</i></dt>
<dd><p>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.</p></dd>
<dt><b class="option">chat</b> <i class="arg">target</i> <i class="arg">nick</i> <i class="arg">message</i> <i class="arg">type</i></dt>
<dd><p>called when a message arrives. <i class="arg">target</i> is the identity that the
message was targetted for. This can be the logged in nick or a channel
name. <i class="arg">nick</i> is the name of the sender of the message.
<i class="arg">message</i> is the message text. <i class="arg">type</i> is set to "ACTION" if the
message was sent as a CTCP ACTION</p></dd>
<dt><b class="option">system</b> <i class="arg">channel</i> <i class="arg">message</i></dt>
<dd><p>called when a system message is received</p></dd>
<dt><b class="option">topic</b> <i class="arg">channel</i> <i class="arg">topic</i></dt>
<dd><p>called when the channel topic string is seen. <i class="arg">topic</i> is the text
of the channel topic.</p></dd>
<dt><b class="option">traffic</b> <i class="arg">action</i> <i class="arg">channel</i> <i class="arg">nick</i> <span class="opt">?<i class="arg">newnick</i>?</span></dt>
<dd><p>called when users join, leave or change names.
<i class="arg">action</i> is either entered, left or nickchange and <i class="arg">nick</i>
is the user doing the action. <i class="arg">newnick</i> is
the new name if <i class="arg">action</i> is nickchange.</p>
<p><em>NOTE</em>: <i class="arg">channel</i> 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.</p></dd>
<dt><b class="option">version</b></dt>
<dd><p>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</p>
<p>Appname:Appversion:LibraryVersion</p>
<p>For example, the default is</p>
<p>PicoIRC:[package provide picoirc]:Tcl [info patchlevel]</p></dd>
<dt><b class="option">debug</b> <i class="arg">type</i> <i class="arg">raw</i></dt>
<dd><p>called when data is either being read or written to the network
socket. <i class="arg">type</i> is set to <b class="const">read</b> when reading data and
<b class="const">write</b> if the data is to be written. <i class="arg">raw</i> is the
unprocessed IRC protocol data.</p>
<p>In both cases the application can return a break error code to
interrupt further processing of the raw data. If this is a
<b class="const">read</b> operation then the package will not handle this line. If
the operation is <b class="const">write</b> 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.</p></dd>
</dl>
</div>
<div id="see-also" class="section"><h2><a name="see-also">See Also</a></h2>
<p>rfc 1459</p>
</div>
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#key674">chat</a>, <a href="../../../../index.html#key727">irc</a></p>
</div>
<div id="category" class="section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div></body></html>
