chatty v0.5.0 Chatty

This module defines the public API for interacting with the IRC connection and the hook mechanism.

How hooks are invoked

When a new message arrives, the whole list of hooks is enumerated to see which ones are applicable to the message (based on parameters like the message kind, hook options, etc.). Then each applicable hook is executed in a separate Task, concurrently with the others. Finally, all of the hooks that returned a non-nil value (and didn’t crash or time out) will have their result sent back over the IRC connection.

The only exception to the above algorithm is when a hook is added as exclusive. In that case, its result will only be sent back if no other hook has returned a value.

Summary

Types

response()

Functions

add_presence_hook(id, f, opts \\ [])

Add a hook that will trigger whenever user joins or leave a channel

add_privmsg_hook(id, f, opts \\ [])

Add a hook that will trigger on incoming messages, whether they appear on a channel or are sent directly to the connected user’s nickname

add_topic_hook(id, f, opts \\ [])

Add a hook that will trigger whenever the channel topic changes

init_hooks()

remove_hook(id)

Remove a previously added hook

send_message(chan, msg)

Types

response ::
  singular_response |
  [singular_response] |
  nil

Functions

add_presence_hook(id, f, opts \\ [])

Specs

add_presence_hook(atom, (:join | :part, String.t, String.t -> response), Dict.t) ::
  :ok |
  {:error, term}

Add a hook that will trigger whenever user joins or leave a channel.

Arguments

id - arbitrary atom to identify the hook when calling remove_hook/1
f - function of 3 arguments:
- event – the type of the event, either :join or :part;
- sender – the nickname of the user who changed joined or left;
- channel – the channel on which the event happened;
options - a dict of options

Hook options

channel: <string> - the hook will be active only on the specified channel, as opposed to all channels that the connected user is present in.

Hook results

The same return values as for add_privmsg_hook/3 are supported.

add_privmsg_hook(id, f, opts \\ [])

Specs

add_privmsg_hook(atom, (String.t | [String.t], String.t, String.t -> response), Dict.t) ::
  :ok |
  {:error, term}

Add a hook that will trigger on incoming messages, whether they appear on a channel or are sent directly to the connected user’s nickname.

Arguments

id - arbitrary atom to identify the hook when calling remove_hook/1
f - function of 3 arguments that will be called on incoming messages where the arguments are:
- message – the message that was sent;
- sender – the nickname of the user who sent the message;
- channel – the channel on which the message was sent; can be the nickname of the connected user;
options - a dict of options

Hook options

in: :text | :tokens - specify the type of the message argument that the hook function will be called with. :text means that the message will be passed to the function as is. :tokens means that it will be split into words and the resulting list will be passed to the function.
direct: <boolean> - if true, the hook will be triggered only on those messages that are addressed to the connected user’s nickname in the following form:
```
<nickname>: message goes here
```
exclusive: <boolean> - if true, the hook will be triggered only if no other hook has returned a result.
channel: <string> - the hook will be active only on the specified channel, as opposed to all channels that the connected user is present in.

Hook results

A hook function may return one of the following values:

nil - nothing will be sent back
{:msg, <string>} - send a message to the channel where it was received
{:notice, <string>} - send a notice to the channel where it was received
{:reply, <string>} - send a message addressed to the original sender
{:reply, <receiver>, <string>} - send a message addressed to <receiver>
<list> - a list containing any of the above values which will result in one message for each list item

add_topic_hook(id, f, opts \\ [])

Specs

add_topic_hook(atom, (String.t, String.t, String.t -> response), Dict.t) ::
  :ok |
  {:error, term}

Add a hook that will trigger whenever the channel topic changes.

Arguments

id - arbitrary atom to identify the hook when calling remove_hook/1
f - function of 3 arguments:
- topic – the new topic;
- sender – the nickname of the user who changed the topic;
- channel – the channel on which the topic was changed;
options - a dict of options

Hook options

channel: <string> - the hook will be active only on the specified channel, as opposed to all channels that the connected user is present in.

Hook results

The same return values as for add_privmsg_hook/3 are supported.

init_hooks()

remove_hook(id)

Specs

remove_hook(atom) :: :ok | :not_found

Remove a previously added hook.

send_message(chan, msg)

Specs

send_message(String.t, String.t) :: :ok