Auto Actions

Auto Actions are a powerful feature that Foo IRC provides to allow users to have more control over there IRC session by providing some functionality only seen in desktop IRC applications like mIRC. Auto Actions are constructed using a language that shares similar syntax to some of the most popular programming languages. This document provides all the information needed in order to use and understand this language.

Changes in v3.7.0

Operator '+' now works to join two arrays.
Operator '-' now works to diff arrays and strings.

Changes in v3.5.1

unset can now be used on array items.

Changes in v3.0.5

Bug fixes.

Changes in v3.0

Arrays are now ordered maps which means the index (key) can now be a string.
IRC commands can now be used directly in a script by starting a line with /< the command name >

Changes in v2.7

Added the ability to prioritize actions added to a action stream.

Changes in v2.5

Support for '-' (negative sign) for negative numbers.
Improved support for the '!' (not) operator
Math expression fixes.

Changes in v2.2.1.2:

Added support for single line comments (// comment text).
Fixed line number counts

Changes in v2.2.1:

Added support for comments (/* comment text */) and the ! (not) operator.
Fix for setting and retrieving array values.

Action Groups

Action groups are similar to classes of programming languages. Groups provide a way to combine actions into a single scope that they can be called from and share data with.

Below is an example definition of a group with no action:

MyGroup {

}

Actions

Actions are similar to functions or methods of programming languages. An action can be called directly from another action or it can be triggered by an event. All actions must be placed in an action group and be uniquely named in that action group.

Creating an Action

An action can be defined as follows:

MyGroup {

    action MyAction(parameter1, parameter2) {

    }

}

This action is named MyAction and has two named parameters, parameter1 and parameter2. The name of an action can only have numbers, letters, and underscores. Actions can have zero or more parameters which can be access by commands inside the body of the action.

Auto Run Actions

If actions exist in an action group with the names Init or ServerInit, these actions will be automatically triggered. These actions are not required to be in action groups. The triggering of these actions are not associated with any stream, and may not have certain reserved variables available for use.

Init()

Triggered when the action group that holds this action is first added to the system.

ServerInit()

Triggered when a server is added to the system.

Commands

Commands can be placed in the body of an action and are run whenever the action is called. They can consist of variable assignments, action calls, and arithmetic. Each command must be separated by and end with semicolons unless it is a block.

Variables

Scope

Variables can be set and accessed from various scope levels which control how variables are shared between different actions. Variables can be set in the following scopes:

local (default) Variables set in the local scope are only accessible in the current block (i.e. inside the closest surrounding parentheses). If a scope is not explicitly given, the local scope is used by default. When attempting to access a local variable, if it does not exist in the current block, the variable will be looked up in parent scope, down to the group scope.

group The variable is accessible by all actions a part of this action group. These are treated similar to static variables of some programming languages.

global The variable is accessible by all action groups.

server The variable is accessible to all actions running on the current server running this action.

To set or access a variable from a particular scope, the variable can be accessed in the form [scope].[variableName].

Ex:

global.myVar

Declaring Variables

A variable must be declared before it can be assigned or accessed. Variables can be declared as follows:

set group.myVar;

The type of a variable is determined dynamically and can be an integer, double, string, or an array. The name of a variable can contain numbers, letters, and underscores, but it cannot start with a number. To unset a variable, use unset instead of set.

unset group.myVar;
unset group.myVarArr[1];

Assigning Variables

A variable can be assigned as follows:

[scope].[variable name] = [expression];

Only variables that have already been declared can be assigned. If no scope is given, the local scope is used by default.

Reserved Variables

Reserved variables can only be accessed in a read-only manner. Variables names starting with r_ are reserved variables and cannot be declared or assigned by the user.

See the Registering Auto Actions section to see some examples of reserved variables that are used.

Reserved Server Variable

r_serverHostname: The hostname entered by the user to connect to this server.

r_serverRealHostname: The hostname reported by the connected

r_serverName: The name of the server reported by the server.

r_nickname: The users current nickname.

r_settingsGuid: The guid used for this server in the saved server settings.

r_guid: The guid used to uniquely identify this server connection.

Arrays

An array is a ordered map variable that can hold multiple key/value pairs. The value at each key of an array can be retrieved or assigned just like regular variables. The following is an example of declaring and assigning an array:

set myArray[];

myArray[0] = 1;

myArray[1] = 2;

myArray["two"] = 3;

Values

The types of values are dynamically determined and supported in the form of Booleans, Integers/Doubles, or Strings.

Boolean: true or false

Integer/Double: -1.7976931348623157E+308 to 1.7976931348623157E+308

String: Begin and end with quotation marks

Calling Actions

An action can be called by another action using the following form:

[group name].[action name]([parameter 1, , parameter N])

[group name] is the name of the action group, [action name] is the name of the action name, and [parameter 1, , parameter N] is comma separated parameters. If calling an action from the same action group, then the action group is implied is does not need to be given. An action call can be placed anywhere in a command except as an assignable variable in an assignment.

Operators

Operators can be used to perform specific arithmetic, relational, or logical operations on values to get a result. The following operators are supported.

[value 1] [operator] [value 2]

Arithmetic

+ : Numeric addition, String concatenation, array joining

- : Numeric subtraction, string substring removal, array diffing

/ : Numeric division

* : Numeric multiplication

Relational

== : Equals

!= : Not equal

< : Numeric less than

<= : Numeric less than or equal to

> : Numeric greater than

>= : Numeric greater than or equal to

Logical

| : Boolean or

& : Boolean and

! : Boolean not

Returning Values

An action can return a value using the return keyword. When a value is returned, the value takes the place of where the action was called. Once a return is reached in an action, no other commands in the current action are run and the action that called it continues where it left off.

return [expression];

IRC Style Commands

IRC commands can be used directly in Auto Action scripts in the same form they are normally sent to an IRC server. This follows the form /< IRC command > < parameters >. The full line will be consider the command unless the command contains a non-conditional block.

Non-Conditional Blocks

A block is a section of code that starts with an open brace '{' and ends with a close brace '}'. While it is a necessary part of actions and control flow statements, a block can also be used standalone anywhere inside an action and can contain any code that is typically allowed within an action, including other blocks. These standalone blocks are called non-conditional blocks.

Control Flow Statements

While

Structure of a while statement:

While ([condition]) {
    [commands];
}

While statements can be used to run commands in the block of a while statement as long as the condition is true. The condition must be an expression that results in a Boolean value. Be careful to make sure the condition eventually becomes false, otherwise the commands may continue to be run until the system is terminated.

Conditionals

Structure of conditionals:

if ([condition]) {
    [commands];
}
else if ([condition]) {
    [commands];
}
else {
    [commands];
}

Conditionals allow control over running a block of commands based on a Boolean condition. A conditional starts with an if statement. If the condition of the if statement is true, the commands in its block are run. Otherwise, flow control moves to the next conditional statement if there is one. The next conditional can be an else if or else. An else if acts the same as an if and must be following an if or another else if. An else is the last conditional and its commands are always run if no previous conditions were met.

Registering Auto Actions

The primary feature of Auto Actions is the ability to register actions to be triggered by events in the application. See Actions.Register(). Actions can be registered to run in response to server events which are differentiated by the message channel (stream) on which an event has occurred. Each stream provides access to certain reserved variables which are accessible from the local scope that provides information about the event.

When an event occurs on a stream, by default, all Actions registered on a stream for an event are run sequentially based on the priority set on the Actions. Priorities are integer values in which lower values take precedence. An Action can prevent all Actions scheduled after it for an event from running by returning the string value "ABORT".

SERVER Stream

Generally, the SERVER stream receives events that would typically be shown on a servers console. Event codes for these events usually are numeric.

The following are reserved variables used by the SERVER stream:

r_stream: The name of the stream.

r_raw: The full text of the event.

r_eventCode: The event code this action is registered to.

r_serverName: The server hostname used to connect to this server.

r_0 - r_2: Data specific to this event.

USER Stream

Generally, the USER stream receives events that would typically be shown on a channel view.

The following are reserved variables used by the USER stream:

r_stream: The name of the stream.

r_raw: The full text of the event.

r_eventCode: The event code this action is registered to.

r_serverName: The server hostname used to connect to this server.

r_0 - r_4: Data specific to this event.

RAW_IN Stream

The RAW_IN stream receives all messages already processed by the SERVER and USER streams, messages not processed by those streams, and server connection events.

The following are reserved variables used by the RAW_IN stream:

r_stream: The name of the stream.

r_raw: The full text of the event.

r_eventCode: The event code this action is registered to.

r_serverName: The server hostname used to connect to this server.

DCC_IN

The DCC_IN stream receives all messages and connection events received by the client during a DCC Chat session.

The following are reserved variables used by the DCC_IN stream:

r_stream: The name of the stream.

r_raw: The full text of the event.

r_eventCode: The event code this action is registered to.

r_sourceServer: The IRC Server that was used to establish the DCC session.

r_remoteIp: The IP or hostname of the DCC partner.

r_remoteNickname: The nickname of the DCC partner which is used on the IRC Server that was used to establish the DCC session.

r_port: The port used on the host of the DCC session.

OUT Stream

The OUT stream receives user input and directed messages from a servers console, private message views, channel views, and some backend calls. The OUT stream is geared toward output that will be sent to the server.

The following are reserved variables used by the USER stream:

r_stream: The name of the stream.

r_text: The full text of the event.

r_eventCode: The event code this action is registered to.

r_serverName: The server hostname used to connect to this server.

r_channelName: If this event was triggered by user input from a channel view, this will be the name of the channel.

r_userName: If this event was triggered by user input from a private message view, this will be the name of the user view is dedicated to.

DCC_OUT Stream

The DCC_OUT stream receives user input and directed messages from DCC Chat. The DCC_OUT stream is geared toward output that will be sent to the DCC partner.

The following are reserved variables used by the USER stream:

r_stream: The name of the stream.

r_text: The full text of the event.

r_eventCode: The event code this action is registered to.

r_sourceServer: The IRC Server that was used to establish the DCC session.

r_remoteIp: The IP or hostname of the DCC partner.

r_remoteNickname: The nickname of the DCC partner which is used on the IRC Server that was used to establish the DCC session.

r_port: The port used on the host of the DCC session.

KEY Stream

The KEY stream receives keyboard hot-keys inserted by the user of client.

The following are reserved variables used by the KEY stream:

r_stream: The name of the stream.

r_eventCode: The hot-key code this action is registered to.

r_serverName: The server hostname used to connect to this server.

r_channelName: If this event was triggered by hot-keys entered on a channel view, this will be the name of the channel.

r_userName: If this event was triggered by hot-keys entered on a private message view, this will be the name of the user view is dedicated to.

Keywords

Stream

FooIRC has four streams where actions can be triggered in response to events.

SERVER: Receives numeric replies, server ping requests, server pong responses, and server errors.

USER: Receives join, quits, channel messages, topic changes, kicks, etc.

RAW_IN: Receives server messages not caught by the SERVER or USER streams, and status events.

DCC_IN: Receives messages from DCC Chat connections.

OUT: Receives all messages entered in message boxes for IRC Servers by the user and OUT targeted messages.

DCC_OUT: Receives all messages entered in message boxes for DCC Chat by the user and OUT targeted messages.

KEY: Receives keyboard input on the UI.

Target

Specifies what type of auto actions will be affected on a stream.

NATIVE: Auto actions that are already built into Foo IRC.

CUSTOM: Auto actions written by the user.

ALIAS: Auto actions written created by aliases.

ALL: Both native and custom auto actions.

THIS: The action that is currently running.

Context Target

Specifies the context menu target.

SERVERS: Context menu that shows when right-clicking a server name in the server list.

CHANNELS: Context menu that shows when right-clicking a channel name or other view in the channel list.

USERS: Context menu that shows when right-clicking a nickname in the user list of a channel.

Event Codes

SERVER Stream

001-999: Numeric codes. This page outlines what each numeric code means.

AUTHENTICATE, PING, PONG, ERROR

USER Stream Events

JOIN, PART, PRIVMSG, etc. See List of Events for more event codes.

DCC_IN Stream Events

CONNECTIONATTEMPTSTARTED: The client has attempted to open a connection to the DCC partner.

CONNECTIONESTABLISHED: A socket connection with the DCC partner is open.

CONNECTIONREADY: The connection is ready to receive messages.

FORCEDDISCONNECTION: The user has requested to disconnect from the DCC partner.

MESSAGE: A message from the DCC partner.

RECONNECTIONPROCESSSTARTED: The client has began the process to reconnect to the DCC partner after an unexpected disconnection.

SSLCERTIFICATEERROR: The DCC connection was aborted due to a certificate error.

UNEXPECTEDCONNECTIONLOST: The client has been disconnected from the DCC partner unexpectedly.

HOSTSERVERABORTED: The client has closed the server for hosting a DCC connection.

HOSTATTEMPTABORTED: The client could not open a server for hosting a DCC connection.

LISTENINGSTARTED: The client is listening for DCC connections.

RAW_IN Stream Events

CONNECTIONATTEMPTSTARTED: The client has attempted to open a connection to the IRC server.

CONNECTIONESTABLISHED: A socket connection with the IRC server is open.

CONNECTIONREADY: The server is ready to receive commands.

FORCEDDISCONNECTION: The user has requested to disconnect from the server.

LEFTOVERMESSAGE: A message from the server that is not recognized as a SERVER or USER stream event.

CAPTUREDMESSAGE: A message from the server that is recognized as a SERVER or USER stream event.

RECONNECTIONPROCESSSTARTED: The client has began the process to reconnect to the server after an unexpected disconnection.

SSLCERTIFICATEERROR: The server connection was aborted due to a certificate error.

UNEXPECTEDCONNECTIONLOST: The client has been disconnected from the server unexpectedly.

OUT Stream Events

If the OUT streams receives a message beginning with a '/', (e.g. "/post hello sir"), the word directly next to the '/' will be used as the event code (e.g. "POST" in the previous example). If the message does not begin with a '/', then NONE will be the event code.

DCC_OUT Stream Events

If the DCC_OUT streams receives a message beginning with a '/', (e.g. "/post hello sir"), the word directly next to the '/' will be used as the event code (e.g. "POST" in the previous example). If the message does not begin with a '/', then NONE will be the event code.

KEY Stream Events

The KEY streams captures keyboard combinations the UI receives with modifiers keys held at the same time other keys are held. Supported modifiers keys are CONTROL, MENU (alt), and SHIFT. For example, to capture a user pressing CTRL, A, and B keys down, CONTROL+A+B would be the event code.

Supported Keys: LeftButton, RightButton, Cancel, MiddleButton, XButton1, XButton2, Back, Tab, Clear, Enter, Shift, Control, Menu, Pause, CapitalLock, Kana, Hangul, Junja, Final, Hanja, Kanji, Escape, Convert, NonConvert, Accept, ModeChange, Space, PageUp, PageDown, End, Home, Left, Up, Right, Down, Select, Print, Execute, Snapshot, Insert, Delete, Help, Number0, Number1, Number2, Number3, Number4, Number5, Number6, Number7, Number8, Number9, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, LeftWindows, RightWindows, Application, Sleep, NumberPad0, NumberPad1, NumberPad2, NumberPad3, NumberPad4, NumberPad5, NumberPad6, NumberPad7, NumberPad8, NumberPad9, Multiply, Add, Separator, Subtract, Decimal, Divide, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24, NumberKeyLock, Scroll, LeftShift, RightShift, LeftControl, RightControl, LeftMenu, RightMenu, GoBack, GoForward, Refresh, Stop, Search, Favorites, GoHome

Settings

Certain settings can be accessed and modified using the System action group.

General Server Settings

Servers, ServerName, Default_Nickname, Default_Port, Default_Username, Default_EnableIdent, Default_EnableAutoPing, Default_UseSSL, Default_UseSASL, Default_RejoinOnDisconnect, Default_QuitMessage, Default_PartMessage, Default_EnableOnConnectCommands, Default_OnConnectCommands, Default_Encoding, Default_AutoConnectOnStart, Default_IgnoreCertificateErrors

General Settings

TimestampFormat, ConnectionRetryAttempts, ConnectionRetryIntervals, EnableServerLogging, LoggingFolder, EnableDebugLogging, LogChannels, LogConsoles, LogQueries, EnableVersionReply, EnablePingReply, savedServerReuseViews, SeparateLogsByDate, UseIdentInDisplayName

Server Settings

Guid, Nickname, Name, NickservUsername, ServerHostname, ServerPassword, NickservPassword, Port, Username, EnableIdent, UseSSL, UseSASL, EnableAutoPing, RejoinOnDisconnect, SavedChannels, AutoJoinChannels, IgnoreList, QuitMessage, PartMessage, EnableOnConnectCommands, OnConnectCommands, Encoding, AutoConnectOnStart, IgnoreCertificateErrors

DCC Settings

SendBlockSize, MaxReceiveFileSize, ReceiveFileNameCollisionAction, HostConnectionTimeout, DefaultHostAddress, RandomizePorts, UseSendAhead, IgnoreDccChatRequests, UseDefaultAddress, IgnoreDccSendRequests, AutoAcceptChatRequests, AutoAcceptSendRequests, UseOldTurboDccHandshake, DefaultSaveLocation, UseDefaultSaveLocation, UseHostAddressFromIrcServer, MinHostPort, MaxHostPort, MaxDccSessions, MaxDccTransfers

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search