irc-bot.rs

irc-bot is a library for writing Internet Relay Chat (IRC) bots in the programming language Rust, additionally providing a pre-configured bot for immediate use.

This project is hosted both on GitHub and on GitLab; the repositories are synchronized automatically.

If you use, or are interested in using, this library, you may post in one of the support tickets that have been opened on GitHub and on GitLab in which for people to note their interest in this library so that this library's maintainers can survey them as to, notify them of, and/or help them adjust to changes in the API of this library, and perhaps provide other support.

Documentation

What documentation there is for the versions of this crate published to Crates.io should be available on Docs.rs. Also available is documentation for the development version of this crate, i.e., for the latest build of this crate from the Git branch dev.

Contributing

Please see the file CONTRIBUTING.md. Please note that the said file contains some terms, particularly concerning licensing of contributions, to which one must agree to contribute to this project.

Licensing

All parts of this crate are available under the standard open-source software licence or licences specified in the file Cargo.toml. From the earliest release of this crate, this has been the Apache License, version 2.0.

Some portions of this crate may be available under other licences in addition, but, in any such case, one may opt to accept such portions solely under the crate-wide licence (or any of the crate-wide licences, if there are multiple crate-wide licences).

Quick-start

To use this library without writing one's own bot with it, one can run the provided program src/bin/egbot.rs:

$ # For most people:
$ cargo run
$ # For NixOS users:
$ make run

The name egbot is derived from "e.g.", which means "for example", and is also a pun on the name of Eggdrop, an old IRC bot.

The bot can be configured by editing the YAML file config.yaml. One at least should put one's IRC nickname ("nick") in the admins field — e.g., if one's nick is "Ferris":

admins:
  - nick: Ferris

Configuration fields currently supported are as follows (with values given for example only) (TODO: Document these in rustdoc, with rich text):

# A string to be used as the bot's IRC nickname. This field is required.
nickname: egbot

# A string to be used as the bot's IRC username (which has little effect
# in most cases). Defaults to the nickname.
username: egbot

# A string to be used as the bot's IRC "realname" or "GECOS string", which
# has still less effect and is often used to display information about a
# bot's software. Defaults to displaying information about the bot's
# software.
realname: 'Built with `irc-bot.rs`.'

# A list of servers to which the bot should connect on start-up.
# Currently, only the first server will be used, and the bot will crash if
# no servers are listed; both of these issues should be fixed at some
# future point.
servers:
  - name: Mozilla
    host: irc.mozilla.org
    port: 6697
    # Whether to use Transport Layer Security. Defaults to `true`.
    TLS: true
    # A list of channels that the bot should join after connecting. Note
    # that each channel's name should be wrapped in quotation marks or
    # otherwise escaped so that the '#' is not taken as the start of a
    # comment.
    channels:
      - name: '#rust-irc'

# A list of IRC users who will be authorized to direct the bot to run
# certain priviledged commands. For each listed user, the fields `nick`,
# `user`, and `host` may be specified; for each of which that is
# specified, a user will need to have a matching nickname, username, or
# hostname (respectively) to be authorized. All the specified fields must
# match for a user to be authorized.
admins:
  # To be authorized as an administrator of the bot, this user will need
  # to have the nickname "Ferris", the username "~crab", and the hostname
  # "rustacean.net":
  - nick: Ferris
    user: '~crab'
    host: rustacean.net
  # To be authorized as an administrator of the bot, this user will only
  # need have the nickname "c74d":
  - nick: c74d

Building

For most users, it should suffice simply to use Cargo:

$ cargo build

Users of the Linux distribution NixOS may prefer to use the provided Makefile, which wraps the tool nix-shell:

$ make build

Supported Rust versions

This package supports the Rust version noted in the file RUST_VERSION.yaml and any Rust versions backwards-compatible therewith. This minimum supported Rust version may be increased at any time to the latest release of Rust understood by the maintainer(s) of this package to fix or to mitigate one or more security vulnerabilities in the standard library or compiler output. The minimum supported Rust version may not be increased for reasons unrelated to security.

Although increases in the minimum supported Rust version are breaking changes, they are also, under this policy, bug-fixes, and for the purposes of SemVer they will be treated as bug-fixes and not as breaking changes. The idea here is that not upgrading Rust when a security fix is available is an irresponsible course of (in)action that the maintainer(s) of this package wish not to support, as confessedly doctrinairely as such a denial of support may ignore users' reasons for not updating.