# Igor

Igor allows you to write bots for [Matrix](https://matrix.org/).

## Installation

The package can be installed by adding `igor` to your list of dependencies in
`mix.exs`:

```elixir
def deps do
  [
    {:igor, "~> 0.1.0"}
  ]
end
```

Igor depends on
[html5ever_elixir](https://github.com/hansihe/html5ever_elixir), which in turn
depends on the html5ever Rust library, so to compile Igor, you will need to
[install Rust](https://www.rust-lang.org/tools/install).  (Also,
html5ever_elixir currently [does not work with OTP
22](https://github.com/hansihe/html5ever_elixir/issues/13), so you must use a
lower version of OTP until it is fixed.)

## 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 igor.run` to start
the bot.

### As part of an application

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

```elixir
Igor.start_link(opts)
```

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

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

### Configuring

Igor takes the following configuration parameters:

- `client:` (optional) something that implements `Polyjuice.Client.API`
- `homeserver_url:` (required if `client:` is not set) the base URL of the
  homeserver
- `access_token:` (required if `client:` is not set) the access token for the
  bot user to authenticate with the homeserver
- `device_id:` (optional) the device ID for the bot's session (currenty unused)
- `bot_name:` (optional) the bot's name, for use with responding to commands.
  Default: `igor`
- `mxid:` (required) the bot's Matrix user ID
- `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, []}`

## 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`.