Actual function used to execute await_resp. The macro should be preferred most of the time, but the function can be used if necessary.

Waits for an irc user to send a message which matches the given match string, and returns the resulting map. The user(s) listened for, channel listened for, timeout, and match params can all be tweaked. If the matcher times out, the variables new_message and resp will be set to nil, otherwise they will contain the message and the parameter map respectively for use.

You must use await_resp in a match which has the asnyc: true flag enabled or the module will time out.

Example

def handleOn(message, %{"target" => t, "repl" => r}) do
  reply "Fine."
  {msg, _resp} = await_resp t
  if msg != nil do
    reply r
  end
end

In this example, the bot will say “Fine.” upon the function being run, and then wait for the user in the channel to say the target phrase. On doing so, the bot responds with the given reply.

await_resp also can be called with certain options, these are:

• match_group - regex to be used for matching parameters in the given string. By default this is [a-zA-Z0-9]+
• nick - the user whose nick will be matched against in the callback. Use :any to allow for any nick to be matched against. By default, this will be the nick of the user who sent the currently processed messages
• chan - the channel to be matched against. Use :any to allow any channel to be matched against. By default this is the channel where the currently processed message was sent from.
• timeout - the timeout period for a message to be matched, in milliseconds. By default it is 60000, or 60 seconds.

Defines a group of matchers which will handle all messages of the corresponding IRC command.

Example

handle "PING" do
  match_all :pingHandler
  match_all :pingHandler2
end

In the example, all IRC messages which have the PING command will be matched against :pingHandler and :pingHandler2

Defines a matcher which will match a string defining various capture variables against the trailing portion of an IRC message.

Example

handle "PRIVMSG" do
  match "!rand :low :high", :genRand, match_group: "[0-9]+"
end

In this example, the geRand function will be called when a user sends a message to a channel saying something like !rand 0 10. If both parameters are strings, the genRand function will be passed the messages, and a map which will look like %{low: 0, high: 10}.

Available match string params are :param and ~param. The former will match a specific space separated parameter, whereas the latter matches an unlimited number of characters.

Match can also be called with a few different options. Currently there are:

• match_group - Regex which is used for matching in the match string. By default it is [a-zA-Z0-9]+
• async - Whether or not the matcher should be run synchronously or asynchronously. By default it is false, but should be set to true if await_resp is to be used.
• uniq - When used with the async option, this ensures only one version of the matcher can be running at any given time.

Defines a matcher which always calls its corresponding function. Example: match_all :pingHandler

The available options are:

• async - runs the matcher asynchronously when this is true
• uniq - ensures only one version of the matcher can be running per channel. Should be used with async: true.

Defines a matcher which will match a regex againt the trailing portion of an IRC message. Example: match_re ~r"me|you", :meOrYouHandler

The available options are:

• async - runs the matcher asynchronously when this is true
• uniq - ensures only one version of the matcher can be running per channel. Should be used with async: true.
• capture - if true, then the regex will be matched as a named captures, and the specified function will be called with the message and resulting map on successful match. By default this option is false.

Sends a response to the sender of the PRIVMSG with a given message. Example: reply "Hi"

Creates a scope in which only messages that succesfully pass through the given will be used.

Example:

handle "PRIVMSG" do
  validate :is_me do
    match "Hi", :hiHandler
  end
end

In the example, only messages which pass through the is_me validator, defined prior will be matched within this scope.

Creates a validation stack for use in a handler.

Example:

validator :is_me do
  :check_nick_for_me
end

def check_nick_for_me(%{user: %{nick: "me"}}), do: true
def check_nick_for_me(_message), do: false

In the example, a validator named :is_me is created. In the validator, any number of function can be defined with atoms, and they will be all called. Every validator function will be given a message, and should return either true or false.