Actions


With an Action you can setup Snak to respond automatically to a wide variety of events. An Action consists of a specified event, like "On join" and a selected response, like "Send private message". With actions you can:
• Greet someone that joins a channel, and inform them of the channel rules.
• Authenticate yourself to a channel service when you join a channel.
• Play a sound when a friend signs on to IRC, or sends you a message.
• Accept DCC chats from known friends.
• Accept a particular kind of files, like MP3 automatically, and save them in a particular location.
• Open a MP3 file in iTunes after it has been received.
• Highlight messages that contain a particular word or your nick.
And much more.

Events and Responses


While you are using IRC several event may happen that require a response from you. Actions allows you to automate responses that you make all the time. To make an Action more specific, each event has parameters. When the selected event happens, Snak checks to see if the entered parameters apply. For instance, the "On join" events are checked when someone joins a channel.

The parameters for that event consists of a channel name and a nick. That means Snak will perform the response if the name of the channel matches the channel name event parameter, and if the nickname or userhost of the person matches the nick event parameter.
Whenever an event has a nick field you can use it to match on either the nickname or the userhost of the user in question.
ActionJoinPrivate

There are many combinations of events, parameters and responses. This allows you to automate a wide variety of situations.
In the above example you have an Action that responds when someone called myfriend or myfriend1 joins the channel #macintosh on Undernet. When that happens Snak will send a private message to the person that just joined with the text Hi and the nickname.

Each kind of event has a set of possible responses. The "On join" event has the most extensive response list of all the events. You can choose to send a channel message, a private message or a notice to the nick that just joined the channel. You can also do a whois in order to learn more about the person, or you can run an arbitrary command, play a sound or speak a message.

One of the other events is "On signoff" which occurs when someone from your notify list signs off IRC. This event only has three possible responses, namely to run an arbitrary command, to play a sound or speak a message.
There are many other possible events, and the following page describes each event, the event parameters and the possible responses.

Parameters


There are some common features of event parameters that allow you to apply a single Action in many situations.
For instance the parameters for the "On join" event can be set in several combinations:
• To have the Action apply to everyone joining a particular channel, fill out the channel name, and leave the nick blank.
• To have the Action apply in all channels whenever a particular nick joins, leave the channel name blank, and fill in the nick.
• Leave both channel name and nick blank to have the Action apply to everyone joining in all channels.
Some events, like "On channel message" also include a channel message parameter. The same rules apply so you can leave it blank to have the action apply to all channel messages or you can enter a text string to narrow the scope of the Action.

Matching text strings


In order to make it possible to match a parameter to more than one precise string, wildcards are used. A wildcard is a special character that stand in for other text. Snak supports three wildcards:
• '*' matches any sequence of characters.
• '%' matches any sequence of characters except a space.
• '?' matches any single character.
"% % abc" would match a message with two words and then the word "abc" "*abc* would match any message that contains "abc"

For example, if you have an Action with an "On join" event that has "myfriend" as the nick parameter, Snak will only apply the Action to that specific nick. If your friend sometimes uses the nick "myfriend[Work]" the Action will not be applied. In order to work around that use a wildcard. For example, use "myfriend*" to match both "myfriend" and "myfriend[Work]".
In order to make it easier to use, Snak will automatically add a "*" wildcard before and after a string in the message field if you haven't used any other wildcards directly. In order to avoid this you can put quotes around the text in the message field.

Variables and text substitution


Sometimes it is also useful to use text substitution. This means using a variable like $mynick in one of the parameters. When Snak determines if the Action applies it substitutes the current nickname instead of $mynick.

For example, if you want to respond to a greeting containing your nickname, enter "Hi $mynick" in the message field for the event. This also makes the Action continue to work when you change nick, or if you use a differenct nickname for each connection. However, if your nickname happens to contain a wildcard character like the three above the Action will probably not work.

The "$mynick" substitution is only active for the message field in the event part of the Action. There are other substitutions that are active for the response side and they are explained on the next page.

Setting up an action


To view the list of Actions, open the Actions panel with cmd-N. The leftmost column contains a checkmark that can be clicked to activate or deactivate the Action. Each action is listed with a descriptive text to allow you to easily see what each action does.
Press the Add button to open a dialog to set up an Action.
Events
The events that you can automatically respond to are:
• On any normal message
• On channel message
• On private message
• On notice
• On server notice
• On signon
• On signoff
• On join
• On join by self
• On opping
• On deopping
• On DCC chat offer
• On DCC filetransfer offer
• On DCC filetransfer done
• On DCC filetransfer fail

Event parameters


The parameter fields for the event support variable substitution. As explained on the previos page that means that you can use the following variable in the event strings:
• $mynick

On any normal message


Someone sent a channel message, a private message, a notice or a server message Parameters: Nick - the nick that sent the message. Message - the text of the message.

On channel message


Someone sent a message to the channel. Parameters: Channelname - the channel where message was sent. Nick - the nick that sent the message. Message - the text of the message.

On private message


Someone sent a private message to you. Parameters: Nick - the nick that sent the message. Message - the text of the message. Possible responses

On notice


Someone sent a notice message to you. Parameters: Nick - the nick that sent the message. Message - the text of the notice.

On server notice


The server sent a notice to you. Parameters: Message - the text of the notice

On join


Someone joined the channel. Parameters: Channel name - the channel where the join happened. Nick - the nick that just joined the channel.

On join by self


You joined a channel. Parameters: Channel name - the channel you just joined.

On opping


Someone was opped in the channel. Parameters: Channel name - the channel where the opping happened. Nick - the nick that was just opped.

On deopping


Someone was deopped in the channel. Parameters: Channel name - the channel where the deopping happened. Nick - the nick that was just deopped.

On signon


Someone from your contacts list on notify just signed on. Parameters: Nick - the nick that just signed on.

On signoff


Someone from your contacts list on notify just signed off. Parameters: Nick - the nick that just signed off.

On DCC chat offer


You received a DCC chat offer. Parameters: Nick - the nick that sent the offer.

On DCC filetransfer offer


You received a DCC filetransfer offer. Parameters: Nick - the nick that sent the offer. Filename - the name of the file that is being offered.

On DCC filetransfer done


A DCC filetransfer completed successfully. Parameters: Nick - the nick that sent the file. Filename - the name of the file that has been received.

On DCC filetransfer fail


A DCC filetransfer completed successfully. Parameters: Nick - the nick that sent the file. Filename - the name of the file that could not be received.

Responses


Each event has a preset list of supported responses which are appropriate to the event. If you find the need for a particular response that isn't currently supported, please let me know.
These are all the supported responses:
• Send public message
• Send notice
• Send private message
• Send notice to
• Send private message to
• Do whois
• Run command
• Op
• Deop
• Voice
• Unvoice
• Deop and kick opping nick
• Op and kick deoppping nick
• Kick
• Ban
• Highlight
• Ignore
• Redirect to
• Speak message
• Speak string
• Play sound
• Accept chat
• Accept file
• Open file

Response parameters


The parameter fields for the responses support variable substitution. That means that you can use the following variables in the response strings:
• $nick
• $userhost
• $channel
• $message
• $filename

Example:
If you want to have a spoken notification whenever someone joins a channel you can set up an Action to speak a string. The parameter to the Speak string response would then be "$nick just joined $channel".
ActionJoinSpeak

When Snak performs the response for this Action the $nick will be replaced by the nick that just joined the channel and $channel will be replaced by the channel name.

Not all variables make sense in all situations. In the above example, no message of any kind is involved in the the event, so if you were to use the $message variable in the string, nothing would happen. Likewise with the $filename variable, which is only functional in conjunction with the DCC events.
For events where the $message variable is supported you can also use the substring variables. If the message that you want to act on is in a known format, and you are only interested in certain parts of it you can refer to the individual words with numeric variables.

If the message is "one two three four", $0 would be "one", $1 is "two" etc. The numeric variables can be combined in a number of ways:
• $n Where n is a non-negative number, expands to the nth argument.
• $n-m Where n and m are positive numbers, expands to the nth thru mth arguments inclusive.
• $n- Where n is a positive number, expands from the nth argument to the end of the argument list.
• $-m Where m is a positive number, expands from the beginning of the argument list to the mth argument. This is the same as $0-m.
• $~ Expands to the last word on a line. 

That means, for example that you can refer to the second and third word of a message with "$1-2", and to the entire message, except for the first two words with "$2-"