Igor

Igor v0.3.0 Igor 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.

Link to this section 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.

Link to this section Types

Link to this type

t()

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

Link to this section Functions

Link to this function

%Igor{}

View Source (struct)

The handle for a bot.

Link to this function

child_spec(init_arg)

View Source

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

escape_html(str)

View Source
Link to this function

html_to_text(html)

View Source

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 "
Link to this function

parse_text_to_command(text, bot)

View Source

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"]
Link to this function

react(reaction, message, bot)

View Source

React to a message.

Link to this function

send(message, room, bot)

View Source 
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.

Link to this function

start_link(opts)

View Source 
start_link(opts :: Keyword.t()) :: {:ok, pid()}

Start the bot process.

Link to this function

strip_reply_html(html)

View Source

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