# 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.2.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:

- `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
- `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, []}`
- `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`.