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