Hedwig v1.0.0 Hedwig.Responder

Base module for building responders.

A responder is a module which setups up handlers for hearing and responding to incoming messages.

Hearing & Responding

Hedwig can hear messages said in a room or respond to messages directly addressed to it. Both methods take a regular expression, the message and a block to execute when there is a match. For example:

hear ~r/(hi|hello)/i, msg do
  # your code here
end

respond ~r/help$/i, msg do
  # your code here
end

Using captures

Responders support regular expression captures. It supports both normal captures and named captures. When a message matches, captures are handled automatically and added to the message’s :matches key.

Accessing the captures depends on the type of capture used in the responder’s regex. If named captures are used, captures will be available by the name, otherwise it will be available by an index, starting with 0.

Example:

# with indexed captures
hear ~r/i like (\w+), msg do
  emote msg, "likes #{msg.matches[1]} too!"
end

# with named captures
hear ~r/i like (?<subject>\w+), msg do
  emote msg, "likes #{msg.matches["subject"]} too!"
end

Summary

Functions

Send an emote message via the underlying adapter

Returns a random item from a list or range

Send a reply message via the underlying adapter

Sends a message via the underlying adapter

Macros

Matches messages based on the regular expression

Setups up an responder that will match when a message is prefixed with the bot’s name

Functions

emote(msg, text)

Send an emote message via the underlying adapter.

Example

emote msg, "goes and hides"
random(list)

Returns a random item from a list or range.

Example

send msg, random(["apples", "bananas", "carrots"])
reply(msg, text)

Send a reply message via the underlying adapter.

Example

reply msg, "Hello there!"
send(msg, text)

Sends a message via the underlying adapter.

Example

send msg, "Hello there!"
start_link(module, arg)

Macros

hear(regex, msg, state \\ Macro.escape(%{}), list)

Matches messages based on the regular expression.

Example

hear ~r/hello/, msg do
  # code to handle the message
end
respond(regex, msg, state \\ Macro.escape(%{}), list)

Setups up an responder that will match when a message is prefixed with the bot’s name.

Example

# Give our bot's name is "alfred", this responder
# would match for a message with the following text:
# "alfred hello"
respond ~r/hello/, msg do
  # code to handle the message
end