commit b195cf41d0fa30b682bdbe97f77c666c69b391a2
parent 2ec7c07fa273a83e06dc2b963f31894f39b5361a
Author: Antoine Amarilli <a3nm@a3nm.net>
Date: Sat, 28 Jul 2012 01:01:16 +0200
write doc and prospective doc, forget about complicated stuff for now
Diffstat:
| README | | | 62 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- |
| TODO | | | 96 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| irctk.c | | | 8 | -------- |
3 files changed, 157 insertions(+), 9 deletions(-)
diff --git a/README b/README
@@ -126,7 +126,67 @@ TODO poor man's irc client with screen
TODO an IRC shell
TODO an IRC shell running irctk (irception!)
-== 4. Caveats ==
+== 4. Pipelining ==
+
+irctk tries to apply its rate limitation (-i) independently on each channel.
+This means that, to ensure the fastest possible delivery, messages to channels
+with an empty queue will be sent *before* messages to channels with a busy
+queue. no matter the order on which they were provided on standard input.
+However, within a given channel, the order relation on messages matches their
+order on standard input.
+
+If you specify multiple destination channels like "[#a,#b,#c]", however, the
+resulting message will be said on all channels simultaneously (and will
+therefore wait for the buffers of all relevant channels to be empty). If you do
+not want this synchronization, you should say the message several times,
+addressed to each individual channel.
+
+== 5. Implied destinations ==
+
+You can always specify the channel to which you speak by using a "[#channel]"
+prefix. You can specify multiple channels for the same message (but see the
+previous section for what this implies for timing). You can specify "[]" to
+escape "[" if your message starts with it. If you do not specify a channel, then
+irctk will choose one itself. Several possible ways to choose are available,
+only one of them can be provided on the command line. Here are those options,
+sorted by ascending complexity. A discussion of other useful options follows.
+
+* --default-always-first
+
+Messages with no destination will be sent to the first channel specified on the
+command line invocation of irctk, or to irctk's private channel if none were
+specified (this isn't very useful).
+
+* --default-all
+
+Messages with no destination will be sent to all channels specified on the
+command line invocation of irctk. (They will *not* be sent to other channels
+that might have been joined by irctk.)
+
+* --default-last-posted
+
+Messages with no destination will be sent to the last channel to which a message
+was sent. This is useful if you are lazy and want to specify the channel only
+when you change it.
+
+* --default-last-active (default)
+
+Messages with no destination will be sent to the last active channel, that is,
+the last channel on which something took place. This is reasonable if you want
+to react instantaneously to something which just happened. Note that because
+irctk reads stdin as greedily as possible, the last active channel is the last
+active at the moment when you *write* your message to irctk's stdin, not at the
+moment when irctk will *say* it. This is usually what you expect.
+
+This setting is perfect if you want to reply to messages by users and if your
+replies are instantaneous. If they are not, more options are available.
+
+
+
+
+Messages with
+
+== 6. Caveats ==
irctk has not been audited thoroughly for bugs or security vulnerabilities. Be
cautious if you intend to connect it to an IRC server with untrusted users.
diff --git a/TODO b/TODO
@@ -27,3 +27,99 @@ last-active and reply:
- last-goes then last-said until \n
- stack on things to manage with \n as delimiter
+
+
+
+Future features:
+
+ /*
+ {"default-last-active-delimited", 'd', 0, 0,
+ "Like -a but messages are read in atomic groups starting and ending with a blank line."
+ CHANNEL_SELECTION}, // TODO
+ {"default-last-active-delimited-queued", 'D', 0, 0,
+ "Like -d but require one message group for each outputted message."
+ CHANNEL_SELECTION}, // TODO
+ */
+
+* --default-last-active-delimited
+
+WARNING: This option is not yet implemented.
+
+Messages with no destination will be sent to the last active channel, like with
+--default-last-active. However, if you provide a blank line, non-blank lines,
+and a blank line, the non-blank lines are treated as an atomic message group
+which will be sent to the last active channel at the moment when the initial
+blank line was read by irctk.
+
+This is useful if you want to answer a message in a way which can potentially
+take time. Whenever you receive a message you want to reply to, output a blank
+line. Then, perform computations, provide the actual message, and finish with a
+blank line. In that way, the reply will go in the proper channel. The downside
+of this is that you will not be able to answer on the right channel for any
+messages which occur while you are managing a query. For this case, another
+option is available.
+
+* --default-last-active-delimited-queued
+
+WARNING: This option is not yet implemented.
+
+For every message that it produces on stdout, irctk expects to read on stdin a
+message group (blank line, non-blank lines (possibly 0), blank line) which will
+be sent to the channel of the incoming message. Lines which occur outside of a
+block are sent to the last active channel at the time when they are read.
+
+This option allows you to process each incoming message as a request, and output
+a delimited answer to this request which will be routed to the right channel.
+The only limitation is that requests cannot be processed in parallel -- if this
+is an issue, consider forgetting about the channel inference options and always
+indicate the destination channel according to your own complicated logic.
+
+* --reply
+
+This option is useful to write bots: whenever a destination channel is inferred,
+a destination nick is inferred, which is equal to the nick of the person who
+said the message. All outgoing messages are prefixed with this nick. Note: with
+--default-last-active-delimited and --default-last-active-delimited-queued, this
+option only applies to the message groups, not to content outside groups.
+
+* --default-last-active-delimited
+
+WARNING: This option is not yet implemented.
+
+Messages with no destination will be sent to the last active channel, like with
+--default-last-active. However, if you provide a blank line, non-blank lines,
+and a blank line, the non-blank lines are treated as an atomic message group
+which will be sent to the last active channel at the moment when the initial
+blank line was read by irctk.
+
+This is useful if you want to answer a message in a way which can potentially
+take time. Whenever you receive a message you want to reply to, output a blank
+line. Then, perform computations, provide the actual message, and finish with a
+blank line. In that way, the reply will go in the proper channel. The downside
+of this is that you will not be able to answer on the right channel for any
+messages which occur while you are managing a query. For this case, another
+option is available.
+
+* --default-last-active-delimited-queued
+
+WARNING: This option is not yet implemented.
+
+For every message that it produces on stdout, irctk expects to read on stdin a
+message group (blank line, non-blank lines (possibly 0), blank line) which will
+be sent to the channel of the incoming message. Lines which occur outside of a
+block are sent to the last active channel at the time when they are read.
+
+This option allows you to process each incoming message as a request, and output
+a delimited answer to this request which will be routed to the right channel.
+The only limitation is that requests cannot be processed in parallel -- if this
+is an issue, consider forgetting about the channel inference options and always
+indicate the destination channel according to your own complicated logic.
+
+* --reply
+
+This option is useful to write bots: whenever a destination channel is inferred,
+a destination nick is inferred, which is equal to the nick of the person who
+said the message. All outgoing messages are prefixed with this nick. Note: with
+--default-last-active-delimited and --default-last-active-delimited-queued, this
+option only applies to the message groups, not to content outside groups.
+
diff --git a/irctk.c b/irctk.c
@@ -84,14 +84,6 @@ static struct argp_option options[] = {
{"default-last-active", 'a', 0, 0,
"Post messages to the last active channel by default (default)",
CHANNEL_SELECTION},
- /*
- {"default-last-active-delimited", 'd', 0, 0,
- "Like -a but messages are read in atomic groups starting and ending with a blank line."
- CHANNEL_SELECTION}, // TODO
- {"default-last-active-delimited-queued", 'D', 0, 0,
- "Like -d but require one message group for each outputted message."
- CHANNEL_SELECTION}, // TODO
- */
{"default-last-posted", 'p', 0, 0,
"Post messages to the last posted channel by default",
CHANNEL_SELECTION},
