Igor (Igor v0.3.1)

View Source

Bot framework for Matrix.

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, 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

Igor.start_link(opts)

where opts is a keyword list as described in the 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
  • mxid: (optional, deprecated) the bot's Matrix user ID. Defaults to the user ID associated with the client object.
  • 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 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
  • client_opts: (optional) Any additional options to pass when creating the Polyjuice.Client. This option only has effect if start_client, make_client, and client are not specified.

Responders

Igor uses responders to respond to Matrix events, and comes with some sample responders as submodules of Igor.Responder. For information on writing your own responder, see the documentation for Igor.Responder.

Bot functions

This module provides some functions that can be used in writing bots, such as sending messages and reactions.

Summary

Types

t()

Functions

%Igor{}

The handle for a bot.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

escape_html(str)
html_to_text(html)

Convert Matrix HTML to an approximate text rendering that should be more useful for parsing. This will not necessarily be a useful text rendering for displaying to a user; it is only meant to be used for parsing.

parse_text_to_command(text, bot)

Parse text into a command list if possible.

react(reaction, message, bot)

React to a message.

send(message, room, bot)

Send a message to a room.

start_link(opts)

Start the bot process.

strip_reply_html(html)

Strip out the replied-to message from a message reply in Matrix HTML format. Also sanitizes the HTML.

Types

t()

@type t() :: %Igor{
  bot_name: String.t(),
  client: Polyjuice.Client.API.t(),
  command_prefix: Regex.t(),
  opts: map(),
  responders: [],
  storage: Polyjuice.Client.Storage.t()
}

Functions

%Igor{}

(struct)

The handle for a bot.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

escape_html(str)

html_to_text(html)

Convert Matrix HTML to an approximate text rendering that should be more useful for parsing. This will not necessarily be a useful text rendering for displaying to a user; it is only meant to be used for parsing.

Examples

iex> Igor.html_to_text("<mx-reply>Someone else's message</mx-reply>foo<img alt=\"bar\"><b>baz</b>")
"foobarbaz"

iex> Igor.html_to_text("Yes <a href=\"https://matrix.to/#/%40hubert:uhoreg.ca\">master</a>")
"Yes  @hubert:uhoreg.ca "

parse_text_to_command(text, bot)

Parse text into a command list if possible.

Examples

iex> Igor.parse_text_to_command("igor: foo bar baz", %Igor{})
["foo", "bar", "baz"]

iex> Igor.parse_text_to_command("!foo bar baz", %Igor{})
["foo", "bar", "baz"]

react(reaction, message, bot)

React to a message.

send(message, room, bot)

@spec send(
  message :: Igor.Message.t() | Polyjuice.Client.MsgBuilder.MsgData.t() | map(),
  room :: String.t() | Igor.Message.t(),
  bot :: t()
) :: Any

Send a message to a room.

The message can be a string, a tuple (where the first item is the message in plain text, and the second item is the message in HTML), an Igor.Message, or a map (giving the full message contents).

The room can either be a room ID as a string, or the Igor.Message that the message is sent in response to.

start_link(opts)

@spec start_link(opts :: Keyword.t()) :: {:ok, pid()}

Start the bot process.

strip_reply_html(html)

Strip out the replied-to message from a message reply in Matrix HTML format. Also sanitizes the HTML.

Examples

iex> Igor.strip_reply_html("<mx-reply>Someone else's message </mx-reply>foo<img alt=\"bar\"><b>baz</B><unclosed-tag>bla")
"foo<img alt=\"bar\"><b>baz</b><unclosed-tag>bla</unclosed-tag>"