A scriptable, configuration powered IRC bot that can handle as many connnections as you want.

Table of Contents

1. Installing
   1. Building from source
   2. Downloading a binary
2. Configuring
   1. Choosing a configuration type
      1. Configuring with TOML
      2. Configuring with JSON
      3. Configuring with HCL
      4. Configuring with YAML
      5. Configuring with Java Properties
   2. Configuration options
      1. Nick
      2. User
      3. Name
      4. Host
      5. Port
      6. TLS
      7. Reconnect
      8. Ping
      9. Debug
      10. Channels
      11. Plugins
          1. Enabled
          2. Folders
          3. Pattern
          4. Events
      12. Storage
          1. Sqlite3
          2. MySQL
          3. Postgres
          4. MsSQL
      13. Store
          1. DSN
3. API
4. Extending Mouse with plugins
   1. Language choices
      1. JavaScript
      2. Lua
   2. Global functions
      1. Join
      2. Part
      3. Cycle
      4. Say
      5. Kick
      6. Ban
      7. Unban
      8. Op
      9. Deop
   3. Global variables
      1. Event
         1. Command
         2. Channel
         3. Message
         4. Host
         5. Nick
         6. User
      2. Storage
         1. Put
         2. Get
         3. Delete
5. Contributing
6. License

Installing

Building from source

Mouse is built on Go, and uses GB to vendor code. You should always be using the most recent version of both.

gb build all

Downloading a binary

This option is currently not available, but will be once Mouse hits version 1.0.0, and for each release after that.

Configuring

Your configuration file can exist at any of the following locations:

/etc/mouse/
$HOME/.mouse/
./

The name of your configuration file should always be mouse, but the file extension depends on the configuration type that you use.

Choosing a configuration type

Mouse uses the Viper library, which allows a variety of configuration types. Your configuration file must be named appropriately and should be one of the following:

mouse.toml
mouse.json
mouse.hcl
mouse.yaml
mouse.properties

Keep in mind that a configuration file named mouse.toml MUST be a TOML file, and the same goes for every other supported configuration file type.

Configuring with TOML

You can choose to configure Mouse with TOML. Configure your servers like this:

[servers]

    [server.a]
        nick = "mouse"

        # ...

        [servers.a.plugins.javascript]
            enabled = true

            # ...

    [server.b]
        nick = "mouse"

        # ...

You can see a full example at contrib/config-examples/config.toml.

Configuring with JSON

You can choose to configure Mouse with JSON. Configure your servers like this:

{
    "servers": {
        "a": {
            "nick": "mouse",
            "plugins": {
                "javascript": {
                    "enabled": true
                }
            }
        },
        "b": {
            "nick": "mouse"
        }
    }
}

You can see a full example at contrib/config-examples/config.json.

Configuring with HCL

You can choose to configure Mouse with HCL. Configure your servers like this:

servers "a" {
    nick = "mouse"

    # ...

    plugins "javascript" {
        enabled = true

        # ...
    }
}

servers "b" {
    nick = "mouse"

    # ...
}

You can see a full example at contrib/config-examples/config.hcl.

Configuring with YAML

You can choose to configure Mouse with YAML. Configure your servers like this:

servers:
    a:
        nick: mouse
        # ...

        plugins:
            javascript:
                enabled: true
                # ...
    b:
        nick: mouse
        # ...

You can see a full example at contrib/config-examples/config.yaml.

Configuring with Java Properties

You can choose to configure Mouse with Java Properties.

servers.a.nick = "mouse"
# ...
servers.a.plugins.javascript.enabled = true
# ...

servers.b.nick = "mouse"
# ...

You can see a full example at contrib/config-examples/config.properties.

Configuration options

All of the following configuration options should be nested in a server block. See above to find a full example of the configuration file type that you're using.

Nick

Nick is a string and the name that the bot will use once connected to the IRC server.

nick = "mouse"

User

User is a string and contains the username of the user.

user = "mouse"

Name

Name is a string and the real name of the bot.

name = "mouse"

Host

Host is a string that specifies what server to connect to. This should not include the port.

host = "irc.fc00.io"

Port

Port is an integer that specifies the port on the IRC server to connect to.

port = 6667

TLS

Currently does nothing.

tls = false

Reconnect

Reconnect is a boolean that when true will try to reconnect to the server if disconnected from.

reconnect = true

Ping

Ping is an integer that is the number of seconds we should ping the server for a health check.

ping = 30

Debug

Debug is a boolean that prints every IRC event for all connected servers to STDOUT.

debug = false

Channels

Channels is an array of strings that represent channels to join once connected to the IRC server. If the channel contains a password, it should be placed after the channel name with a space in between like #c is in the example below.

channels = [ "#a", "#b", "#c password" ]

Plugins

All of the following configuration options should be nested in a plugins block named for the plugin language to be configured. See below for more information on plugins.

Enabled

Enabled is a boolean that enables and disables plugin support for the specific plugin language.

enabled = true

Folders

Folders is an array of strings that contains a directory path for plugin files. This does not include a pattern, as the pattern attribute below decides what the pattern is for plugin files. A good use of multiple folders that contain scripts could be certain scripts that only one bot should access, and some scripts that all bots should access.

folders = [ "/home/username/.mouse/scripts/language/" ]

Pattern

Pattern is a string that contains the pattern for plugin files. This does not include the folder, as the folder attribute above decides where to look for the pattern.

pattern = "*.js"

Events

Events is an array of strings that contain official IRC event types that the plugins should run on.

events = [ "PRIVMSG" ]

Storage

Storage is a string that contains the type of storage engine that should be used. Information of which storage enginges, along with how to find an example of a DSN, are available are below:

storage = "sqlite3"

Sqlite3

sqlite3

Mouse uses the mattn/go-sqlite3 package for handling SQLite connections. You can find examples of DSN strings there.

MySQL

mysql

Mouse uses the go-sql-driver/mysql package for handling MySQL connections. You can find examples of DSN strings there.

Postgres

postgres

Mouse uses the lib/pq package for handling Postgres connections. You can find examples of DSN strings there.

MsSQL

mssql

Mouse uses the denisenkom/go-mssqldb package for handling MsSQL connections. You can find examples of DSN strings there.

Store

All of the following configuration options should be nested in a store block named for the storage engine to be configured.

DSN

DSN is a string that contains the data source name that should be used to connect to this specific storage engine.

dsn = "mouse.db"

API

See the API on GoDoc for the most up to date documentation.

Extending Mouse with plugins

Language choices

JavaScript

Using the embeddable JavaScript interpreter Otto, we can write plugins that deeply integrate with Mouse.

Lua

Coming soon.

Global functions

Join

The join function allows your bot to join a new channel. You may also specify a password if the channel has a password set, but that's not required. If there is a password, append it to the channel parameter with a space in between.

/**
 * @param string channel
 */
function join(channel)

Part

The part function allows your bot to part a channel.

/**
 * @param string channel
 */
function part(channel)

Cycle

The cycle function allows your bot to cycle on a channel. This will leave the channel, and then re-join it.

/**
 * @param string channel
 */
function cycle(channel)

Say

The say function allows your bot to send messages to any buffer that will allow it. When sending to a channel, the channel name must be prefixed with #, and when sending to a user, it should not be.

/**
 * @param string buffer
 * @param string message
 */
function say(buffer, message)

Kick

The kick function allows your bot to kick users out of a channel. You may also specify a reason, but that's not required.

/**
 * @param string channel
 * @param string user
 * @param string reason
 */
function kick(channel, user, reason)

Ban

The ban function allows your bot to ban users in a channel. You may also specify a reason, but that's not required.

/**
 * @param string channel
 * @param string user
 * @param string reason
 */
function ban(channel, user, reason)

Unban

The unban function allows your bot to unban users in a channel.

/**
 * @param string channel
 * @param string user
 */
function unban(channel, user)

Op

The op function allows your bot to change the mode of a user to +o in a channel.

/**
 * @param string channel
 * @param string user
 */
function op(channel, user)

Deop

The deop function allows your bot to change the mode of a user to -o in a channel.

/**
 * @param string channel
 * @param string user
 */
function deop(channel, user)

Global variables

There are variables set at the global scope that can be used in all plugins.

Event

On each event that the plugins are listening for, a new event is populated that is passed in to an event object in the global scope.

Command

Command is a string that contains the command that triggered this event. The most frequently used command in Mouse plugins is probably "PRIVMSG".

event.command

Channel

Channel is a string that contains the channel where the event took place. Channel is not just for channels, but also for private messages. If it is a channel, it will be prefixed with #.

event.channel

Message

Message is a string that contains the message of the event.

event.message

Host

Host is a string that contains the host of the user that triggered this event.

event.host

Nick

Nick is a string that contains the nick of the user that triggered this event.

event.nick

User

User is a string that contains the user of the user that triggered this event.

event.user

Storage

The storage object at the global scope cotains key functionality for using a database with plugins.

Put

The storage.put function allows your bot to save a key and value to a database. If the key does not exist, it will be created. If the key does exist, it will overwritten.

/**
 * @param string key
 * @param string val
 */
function put(key, val)

Get

The storage.get function allows your bot to get a value from a database from a key.

/**
 * @param string key
 */
function get(key)

Delete

The storage.delete function allows your bot to delete a row from a database with a key.

/**
 * @param string key
 */
function delete(key)

Contributing

Want to contribute? Do it. Read the contributing guidelines first.

License

Mouse is licensed under MIT.