kameloso 0.9.14

IRC Bot


To use this package, run the following command in your project's root directory:

Manual usage
Put the following dependency into your project's dependences section:

kameloso Build Status

kameloso sits and listens in the channels you specify and reacts to events, like bots generally do.

Features are added as plugins, written as D modules. A variety comes bundled but it's very easy to write your own. Ideas welcome.

It includes a framework that works with the vast majority of server networks. IRC is standardised but servers still come in many flavours and some conflict with others. Where it doesn't immediately work it's often a case of specialcasing something for that particular IRC network or server daemon.

Use on networks without services may be difficult, since the bot identifies people by their services (NickServ/Q/AuthServ/...) login names. As such you will probably want to register and reserve nicknames for both yourself and the bot, where available.

Current functionality includes:

  • bedazzling coloured terminal output like it's the 90s
  • user quotes service
  • saving notes to offline users that get played back when they come online
  • seen plugin; 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
  • sed-replacement of the last message sent (s/this/that/ substitution)
  • piping text from the terminal to the server
  • mIRC colour coding and text effects (bold, underlined, ...), translated into Bash formatting
  • SASL authentication (plain)

Windows

There are a few Windows caveats.

  • Web URL title lookup, including the Bash and Reddit plugins, may not work out of the box with secure HTTPS connections, due to the default installation of dlang-requests not finding the correct OpenSSL libraries. Unsure of how to fix this.
  • Terminal colours may also not work, depending on your version of Windows and likely your terminal font. Unsure of how to enable this. By default it will compile on Windows with colours disabled, but they can be enabled by specifying a different build configuration.

Getting Started

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.

Prerequisites

You need a D compiler and the official dub package manager. There are three compilers available; see here for an overview.

kameloso can be built using the reference compiler dmd and the LLVM-based ldc, but the GCC-based gdc comes with a version of the standard library that is too old, at time of writing.

It's possible to build it without dub but it is non-trivial if you want web-related plugins to work.

Downloading

GitHub offers downloads in ZIP format, but it's easier to use git and clone the repository that way.

$ git clone https://github.com/zorael/kameloso.git
$ cd kameloso

Compiling

$ 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 in unittest mode for them to run.

$ 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 the program in one go.

The available build configurations are:

  • vanilla, builds without any specific extras
  • colours, compiles in terminal colours
  • web, compiles in plugins with web lookup (webtitles, bashquotes and reddit)
  • colours+web, includes both of the above
  • posix, default on Posix-like systems, compiles both colours and web
  • windows, default on Windows, equals vanilla
  • cygwin, equals windows but with extra code needed for running it under the default Cygwin terminal (mintty)

You can specify which to build with the -c switch.

$ dub build -b release -c vanilla

How to use

The bot needs the services login name of the administrator/master of the bot, and/or one or more home channels to operate in. It cannot work without having at least one of the two. The hardcoded defaults contain neither, 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 an old configuration file and you notice missing options, such as plugin-specific settings, just run --writeconfig again and your file should be updated with all entries. There are many more plugin-specific and less important options available than what is displayed at program start.

The colours 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; brightTerminal under [Core]. The bot uses the entire range of ANSI colours, so if one or more 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 and whitelist your master login 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 them with its internal list.

 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://www.youtube.com/watch?v=s-mOy8VUEBk

kameloso | Reddit post: https://www.reddit.com/r/languagelearning/comments/7dcxfa/norwegiancomedyaboutthedanishlanguage4m15s/

The prefix character (here '!') is configurable; see your generated configuration file. Common alternatives are '.' and '~', making it .note and ~quote respectively.

[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 "please ".

Twitch

To connect to Twitch servers you must supply an OAuth token.

Generate one here, then add it to your kameloso.conf in the pass field.

[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, when the username and nickname is still being negotiated, whereas authPassword is something that is sent to nickname services after registration is finished and you have successfully logged onto the server. (In the case of SASL, authPassword is used late during registration.)

Mind that a full Twitch bot cannot be implemented as an IRC client.

TODO

  • "online" help; listing of verbs/commands
  • investigate inverse channel behaviour (blacklists)
  • pipedream: DCC
  • pipedream two: ncurses
  • Travis LDC tests
  • more command-line flags
  • more modules? uda.d/attribute.d?
  • more specific users in configuration arrays? nick/address/etc... needs rework of config.d
  • concurrency message-checking as Fiber?
  • timed Fibers

Built With

License

This project is licensed under the MIT license - see the LICENSE file for details.

Acknowledgments

Authors:
  • JR
Dependencies:
none
Versions:
3.14.159 2024-Jan-27
3.13.0 2023-Sep-26
3.12.1 2023-Sep-06
3.12.0 2023-Aug-25
3.11.1 2023-Jul-21
Show all 90 versions
Download Stats:
  • 0 downloads today

  • 0 downloads this week

  • 0 downloads this month

  • 177 downloads total

Score:
1.7
Short URL:
kameloso.dub.pm