# Igor

Igor allows you to write bots for [Matrix](

## Installation

The package can be installed by adding `igor` to your list of dependencies in

def deps do
    {:igor, "~> 0.2.1"}

Igor depends on
[html5ever_elixir](, which in turn
depends on the html5ever Rust library, so to compile Igor, you will need to
[install Rust](

Note that html5ever_elixir 0.7.0 [does not work with OTP
22](, but
html5ever_elixir 0.8.0 does not compile with older versions of Rust (notably,
the version of Rust shipped with Debian Buster), so there isn't a single
version of html5ever_elixir that will work universally. Currently, `mix.lock`
specifies version 0.7.0, but if you need/want to use version 0.8.0, run `mix
deps.unlock html5ever rustler` and then `mix deps.get`.

## Running the bot

### Standalone

To run Igor on its own, create a new Elixir project that depends on it and on
any plugins that you want to use, and run `mix deps.get` to fetch the
dependencies.  Then create a `config/config.exs` file (see
`config/config_sample.exs` for an example), and call `mix` to start
the bot.

### As part of an application

Igor can also be started from within another Elixir application by calling


where opts is a keyword list as described in the [configuring](#configuring)
section below.  Or it can be started by a supervisor:

children = [
  {Igor, opts}
Supervisor.start_link(children, strategy: :one_for_one)

## Configuring

Igor takes the following configuration parameters:

- `start_client:` (optional) a function that starts a client process and
  returns `{:ok, pid, client}`, where `client` is something that implements
  `Polyjuice.Client.API`.  The function will be given three arguments: a
  `Polyjuice.Client.Handler`, a `Polyjuice.Client.Storage`, and a sync filter.
- `make_client:` (optional) a function that returns something that implements
  `Polyjuice.Client.API`.  The function will be given three arguments: a
  `Polyjuice.Client.Handler`, a `Polyjuice.Client.Storage`, and a sync filter.
- `client:` (optional) a `Polyjuice.Client.API`.  The `start_client` option
  takes precedence over `make_client`, which takes precedence over `client`.
  If none of these options is specified, Igor will create a new
  `Polyjuice.Client` using the other options given.
- `homeserver_url:` (required if `start_client`, `make_client`, and `client`
  are not set) the base URL of the homeserver
- `access_token:` (optional) the access token for the bot user to authenticate
  with the homeserver
- `bot_name:` (optional) the bot's name, for use with responding to commands.
  Default: `igor`
- `aka:` (optional) list other names that the bot will respond to for commands.
  Default: `[]`
- `command_prefixes:` (optional) list prefixes that can be used for triggering
  commands.  Default: `[]`
- `responders:` (optional) list of [responders](#responders) to use.  Default:
- `storage:` (optional, recommended) persistent storage to use.  The default
  value is not suitable for production use, since it does not persist data
  across restarts.  Default: `{Igor.Storage, :ets, []}`
- `accept_invites:` (optional) whether or not to accept invites.  If `true`,
  accept all invites.  If `false`, reject all invites.  If a list of strings,
  accept invites from any of the users IDs listed, and reject invites from
  others.  Default: `true`

## Responders

Igor uses responders to respond to Matrix events, and comes with some [sample
responders](lib/igor/responder/).  For information on writing your own
responder, see the documentation for `Igor.Responder`.