An IRC bot
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.
It includes a framework that works with the majority of server networks. IRC is standardised but servers still come in many flavours, where some conflict with others. If something doesn't immediately work it's often mostly a case of specialcasing it for that particular IRC network or server daemon.
Current functionality includes:
- bedazzling coloured terminal output like it's the 90s
notesto offline users that get played back when they come online
seenplugin; reporting when a user was last seen, written as a rough tutorial and a simple example of how plugins work
- looking up titles of pasted web URLs
- Reddit post lookup
- Twitch events; simple Twitch chatbot is now easy (see notes on connecting below)
sed-replacement of the last message sent (
- piping text from the terminal to the server
- mIRC colour coding and text effects (bold, underlined, ...), translated into Bash formatting
- SASL authentication (
- some plugins don't yet differentiate between different home channels, if there are more than one
- quirky IRC server daemons that haven't been tested against can exhibit weird behaviour when parsing goes awry (need examples to fix)
Use on networks without services may be difficult, since the bot identifies people by their services (
AuthServ/...) account names. As such you will probably want to register yourself and the bot, where available.
Testing is mainly done on freenode, so support and coverage is best there.
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.
It's possible to build it manually without
dub, but it is non-trivial if you want the web-related plugins to work.
GitHub offers downloads in ZIP format, but it's arguably easier to use
git and get a copy of the source that way.
$ git clone https://github.com/zorael/kameloso.git $ cd kameloso
$ dub build
This will compile it in the default
debug build type, which adds some extra code and debugging symbols. You can automatically strip these and add some optimisations by building it in
release mode with
dub build -b release. Refer to the output of
dub build --help for more build types.
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.
unittest 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 -b release -c cygwin
There are a few Windows caveats.
- Web URL lookup, including the web titles and Reddit plugins, may not work out of the box with secure HTTPS connections, due to the default installation of
dlang-requestsnot finding the correct libraries. Unsure of how to fix this. Normal HTTP accesses should work fine.
- Terminal colours may also not work, depending on your version of Windows and likely your terminal font. Unsure of how to enable this.
- Use in Cygwin terminals without the aforementioned build configuration
cygwinwill be unpleasant. Normal
cmdand Powershell consoles are not affected.
How to use
The bot needs the services account name of the administrator(s) 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 create and edit a configuration file before starting.
$ ./kameloso --writeconfig
Open the new
kameloso.conf in a text editor and fill in the fields.
If you have compiled in colours, they may be hard to see and the text difficult to read if you have a bright terminal background. 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, ...)
Once the bot has joined a channel it's ready. Mind that you need to authorise yourself with any services (with an account listed as an adminisrator in the configuration file) before it will listen to anything you do. Before allowing anyone to trigger any functionality it will look them up and compare their accounts with its internal whitelists.
you | !say herp kameloso | herp 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 #thischannel :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
help to the bot in a private query 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 will not 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 different from
authPassword in that it is supplied very early during login/registration to even 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 services after registration is finished and you have successfully logged onto the server. (In the case of SASL authentication,
authPassword is used during late registration.)
Mind that a full Twitch bot cannot be implemented as an IRC client.
Use as a library
The IRC server string-parsing modules (
ircdefs.d) are largely discoupled from the rest of the program, needing only some helper modules;
meld.d. The big exception is one funtion that warns the user of abnormalities after parsing (
irc.d), which uses a logger class to inform the user of what seems wrong. The logger in turn imports more. Version that function out and you can drop the files into your own project.
(But not neccessarily for
- pipedream: DCC
- pipedream two:
- optional formatting in IRC output? (later if at all)
- notes triggers? (later)
seendoing what? channel-split?
- update wiki
- blacklists; by mask, by account? where and when?
- auto-mode plugin?
This project is licensed under the MIT license - see the LICENSE file for details.
- Registered by JR
- 1.0.0-beta.4 released a year ago
- Copyright © 2018, JR