Kaguya v0.6.5 Kaguya.Module

Module which provides functionality used for creating IRC modules.

When this module is used, it will create wrapper functions which allow it to be automatically registered as a module and include all macros. It can be included with: use Kaguya.Module, "module name here"

Once this is done, the module will autogenerate help documents, start automatically and be able to use the handle, defh, and other macros.

Modules can be loaded and unloaded using Kaguya.Util.loadModule, Kaguya.Util.unloadModule, and Kaguya.Util.reloadModule.

Modules also provide three hooks for certain events that you may want to react to. These are module_init(), module_load(), and module_unload(). Init will be run when the bot starts, and the load/unload functions are run whenever a module is loaded or unloaded.

Link to this section Summary

Functions

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

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

Convenience macro for defining handlers. It injects the variable message into the environment allowing macros like reply to work automatically. It additionally detects various map types as arguments and is able to differentiate between maps which destructure Kaguya messages, vs. the match argument

Enforces certain constraints around a block. This will replace the validate macro

Determines whether or not a response should be sent back to a channel or if the recipient sent the message in a PM

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

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

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

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

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

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

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

Sends a response to the user who sent the PRIVMSG with a given message via a private message. Example: reply_priv "Hi"

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

Creates a validation stack for use in a handler

Link to this section Functions

Link to this macro await_resp(match_str, opts \\ []) (macro)

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.
Link to this function await_resp(match_str, chan, nick, timeout, match_group)

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

Link to this macro defh(arg, list) (macro)

Convenience macro for defining handlers. It injects the variable message into the environment allowing macros like reply to work automatically. It additionally detects various map types as arguments and is able to differentiate between maps which destructure Kaguya messages, vs. the match argument.

For example:

# This handler matches all calls to it.
defh some_handler do
...
end

# This handler matches the IRC message struct's nick param.
defh some_other_handler(%{user: %{nick: nick}}) do
...
end

# This handler matches the given match argument's value.
defh some_other_handler(%{"match_arg" => val) do
...
end

# This handler matches the given match argument's value and the IRC message's nick.
# Note that the order of these two maps in the arguments DOES NOT MATTER.
# The macro will automatically detect which argument is mapped to which type of input for you.
defh some_other_handler(%{user: %{nick: nick}, %{"match_arg" => val) do
...
end
Link to this macro enforce(validators, list) (macro)

Enforces certain constraints around a block. This will replace the validate macro.

Example:

def is_me(msg), do: true
def not_ignored(msg), do: true

handle "PRIVMSG" do
enforce [:is_me, :not_ignored] do
match "Hi", :someHandler
end

enforce :is_me do
match "Bye", :someOtherHandler
end
Link to this function enforce_rec(list, body)
Link to this function get_recip(message)

Determines whether or not a response should be sent back to a channel or if the recipient sent the message in a PM

Link to this macro handle(command, list) (macro)

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

Link to this macro init_attrs() (macro)
Link to this macro match(match, function, opts \\ []) (macro)

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]+"
match "!join :channel([#&][a-zA-Z0-9]+)", :joinChannel"
match ["!say ~msg", "!s ~msg"], :sayMessage
end

In this example, the genRand 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}. Additionally the usage of a list allows for command aliases, in the second match.

The second match well find channel joining messages, using an embedded regex to validate a channel. These embedded regexs will override the match_group value and should be used when you need to match multiple parameters which will not accept the same regex. That or if you just don’t feel like writing match_group: "".

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 - Default 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. The uniq option can be either channel level or nick level, specified with the option :chan or :nick.
  • uniq_overridable - This is used to determine whether or not a unique match can be overriden by a new match, or if the new match should exit and allow the previous match to continue running. By default it is true, and new matches will kill off old matches.

Help commands will additionally be generated for all matches. The “help_cmd” option of the config will allow specifying a prefix to use for help triggers, and this command can be used standalone to list all commands in format “cmd1; cmd2; …”. Additionally, “help_cmd some_cmd” will display more detailed documentation for a given command, including a description(derived from the @doc attribute of the specified handler), and aliases(all non head items in a list based match - [“!queue”, “!q”] will generate a single help command for !queue, and list “!q” as an alias”.

Link to this macro match_all(function, opts \\ []) (macro)

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.
Link to this macro match_re(re, function, opts \\ []) (macro)

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.
Link to this macro reply(response) (macro)

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

Link to this macro reply_notice(response) (macro)

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

Link to this macro reply_priv(response) (macro)

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

Link to this macro reply_priv_notice(response) (macro)

Sends a response to the user who sent the PRIVMSG with a given message via a private message. Example: reply_priv "Hi"

Link to this macro validate(validator, list) (macro)

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.

Link to this macro validator(name, list) (macro)

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.