1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin picoirc n 0.5]
3[moddesc   {Simple embeddable IRC interface}]
4[titledesc {Small and simple embeddable IRC client.}]
5[category  Networking]
6[require Tcl]
7[require picoirc [opt 0.5]]
8[description]
9
10This package provides a general purpose minimal IRC client suitable for 
11embedding in other applications. All communication with the parent
12application is done via an application provided callback procedure.
13Each connection has its own state so you can hook up multiple servers
14in a single application instance.
15
16[para]
17
18To initiate an IRC connection you must call [cmd picoirc::connect]
19with a callback procedure, a nick-name to use on IRC and the IRC URL
20that describes the connection. This will return a variable name that
21is the irc connection context. See [sectref CALLBACK] for details.
22
23[para]
24
25This package is a fairly simple IRC client. If you need something with
26more capability investigate the [package irc] package.
27
28[para]
29
30[section COMMANDS]
31
32[list_begin definitions]
33
34[call [cmd ::picoirc::connect] [arg callback] [arg nick] [arg url]]
35
36Create a new irc connection to the server specified by [arg url] and
37login using the [arg nick] as the username. The [arg callback] must be
38as specified in [sectref CALLBACK]. Returns a package-specific variable
39that is used when calling other commands in this package.
40
41[call [cmd ::picoirc::post] [arg context] [arg channel] [arg message]]
42
43This should be called to process user input and send it to the
44server. A number of commands are recognised when prefixed with a
45forward-slash (/). Such commands are converted to IRC command
46sequences and then sent.
47
48[call [cmd ::picoirc::splituri] [arg uri]]
49
50Splits an IRC scheme uniform resource indicator into its component
51parts. Returns a list of server, port and channel. The default port is
526667 and there is no default channel.
53
54[call [cmd ::picoirc::send] [arg context] [arg line]]
55
56This command is where all raw output to the server is handled. The
57default action is to write the [arg line] to the irc socket. However,
58before this happens the callback is called with "debug write". This
59permits the application author to inspect the raw IRC data and if
60desired to return a break error code to halt further processing. In
61this way the application can override the default send via the
62callback procedure.
63
64[list_end]
65
66[section CALLBACK]
67
68The callback must look like:
69
70[example {
71proc Callback {context state args} {
72}
73}]
74
75where context is the irc context variable name (in case you need to pass 
76it back to a picoirc procedure). state is one of a number of states as
77described below.
78
79[list_begin options]
80
81[opt_def init]
82
83called just before the socket is created
84
85[opt_def connect]
86
87called once we have connected, before we join any channels
88
89[opt_def close]
90
91called when the socket gets closed, before the context is deleted. If
92an error occurs before we get connected the only argument will be the
93socket error message.
94
95[opt_def userlist "[arg channel] [arg nicklist]"]
96
97called to notify the application of an updated userlist. This is
98generated when the output of the NAMES irc command is seen. The
99package collects the entire output which can span a number of output
100lines from the server and calls this callback when they have all been
101received.
102
103[opt_def chat "[arg target] [arg nick] [arg message] [arg type]"]
104
105called when a message arrives. [arg target] is the identity that the
106message was targetted for. This can be the logged in nick or a channel
107name. [arg nick] is the name of the sender of the message. 
108[arg message] is the message text. [arg type] is set to "ACTION" if the
109message was sent as a CTCP ACTION
110
111[opt_def system "[arg channel] [arg message]"]
112
113called when a system message is received
114
115[opt_def topic "[arg channel] [arg topic]"]
116
117called when the channel topic string is seen. [arg topic] is the text
118of the channel topic.
119
120[opt_def traffic "[arg action] [arg channel] [arg nick] [opt [arg newnick]]"]
121
122called when users join, leave or change names.
123[arg action] is either entered, left or nickchange and [arg nick]
124is the user doing the action. [arg newnick] is
125the new name if [arg action] is nickchange.
126[para]
127[emph NOTE]: [arg channel] is often empty for these messages as nick
128activities are global for the irc server. You will have
129to manage the nick for all connected channels yourself.
130
131[opt_def version]
132
133This is called to request a version string to use to
134override the internal version. If implemented, you should
135return as colon delimited string as
136[para]
137  Appname:Appversion:LibraryVersion
138[para]
139For example, the default is
140[para]
141  PicoIRC:[lb]package provide picoirc[rb]:Tcl [lb]info patchlevel[rb]
142
143[opt_def debug "[arg type] [arg raw]"]
144
145called when data is either being read or written to the network
146socket. [arg type] is set to [const read] when reading data and
147[const write] if the data is to be written. [arg raw] is the
148unprocessed IRC protocol data.
149[para]
150In both cases the application can return a break error code to
151interrupt further processing of the raw data. If this is a 
152[const read] operation then the package will not handle this line. If
153the operation is [const write] then the package will not send the
154data. This callback is intended for debugging protocol issues but
155could be used to redirect all input and output if desired.
156
157[list_end]
158
159[see_also {rfc 1459}]
160[keywords irc chat]
161[manpage_end]
162