Igor.Responder.ModuleHelper behaviour (Igor v0.3.1)

View Source

Helper for writing responder modules.

Responses can be defined by using the command or listen macros. If those macros are not sufficient, responses can be defined by defining a respond/2 function, where the first argument is an Igor.Message and the second argument is an Igor.

Responses can be documented using the @help attribute. These will show up when a user uses the help command, if the Igor.Responder.Help module is used. The value should be a map that can contain the following keys:

  • command :: String.t() | [String.t()] (required): the command that is implemented. If it is a sub-command, then this should be a list. Otherwise, it can be a string or a 1-element list. For example, a GitLab responder could implement a gitlab create command, in which case, this would be ["gitlab", "create"].

  • args :: Polyjuice.Client.MsgBuilder.MsgData.t() (optional): the arguments that the command takes.
  • short :: Polyjuice.Client.MsgBuilder.MsgData.t() (optional): a brief description of what the command does. This will be shown when displaying the list of commands that the bot understands.
  • long :: Polyjuice.Client.MsgBuilder.MsgData.t() (optional): a detailed description of what the command does. This will be shown when the user requests help for the command.

Example

defmodule Ping do
  use Igor.Responder

  @help %{command: "ping", args: "[response]", short: "respond with a pong"}
  command ["ping"], msg, bot do
    "pong" |> Igor.send(msg, bot)
  end
end

More complicated responders (e.g. that require state) can be created by writing a module that implements the Igor.Responder.Proto protocol.

Summary

Callbacks

help(cmdprefix)

Invoked to get the help messages.

help(cmdprefix, cmd)

Invoked to get the help message for a certain command.

respond(msg, bot)

Invoked to respond to a message.

Functions

command(pattern, msg, bot, list)

Defines a command that the bot understands.

listen(regexp, matches, msg, bot, list)

Respond to messages that match a regular expression.

Callbacks

help(cmdprefix)

@callback help(cmdprefix :: String.t()) :: [String.t()]

Invoked to get the help messages.

help(cmdprefix, cmd)

@callback help(cmdprefix :: String.t(), cmd :: String.t()) :: String.t() | nil

Invoked to get the help message for a certain command.

respond(msg, bot)

@callback respond(msg :: Igor.Message.t(), bot :: Igor.t()) :: any()

Invoked to respond to a message.

Functions

command(pattern, msg, bot, list)

(macro)

Defines a command that the bot understands.

A command is represented as a list of strings, and can be pattern matched.

Examples

Define a command that adds numbers together.

command(["add" | items], msg, bot) do
  Enum.map(items, &Float.parse)
    |> Enum.reduce(fn x, acc -> x + acc end)
    |> to_string
    |> Igor.send(msg, bot)
end

A command can have multiple syntaxes.

command(["roll"], msg, bot) do
  # if no argument is given, roll a d6
  :rand.uniform(6) |> to_string |> Igor.send(msg, bot)
end
command(["roll" | dice], msg, bot) do
  # if arguments are given, roll the specified dice
  dice |> Enum.flat_map(fn spec ->
      {times, max} = parse_spec(spec) # parse_spec is left as an exercise for the reader
      Enum.map 1..times, fn _ -> :rand.uniform(max) |> to_string end
    end)
    |> Enum.join(" ")
    |> Igor.send(msg, bot)
end

listen(regexp, matches, msg, bot, list)

(macro)

Respond to messages that match a regular expression.

Examples

Respond to messages that contain #(number) with a link to the issue tracker.

listen ~r/#(\d+)/, matches, msg, bot do
  Enum.map(
    matches,
    fn [_, issuenum] ->
      ["https://gitlab.com/uhoreg/igor/issues/", issuenum]
    end
  )
end
|> intersperse("\n")
|> Igor.send(msg, bot)