IRC bot in D
To use this package, put the following dependency into your project's dependencies section:
kameloso sits and listens in the channels you specify and reacts to events, like bots generally do.
A variety of features comes bundled in the form of compile-time plugins, some of which are proofs of concepts and examples. It's designed to be easy to write your own. API documentation is available online. Any and all ideas for inclusion welcome.
It works well with the majority of server networks. IRC is standardised but servers still come in many flavours, where some outright conflict with others. If something doesn't immediately work it's most often an easy case of specialcasing for that kind of event on that particular IRC network or server daemon.
Please report bugs. Unreported bugs can only be fixed by accident.
Current functionality includes:
- bedazzling coloured terminal output like it's the 90s
- automatic mode sets (eg. auto
- looking up titles of pasted web URLs
sed-replacement of the last message sent (
notesto offline users that get played back when they come online
seenplugin; reporting when a user was last seen, written as a rough example plugin
- Reddit post lookup
- Twitch support; Twitch bot is now easy (see notes on connecting below)
- piping text from the terminal to the server (Posix only)
- mIRC colour coding and text effects (bold, underlined, ...), translated into Bash terminal formatting
- SASL authentication (
- configuration stored on file; generate one and edit it to get an idea of the features available to toggle (see notes on generating below)
If nothing else it makes for a good read-only lurkbot.
- the dmd and ldc compilers may segfault if building in anything other than
debugmode (bug #18026, see more on build types below).
- the stable release of the gdc compiler doesn't yet support
static foreachand thus cannot be used to build this bot. On the other hand, the development release based on D version 2.081 segfaults upon compiling (bug #307)
- so far outgoing IRC messages are uncoloured. There's nothing preventing it, we just need to implement it.
- IRC server daemons that have not been tested against may exhibit weird behaviour if parsing goes awry. Need concrete examples to fix; please report errors and abnormalities.
Use on networks without services (
AuthServ/...) may be difficult, since the bot identifies people by their account names. You will probably want to register yourself with such, where available.
Testing is primarily done on freenode, so support and coverage is best there.
Table of contents
- Getting started
- How to use
- Other files
- Example use
- Use as a library
- Debugging and generating unit tests
- Built with
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes, as well as general use.
You need a D compiler and the official dub package manager. There are three compilers available; see here for an overview. You need one based on version 2.076 or later (released September 2017). You will also need a good chunk of RAM, as compiling requires over 4Gb.
kameloso can be built using the reference compiler dmd and the LLVM-based ldc, in
debug mode (see below). The stable release of the GCC-based gdc is currently too old to be used, and the development release crashes when trying.
It's possible to build it manually without dub, but it is non-trivial if you want the web-related plugins to work. Your best bet is to first build it with dub in verbose mode, then copy the actual command it runs and modify it to suit your needs.
$ git clone https://github.com/zorael/kameloso.git $ cd kameloso
Do not use
dub fetch until we have released v1.0.0; it will download an ancient version.
$ dub build
This will compile it in the default
debug build type, which adds some extra code and debugging symbols.
You can automatically skip these and add some optimisations by building it in
dub build -b release. Mind that build times will increase. Refer to the output of
dub build --helpfor more build types.
The above might currently not work, as the compiler may crash on some build configurations under anything other than
debug mode. Bug reported.
Unit tests are built into the language, but you need to compile the project in
unittest mode to include them.
$ dub build -b unittest
The tests are run at the start of the program, not during compilation. You can use the shorthand
dub test to compile with tests and run them in one go. Test builds will only run the unit tests and immediately exit.
The available build configurations are:
vanilla, builds without any specific extras
colours, compiles in terminal colours
web, compiles in plugins with web lookup (
colours+web, includes both of the above
posix, default on Posix-like systems, equals
windows, default on Windows, equals
colours+webbut with extra code needed for running it under the default Cygwin terminal (mintty)
You can specify which to compile with the
-c switch. Not supplying one will make it build the default for your operating system.
$ dub build -c cygwin
There are a few Windows caveats.
- Web URL lookup, including the web titles and Reddit plugins, will not work out of the box with secure HTTPS connections due to missing libraries. Download a "light" installer from slproweb.com and install to system libraries, and it should no longer warn on program start.
- Terminal colours may also not work, depending on your version of Windows and likely your terminal font. Unsure of how to fix this.
- Use in Cygwin terminals without compiling the aforementioned
cygwinconfiguration will be unpleasant (terminal output will be broken). Powershell consoles are not affected and can be used with any configuration, as can normal
cmdones, albeit with the previously mentioned colour issues.
How to use
The bot needs the services account name of one or more administrators of the bot, and/or one or more home channels to operate in. It cannot work without having at least one of the two, so you need to generate and edit a configuration file before starting.
$ ./kameloso --writeconfig
kameloso.conf will be created in a directory dependent on your platform.
- Other unexpected platforms: fallback to current working directory
Open the file in there in a text editor and fill in the fields. Peruse it to get an idea of the features available.
You can override some settings with arguments on the command line, listed by calling the program with
--help. If you specify some and also add
--writeconfig it will save these changes to the file so you don't have to repeat them, without having to manually edit the configuration file.
$ ./kameloso \ --server irc.freenode.net \ --nickname "kameloso" \ --admins "you,friend,thatguy" \ --homes "#channel,#elsewhere" \ --channels "#d,##networking" \ --writeconfig Configuration file written to /home/user/.config/kameloso/kameloso.conf
Repeated calls of
--writeconfig will only regenerate the file. It will never overwrite custom settings, only complement them with new ones. Mind however that it will remove any lines not corresponding to a valid setting, which includes old settings no longer in use and comments.
If you have compiled in colours and you have bright terminal background, the colours may be hard to see and the text difficult to read. If so, make sure to pass the
--bright argument, and/or modify the configuration file;
[Core]. The bot uses the entire range of 8-colour ANSI, so if one or more colours are too dark or bright even with the right
brightTerminal setting, please see to your terminal appearance settings. This is not uncommon, especially with backgrounds that are not fully black or white. (read: Monokai, Breeze, Solaris, ...)
More server-specific resource files will be created the first time you connect to a server. These include
users.json, in which you whitelist which accounts get to access the bot's features. Where these are stored also depends on platform; in the case of MacOS and Windows they will be put in subdirectories of the same directory as the configuration file, listed above. On Linux, under
~/.local/share/kameloso (or wherever
$XDG_DATA_HOME points). As before it falls back to the working directory on other unknown platforms.
Once the bot has joined a home channel, it's ready. Mind that you need to authorise yourself with services with an account listed as an administrator in the configuration file to make it listen to anything you do. Before allowing anyone to trigger any functionality it will look them up and compare their accounts with its white- and blacklists. Refer to the
admins field in the configuration file, as well as your
you joined #channel kameloso sets mode +o you you | !say foo kameloso | foo you | foo bar baz you | s/bar/BAR/ kameloso | you | foo BAR baz you | !8ball kameloso | It is decidedly so you | !addquote you This is a quote kameloso | Quote saved. (1 on record) you | !quote you kameloso | you | This is a quote you | !note OfflinePerson Why so offline? kameloso | Note added. you | !seen OfflinePerson kameloso | I last saw OfflinePerson 1 hour and 34 minutes ago. you | kameloso: sudo PRIVMSG #channel :this is a raw IRC command kameloso | this is a raw IRC command you | !bash 85514 kameloso | <Reverend> IRC is just multiplayer notepad. you | https://www.youtube.com/watch?v=s-mOy8VUEBk kameloso | [youtube.com] Danish language you | !reddit https://dlang.org/blog/2018/01/04/dmd-2-078-0-has-been-released kameloso | Reddit post: https://www.reddit.com/r/programming/comments/7o2tcw/dmd_20780_has_been_released kameloso | [reddit.com] DMD 2.078.0 Has Been Released : programming
Online help and commands
help to the bot in a private message for a summary of available bot commands, and
help [plugin] [command] for a brief description of a specific one. Mind that commands defined as regular expressions cannot be shown, due to technical reasons.
The prefix character (here "
!") is configurable; refer to your generated configuration file. Common alternatives are
~, making it
[Core] prefix !
It can technically be any string and not just one character. Enquote it if you want any spaces as part of the prefix token, like
[IRCBot] nickname twitchaccount pass oauth:the50letteroauthstringgoeshere homes #twitchaccount channels #streamer1,#streamer2,#streamer3 [IRCServer] address irc.chat.twitch.tv port 6667
pass is not the same as
authPassword. It is supplied very early during login (or registration) to allow you to connect -- even before negotiating username and nickname, which is otherwise the very first thing to happen.
authPassword is something that is sent to a services bot (like
AuthServ) after registration has finished and you have successfully logged onto the server. (In the case of SASL authentication,
authPassword is used during late registration.)
Mind that in some cases Twitch does not behave as a conventional IRC server. You cannot readily trust who is +o and who isn't, as it will oscillate to -o at regular intervals. It is also possible to leave a channel that you aren't in, and you cannot join a channel if that corresponding user doesn't exist.
Known bug: A user that is in more than one observed channel can be displayed with a badge in one that he/she actually has in another. This is because a user can only have one badge at a time per the current implementation. It's not an unsolvable problem but it would need some redesigning.
Use as a library
The IRC event parsing bits are largely decoupled from the bot parts of the program, needing only some common non-bot-oriented helper modules.
Feel free to copy these and drop them into your own project. Look up the structs
IRCParser to get started. See the versions at the top of
irc.d. Some very basic examples can be found in
Debugging and generating unit tests
Writing an IRC bot when servers all behave differently is a game of cat-and-mouse. You will come across unexpected events for which there are no rules on how to parse. It may be some messages silently have weird values in the wrong fields (e.g. nickname where channel should go), or be empty when they shouldn't -- or more likely there will be an error message. Please file an issue.
If you're working on developing the bot yourself, you can generate unit test assert blocks for new events by passing the command-line
--asserts flag, specifying the server daemon and pasting the raw line. Copy the generated assert block and place it in
tests/events.d, or wherever is appropriate.
If more state is necessary to replicate the environment, such as needing things from
RPL_ISUPPORT or a specific resolved server address (from early
RPL_HELLO), paste/fake the raw line for those first and it will inherit the implied changes for any following lines throughout the session. It will print the changes evoked, so you'll know if you succeeded.
- pipedream zero: no compiler segfaults
- pipedream: DCC
- pipedream two:
- optional formatting in IRC output? (later if at all)
- notes triggers? (later)
seendoing what? channel-split?
- automode channel awareness boost
- private notes
This project is licensed under the MIT license - see the LICENSE file for details.
- Registered by JR
- 1.0.0-rc.3 released 7 months ago
- Copyright © 2018, JR