commit 08361103b0250cd2877d4edb59acf90bd654b138
parent 0e5c98170ec9a4108ff81000bcf53400df8b2155
Author: Antoine Amarilli <a3nm@a3nm.net>
Date: Fri, 7 Sep 2012 17:43:22 +0200
proof-read, improve
Diffstat:
| README | | | 113 | ++++++++++++++++++++++++++++++++++++++++++++++--------------------------------- |
1 file changed, 66 insertions(+), 47 deletions(-)
diff --git a/README b/README
@@ -1,8 +1,6 @@
irctk -- an IRC toolkit
Copyright (C) 2010-2012 by Antoine Amarilli
-WARNING: this code is NOT stable yet.
-
== 0. License ==
This program is free software: you can redistribute it and/or modify it under
@@ -18,7 +16,7 @@ this program (see file "COPYING"). If not, see <http://www.gnu.org/licenses/>.
== 1. Features ==
-irctk is a general-purpose IRC wrapper. It connects to an IRC server specified
+irctk is a general-purpose IRC toolkit. It connects to an IRC server specified
on the command line, joins channels specified on the command line, posts what it
receives from stdin and outputs to stdout what it hears. This makes it possible
to write simple IRC bots and scripts very quickly, either in the shell or in
@@ -45,15 +43,15 @@ program. Install libircclient-dev (on Ubuntu and Debian systems), or get it from
== 4. How to use ==
+=== 4.1. Connecting to a server ===
+
As a simple interactive use of irctk, here is how you connect to the IRC server
at example.com and join channel #test:
-=== 4.1. Connecting to a server ===
-
$ irctk example.com '#test'
Messages on the channel will get output on your terminal and you can type
-messages that you want so say on the channel. Press ^D to close stdin and
+messages that you want so say to the channel. Press ^D to close stdin and
terminate irctk. Note that the use of quotes is to prevent your shell from
interpreting '#' (irctk won't see them).
@@ -66,32 +64,33 @@ port, specifying a custom nickname, username and real name.
=== 4.2. Using irctk's stdin ===
irctk is meant to be used non-interactively. For instance, you can say the
-contents of a file to a server by giving it as standard input:
+contents of a file on a channel by giving it as standard input:
$ irctk flooder@example.com '#flood' <file
-As a funnier example, here is how to follow the RSS feed of FML and post the
-stories to a channel as they appear in the feed:
+Of course, it is more interesting to pipe to irctk something which will produce
+more and more lines as events occur. For instance, here is how to follow your
+server logs on IRC:
- $ rsstail -u 'http://feeds2.feedburner.com/fmylife' -NdzH -n 1 -i 300 |
- grep --line-buffered '^ Today' |
- ./irctk fmlbot@example.com '#fml'
+ $ ssh server tail -f logfile.log | irctk logger@example.com '#dashboard'
-Note the use of --line-buffered to make sure that the messages do not get
-buffered. If you receive mail to a mbox file, here is how you could use irctk to
+If you receive mail to a mbox file, here is how you could use irctk to
get a private message to notify you about the subjects of incoming emails.
$ tail -f ~/mbox | grep --line-buffered '^Subject:' |
irctk alert@example.com mynick
-As a last example, here is how to follow your server logs on IRC:
+Note the use of --line-buffered to make sure that the messages do not get
+buffered. Here is how to follow the RSS feed of FML and post the stories to a
+channel as they appear in the feed:
- $ ssh server tail -f logfile.log | irctk logger@example.com '#dashboard'
+ $ rsstail -u 'http://feeds2.feedburner.com/fmylife' -NdzH -n 1 -i 300 |
+ grep --line-buffered '^ Today' |
+ ./irctk fmlbot@example.com '#fml'
=== 4.3. Using irctk's stdout ===
-As another possible non-interactive use of irctk, you can log what is happening
-on a channel by setting stdout to be a file:
+You can log what is happening on a channel by setting stdout to be a file:
$ irctk logger@example.com '#chan' >file
@@ -104,9 +103,9 @@ with timestamps:
echo "`date +%s` $MSG" >> "$CHAN.log"
done
-Caution, if you want to run irctk in the background, you need to prevent it to
-read from standard input (to avoid it being suspended) without closing stdin
-(otherwise irctk will terminate). Here is how:
+Caution, if you want to run irctk in the background to do something like this,
+you need to prevent it from reading stdin (to avoid it being suspended) without
+closing stdin (otherwise irctk will terminate). Here is how:
$ tail -f /dev/null | irctk logger@example.com '#chan' >file &
@@ -114,7 +113,7 @@ Another example: play a sound whenever your nick is mentionned (but not when you
speak):
$ irctk example.com '#chan' |
- grep --line-buffered '[^<]alex' | while read l; do
+ grep --line-buffered '[^<]yournick' | while read l; do
aplay alert.wav;
done
@@ -123,15 +122,15 @@ tasks to do by addressing a bot on IRC:
$ irctk -f todobot@example.com '#chan' >>~/todo
-To append lines to ~/todo, you can either address todobot on #chan through lines
-such as "todobot: buy some milk", or you can send a private message to todobot
-(using irssi, "/msg todobot write a poem to alice"). Note that the lines logged
-in ~/todo will look like "[#chan] <mynick> todobot: buy some milk"; if you want
-to get rid of the cruft, you can use:
+To append lines to ~/todo, you can either address todobot on #chan through
+messages like "todobot: buy some milk", or you can send a private message to
+todobot (using irssi, "/msg todobot write a poem to alice"). Note that the lines
+logged in ~/todo will look like "[#chan] <mynick> todobot: buy some milk"; if
+you want to get rid of the cruft, you can use:
$ irctk -F todobot@example.com '#chan' >>~/todo
-which will only log "buy some milk".
+which will only log "buy some milk" (and implies -f).
To combine the use of stdin and stdout, this invocation pipes two irctk calls
together to relay messages from source.com to destination.com (but not the
@@ -171,7 +170,7 @@ buffering*. You can then lift it to IRC very simply:
=== 4.5. Input and output format ===
-The output format is of the following form (unless you use -F):
+The output format of irctk is of the following form (unless you use -F):
[#chan] <nick> message
@@ -184,10 +183,10 @@ Alternatively, you can get them in a barebones form with -c:
[#bar] <foo> /join #bar
-Your own messages will not be included unless you request it with -o. If you
-want to see nicknames like <nick!~username@localhost>, use -w. Remember the -f
-and -F options presented above to only keep lines addressed to you and to remove
-everything but the message (-F implies -f).
+Your own messages will not be included unless you specify --own. If you want to
+see nicknames like <nick!~username@localhost>, use --with-host. You can also use
+the -f and -F options presented above to only keep lines addressed to you and to
+remove everything but the message (-F implies -f).
The input format is of the following form:
@@ -196,20 +195,22 @@ The input format is of the following form:
You can specify multiple channel names separated by commas (but see the section
"Pipelining" below).
-Because specifying the chan each time can be tedious, irctk has options to guess
-it. If you do not specify a destination and just give a message, irctk will say
-it to the last active channel by default (i.e., the last channel where something
-was heard), which is often a reasonable choice if you are replying to stuff.
+Because specifying the chan each time can be tedious, irctk can try to guess it.
+If you do not specify a destination and just give a message, irctk will say it
+to the last active channel by default (i.e., the last channel where something
+was heard), which is often a reasonable choice if you are replying to someone.
There are other possible options: see the section "Implied destinations" below.
irctk will always try to join a channel before saying something to this channel.
This means that it can join entirely new channels in this fashion. To disable
this behavior and prevent irctk from joining any channels except the ones given
-at startup, use -J (can be useful if irctk's stdin is attacker-controlled).
+at startup, use --no-join (can be useful if irctk's stdin is
+attacker-controlled).
irctk will interpret some commands starting with '/' in a fashion similar to
irssi. To inhibit this (can be useful if irctk's stdin is attacker-controlled),
-use -E. To escape, use '/say' or '/ '. The supported commands are:
+use --no-command-to-event. To escape, use '/say' or '/ '. The supported commands
+are:
/nick NICKNAME (changes nick)
/mode MODE (set channel mode)
@@ -236,7 +237,7 @@ where it was addressed. This is very convenient to write bots.
This bot queries on wikipedia whatever is said to him, using the DNS-based
wikipedia query system as an ugly way to get the beginning of pages.
- $ cat fifo | irctk -Ffr wikibot@example.com '#chat' |
+ $ cat fifo | irctk -Fr wikibot@example.com '#chat' |
while read line; do
Q=$(echo "$line" | tr ' ' '_' | tr -dc 'a-zA-Z_()');
dig +short txt $Q.wp.dg.cx; echo;
@@ -247,7 +248,7 @@ saving their game, so run as a suitably unpriviledged user.) The "while true"
loop is to restart the game whenever it exits. The socat invocation is used to
disable buffering.
- $ cat fifo | irctk -Ff DM@example.com '#adventure' |
+ $ cat fifo | irctk -F DM@example.com '#adventure' |
while true; do
socat EXEC:adventure,pty,ctty,echo=0 STDIO;
done | tee fifo
@@ -255,14 +256,14 @@ disable buffering.
Two-way gateway: gateway posts on #chan1 on server1.com whatever
is said to him on #chan2 on server2.com, and vice-versa:
- $ cat fifo | irctk -fF0 gateway@server1.com '#chan1' |
- irctk -fF0 gateway@server2.com '#chan2' | tee fifo
+ $ cat fifo | irctk -F0 gateway@server1.com '#chan1' |
+ irctk -F0 gateway@server2.com '#chan2' | tee fifo
Run shell commands from your IRC client. BEWARE, this means that whoever is
named "admin" on the IRC server can run arbitrary commands on your machine, so
you really shouldn't do this.
- $ cat fifo | ./irctk localhost '#tty' |
+ $ cat fifo | irctk localhost '#tty' |
grep --line-buffered '^\[#tty\] <admin>' |
sed -u 's/^[^>]*> *//' | bash >fifo 2>&1
@@ -270,7 +271,7 @@ Whatever admin says on #tty will get run in a bash shell and the result will be
returned to the channel. Note that you can of course run irctk in this shell
(irception!).
-== 5. Pipelining ==
+=== 4.7. 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
@@ -285,7 +286,7 @@ 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.
-== 6. Implied destinations ==
+=== 4.8. 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
@@ -305,7 +306,7 @@ specified (this isn't very useful).
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.)
+that might have been joined by irctk later.)
* --default-last-posted
@@ -329,6 +330,24 @@ requests may arrive during that time, irctk will not be able to route the
answers on its own: consider writing your own logic to route messages according
to your needs (and always specify the destination explicitly).
+=== 4.9. Tracking ===
+
+Because of the delay between messages which irctk observes to avoid getting
+kicked by a pissed server, messages can be sent to the server a long time after
+irctk received them on stdin. This means that if you addressed someone doing
+something like "nick: message" or "[nick] message" or using -r, then that person
+might have changed nick in the meantime and the message may not get routed
+correctly.
+
+As a countermeasure, you can specify --track-renames so that messages addressed
+to a user in one of the above fashions get sent to the user's current nick.
+(They will get sent to his last known nick if he parts or quits.) There is also
+a --unique-names options with which irctk will maintain unique names for users
+(based on the first seen nick for a user), expose them on stdout, and expect
+them on stdin. This is useful if you want to write a bot which stores e.g. a
+score for each user and if you want users to keep their score even if they
+change nick. These tracking modes are not enabled by default.
+
== 7. Test suite ==
You can run the test suite with ./tests_sequential.sh. This requires a working
