Customizing your IRC Experience

jIRCii is a fully scriptable using the sleep language. Sleep is a simple language that slightly resembles perl. This document covers the jIRCii specificadditions to sleep. The Sleep 2.1 Manual provides full coverage of the features in sleep itself. You may want to read it before you read this. This document is written as a reference, it is not meant to serve as a full tutorial for scripting with jIRCii.

Also be sure to set debug(7) while you're writing your scripts. This will echo all errors opening files and such (checkError() stuff) and force you to declare your variables.

Loading and Unloading Scripts

The following commands are at your disposal for script loading and unloading.

/load filename.irc
Loads the specified script.

/unload filename.irc
Unloads the specified script, restoring any aliases/sets that were overridden by the specified script.

/reload filename.irc
Unloads and then reloads the specified script.

You can also use the script manager dialog. Click the View menu, Options, and then select Script Manager. The script manager dialog has options for loading and unloading scripts.

The script manager dialog has an option to "ignore script warnings". If you are developing a script you should never have this option checked. Often times script errors won't be caught when they are loaded. They are usually announced when the script is running

Aliases

An alias in jIRCii is a way of specifying a /command that when called it will execute a bunch of statements.

alias jf
{
  call("/join #mIRCScripts");
  call("/join #java");
}

The alias jf is for joining favorite channels. The keyword alias followed by jf declares jf as an alias. This means /jf is now a valid command in jIRCii.

Inside of jf the function call() is called with a string each time. Call executes the specificjIRCii command within the double quotes. Using call() is just like typing a command in the editbox. Custom aliases can also receive parameters.

alias j
{
  call("/join $1");
}

Aliases in jIRCii can receive parameters. The first parameter is the scalar $1. The second parameter is the scalar $2. The third is $3 etc.. The name of the alias is $0. The above alias is a shortcut for the join command. If you type /j #floods, $1 in the above alias would have the value of #floods.

The " double quoted string inside of call is known as a parsed literal. It is basically a string where $scalar values are evaluated. See the sleep language fundamentals document for more about parsed literals and scalars.

Built in Variables

jIRCii supports a number of built in variables that are always ready to use. Whenever an alias is typed in you immediately have everything broken down for you. For example say a user types: /blah hello ice cream!

Immediately you have the $n variables available to you were n is an integer or a range of integers. For example:

This is different than sleep subroutines where the arguments are numbered from 1..n These tokenized ranges do not work in sleep subroutines. In general parameters to events, menus, aliases, and sets are passed in the tokenized form described above.

jIRCii also supports some other built in variables. These are available all the time.

Keyboard Shortcuts

In jIRCii nearly any key combination can be bound to execute a script when pressed. This is accomplished using the bind keyword.

bind Escape
{
   call("/part $active");
}

The above binds the "Escape" key to part the active channel when pressed. Whenever someone presses escape call("/part $active") will be executed.

The format for specifying binds is:

bind Modifier+Key { commands }

The Modifier+ part is optional. You can just bind a Key.

Key Constants

Modifiers: Shift, Ctrl, Alt, Meta

Keys:

Also acceptable is A-Z, a-z, 0-9, and anything else. The above table is just a list of special self- explanatory constants for common keys you might want to bind.

Responding to Events

An event is a specifically defined occurrence. Examples of events include a user joining a channel, a dcc send completing, and even a window closing. It is possible to write scripts that respond to events when they occur. This is accomplished using the on keyword.

on event { commands }

The syntax is pretty simple: on the occurrence of some event execute these commands. Whenever the specified event occurs the commands in the { } curly braces will be executed. When an event finishes executing you can use the halt keyword to stop jIRCii scripts from further processing that event. The halt keyword works for most events. Halt has the same syntax as return except you can't return anything with a halt.

# taken from "save the children script"
on public
{
   if ("*swear*word* iswm $parms)
   {
      halt;
   }
}

The above example halts any public channel text that is a wildcard match for *swear*word*. When halt is used the event will not be processed any further and no sets will be fired.

List of Events

* = event has a special variable associated with it.
+ = event has a note associated with it.

DCC Events

GUI Events

IRC Events

Event Variables

The variables listed in the Aliases -> Built in Variables section also applies to sets as well. Generally $0 is the target/source/focus of the event. $1- is the rest of the parameters.

Temporary Events

Along with normal event listeners jIRCii also features the ability to bind temporary event listeners. Temporary event listeners are for responding to an irc event once and thats it. Temporary events are fired before normal event listeners. Temporary events can also be halted stopping the normal event listeners from processing the event.

Temporary events are bound using the wait keyword.

wait event { commands }

Temporary events can be declared nearly any where.

alias j
{
   if ($1 eq "#floods")
   {
      call("/msg JakieChan dude, what is the key to #floods?");
      wait privmsg
      {
         call("/join #floods $1");
      }
   }
   else
   {
      call("/join $1-");
   }
}

In the above example the alias j is declared. The alias checks to see if I'm trying to join the channel #floods. If I am it messages a friend of mine asking for the key. When he responds (presumably with the key), jIRCii joins the channel.

Event specific variables from when the temp listeners was declared are not carried over to temporary events. They have there own set of variables just like any other event. Nothing inside of the { } curly braces is evaluated until the event occurs. As such watch out for using variables outside of a wait command and then expecting it to be available or be the same thing inside of it.

Filtered Events

Generally when you declare an event listener it is not very descriptive. You state the event name and that is all the discretion you get. To get more specificyou can specify a filter string with your events. i.e.

wait event "*source* *target* *parameters*" { commands }

An event filter string contains 3 wildcard strings separated by spaces. When an event occurs jIRCii will check the first wildcard against the source of the event meaning the nickname/server that originated the event. The second wildcard is checked against the target of the event i.e. who the event affects. The third wildcard is checked against the event parameters. If you don't care about a particular part of the filter string just specify a * which means match anything.

alias j
{
   if ($1 eq "#floods")
   {
      call("/msg JakieChan dude, what is the key to #floods?");
      wait msg "JakieChan $me *"
      {
         call("/join #floods $1");
      }
   }
   else
   {
      call("/join $1-");
   }
}

The above example is similar to our original example for temporary events. Except this time when a message happens our temporary listener will only be fired for a msg event originating from JakieChan sent to $me. The filter string is evaluated when you declare the event. Once the wait msg "filter" is declared the $variable's are immediately resolved. In the above example, if you change your nick before JakieChan messages you the temporary event won't trigger.

Descriptive Events

Descriptive events are similar to filtered events in the respect that they let you better describe the event you are looking for. To declare a descriptive event listener:

wait (comparison) { commands }

The above will declare a temporary listener that will be fired only when the comparison following the wait keyword is true. Think of the comparison part as being similar to an if statement. When an event occurs the event is checked against the specifiedcomparison to see if the event matches that description or not. If it does then the event is fired. If it doesn't the event is not fired. Descriptive events work with both normal events (on keyword) and temporary events (wait keyword). Descriptive events only work for events originating from the IRC server. Most GUI events and such won't fire under descriptive events.

alias j
{
   if ($1 eq "#floods")
   {
      call("/msg JakieChan dude, what is the key to #floods?");
      wait ($event eq "PRIVMSG" && $nick eq "JakieChan")
      {
         call("/join #floods $1");
      }
   }
   else
   {
      call("/join $1-");
   }
}

Beating an example to death this example is the same thing as the previous two examples. One difference though: the comparison is re-evaluated each time the event is checked. Variables specific to the original event do not carry over to the comparison.

Hacking Event Listeners

Note: The mechanism described in this section is more or less a hack. It is only documented as it may be useful to scripter's working on more advanced functionality.

One downfall of the temporary event mechanism is you don't get a lot of control. Basically you can register an event listener and once it is fired it is done. This is simple to use and good for some cases such as capturing the server reply of a /USERHOST request. However it is not usable for things like doing a /WHO, capturing all of the output from the server, and when the server sends the end of who reply removing the temporary event listener.

The following example shows how to get this type of functionality:

alias tempevent
{
   on ($event eq "315" || $event eq "352")
   {
      if ($event eq "352")
      {
         # process /who output
         echo("Caught /who: $1-");
         halt;
      }
      if ($numeric eq "315")
      {
         return 6; # halt and remove this event listener
      }
   }
   call("/who $1");
}

The above snippet creates an alias tempevent. When /tempevent is executed a descriptive event is registered. This descriptive event fires when a numeric reply 352 (/who data) or a numeric reply 315 (end of /who data) is received from the server.

If the event is the /who output we just choose to process it. If the event is the end of the /who data we then return a value that tells jIRCii we want to deregister the listener (4) and halt the event (2).

Internally jIRCii processes event listeners based on their return value. Avalue of 4 means remove the event listener. A return value of 2 means halt the event. Areturn value of 1 means continue processing other events. Returning 5 (1 + 4) means continue processing other events but remove this listener. Returning 6 (2 + 4) means halt processing of other events and remove this listener. This form of event hacking is only effective on irc server related events. Other events such as gui events are processed differently.

Scripted Sets

A popular feature of scripts in the past was a built in theme system. A theme system allowed scripters to customize any echo inside the script without altering the functionality of the scripts features. jIRCii has a built in theme system that is accomplished with scripted sets. Nearly every echo event that is echoed to the screen is defined in a scripted set. Altering these sets allows you to change the way jIRCii looks completely without altering the functionality of jIRCii.

The basic format of a set is:

set SET_NAME { return "formatted echo"; }

It is of course possible to use if statements, call functions, and anything else within a set. The important thing is that the set returns a string that formats the data from an event into something presentable (preferably cool looking).

A set that returns nothing will simply not be echoed. It is possible to disable an echo for a set by having the set return nothing.

Time Stamping

If time stamping is enabled the set TIMESTAMP is automatically attached to the beginning of all of your set output. To disable time stamping for a specificset append an ! exclamation point to the set name.

set NOTIFY_SIGNON! { return "*** $nick has signed on at $time"; }

In the above set for a notify signon we already have the time in the echo. There is no point in adding a timestamp even if time stamping is enabled. Adding the ! exclamation point disables time stamping for that specific set.

List of Sets

* = set has a special variable associated with it.
+ = set has a note associated with it.

Channel Event Sets

Channel Information Sets

DCC Sets *

Messages Received

Miscellaneous Sets

Other Events

Send Messages

Event Variables

If a set is in response to an irc event then $variable's available to the event will also be available to the set.

The variables listed in the Aliases -> Built in Variables section also applies to sets as well. Generally $0 is the target/source of the set event. $1- are the rest of the parameters.

Menus

In jIRCii it is possible to script menus for most places in the client. Popup menus are made visible by right clicking in a popup menu hotspot. The popup menu hotspots in jIRCii are background, channel, dcc, input, list, nicklist, query, status, switchbar, and tab.

The background hotspot refers to the background when jIRCii is using an MDI based interface. The tab hotspot refers to the server tab for a specificserver connection. The input hotspot refers to the editbox in jIRCii windows. The list hotspot refers to the /list dialog. The switchbar hotspot refers to the buttons in the window switchbar.

To setup a popup menu for a hotspot you use the menu keyword:

menu hotspot
{
   item "item title" { commands }
   menu "menu title" { commands; more item/menu declarations }
}

Within the menu keyword you can use the menu keyword again to create a submenu. You can also use the item keyword followed by a title to add an item to the menu. Menus in jIRCii are all created dynamically. That is each time a popup menu is to be shown the menu scripts are executed. Submenu scripts are not executed until they are clicked on. Item scripts are not executed until they are clicked on.

The function addSeparator() can be used inside of the menu keyword to insert a separator in the menu.

The function addItem("item title", "/command args") can be used to quickly add an item to a menu.

To add a menu to the nicklist:

menu nicklist
{
   item "Whois" { call("/whois $1"); }
   item "Query" { call("/query $1"); }
}

In the above example two menu items are added to the nicklist hotspot. These are "Whois" and "Query". Whenever "Whois" is clicked on the script inside the { } curly braces will be evaluated. In this case it is call("/whois $1"). In nicklist menus $1 and $snick refer to the nickname that is currently highlighted. $0 represents the current channel. $2- represents the nicknames of the other highlighted nicknames.

When a menu item declared with the keyword item is executed the local variable $command is available. $command contains the item label for the executed menu item. The commands declared inside of a menu or item block are only executed when that menu or item is activated. Local variables declared outside of a menu or item block are not available when they are executed.

Using the menu keyword with a menu hotspot does not erase the menus currently in place. It just adds your menu items to the hotspot along with other menu items already there.

Menubar Menus

Menubar menus can be scripted in jIRCii as well. In fact menubar menus work almost the same as popup menus. The difference is you use the menubar keyword to add an item to the menubar.

menubar "menu title"
{
   item "item title" { commands }
   menu "menu title" { commands; more item/menu declarations }
}

If a menu title already exists in the menubar then the menu will be combined with the already existing menu. If a menu title does not exist then the menu is added to the menubar right before the Window and Help menu items. You can add to the Window and Help menus using "&Window" or "&Help" for the menu title.

Menubar menus are dynamic just like popup menus. Every time the "menu title" is shown the items and submenus are dynamically added.

The function refreshMenubar() can be used to refresh the top-level menubar.

Adding a Mnemonic

You can use the & ampersand character in "item title" and "menu title" to set a mnemonic for the menu item. The focus accelerated character will be underlined. Users of your script can then use their platform specifickeyboard combination to access your menu item when the item's parent menu is showing. In Windows this combination is Alt+(focus accelerator).

Built-in Client Resources

jIRCii has a number of bundled "resource" files that make up the jIRCii experience. These include images that define the toolbar, the window icons, and even the jIRCii logo. Copies of all of these files are contained within the jerk.jar file (which is just a ZIP compressed archive).

To override a jIRCii built-in "resource" with one of your own, simply create your resource and copy it to the .jIRC directory on your computer where jIRCii is keeping all of your settings. For example default.irc is the default script the drives jIRCii. To override the internal version of this resource:

1. create your own version or edits to default.irc
2. copy it to your .jIRC folder (on Linux, OS X /home/<your user>/.jIRC, on Windows c:\documents and settings\<your user>\.jIRC)
3. restart jIRCii

When loading a resource jIRCii looks in the .jIRC folder first before using its own internal version of the resource.

Editing the Default Scripts

Internally jIRCii has two scripts loaded. default.irc and menus.irc default.irc contains all of the default sets and a few features for jIRCii. menus.irc contains all of the popup and menubar menus within the client.

Copies of these two files are distributed with jIRCii under the extras/ directory in the jIRCii archive. The real versions of the default scripts are contained inside of the jerk.jar file.

It is possible to force jIRCii to load modified versions of menus.irc and/or default.irc. Simply modify the copies of default.irc and menus.irc and save the modifications to the jIRCii settings directory. On UNIX the jIRCii settings directory is located in your home directory under .jIRC. In Windows the jIRCii settings directory is located in something like c:\documents and settings\your-username\.jIRC\.

When jIRCii tries to load default.irc or menus.irc it will first look in the .jIRC directory before looking in the jerk.jar file.

If you are creating a "full script" and want to disable the loading of default.irc and menus.irc there are two internal properties "load.default" and "load.menus". These two internal properties can be set to true or false to enable or disable the loading of the default.irc or menus.irc file. To set internal properties look up the setProperty() function.

Generally any .irc file loaded takes precedence over anything in the default.irc and menus.irc. It should be possible to write full featured scripts without disabling the two internal scripts. However if you need to do it now you know how.

Built in Functions and Operators

Conventions

$ add(@array, $scalar, [index])

The $ to the left of the function name represents the return type of the function. Some functions will return an array (@), some a hash (%), and others a scalar ($). Functions marked with (?) will return 1 if the value is true or the empty scalar if the value is false. Functions that have no return value will have nothing to the left.

Optional parameters will be enclosed in [ ] square brackets.

Channel Functions

jIRCii supports the following comparison operators for use in if statements with regards to channels:

jIRCii provides the following functions for retrieving channel information:

Colormap Functions

These functions are provided for manipulating the jIRCii colormap. jIRCii allows colors 17-99 to be user defined as any color the user wants. These colors are saved in the colormap.

The "aarrggbb" format is a hexadecimal format for specifying a color. Similar to what you would use for specifying a color on a webpage. The one caveat is rather than saving this number in hex form jIRCii deals with colors as integers.

To convert a number from a hex triplet to the aarrggbb format try: formatNumber(hex triplet, 16, 10)

Config System Functions

The following functions are used to interface with jIRCii's user preferences sub-system. All user preferences are stored using this system. These functions make it possible to test for any user preference or change any user preference. jIRCii preferences are generally stored in a file called jirc.prop in the .jIRC folder located in the users home folder.

The configsystem supports the following comparisons for user within if statements

The following functions are provided for interfacing with the config system:

Setting a property via the setProperty() or setPropertyList() methods will generally take immediate effect in the client. The stuff being configured in jIRCii is wired to know when its property gets changed. For a list of *some* of the properties you can change see Appendix A- Client Configuration Variables.

Date/Time Functions

In general dates are represented using a scalar long that holds the number of milliseconds since the epoch. The epoch is January 1st, 1970. Some of the functions for date/time manipulation require a scalar long as a parameter. That parameter is represented as date without any " quotes.

jIRCii provides the following functions for date/time manipulation:

DCC Functions

Many of the dcc functions return a $scalar that contains a reference to the dcc connection information. This reference can be queried using functions that take a $dcc_connection as a parameter. Its helpful to know that DCC's come in three varieties: CHAT, RECEIVE, SEND. DCC's can be in one of three states: CLOSED, OPEN, or WAIT.

jIRCii provides the following comparison operator for use in if statements with regards to DCC's:

jIRCii provides the following functions for getting information about the current DCC's:

Send and Get Specific

Get Specific

Send Specific

Dialog Functions

Echo Functions

GUI Functions

The string "window" refers to the name of a window you want to access. The Status window has a special name: %STATUS%.

jIRCii provides the following comparison operator for use in if statements with regards to its UI:

jIRCii provides the following functions for manipulating its user interface:

GUI General

Individual Windows

Window Management

IRC Command Functions

Internal Data List

The internal data list in jIRCii stores all of the channel and address information for users. jIRCii supports the following comparison operator for use in if statements with regards to the internal data list:

The following functions are also available:

Logger Functions

The following functions are provided for querying and accessing the jIRCii built-in logging functionality.

Multiserver Session Manipulation

The following functions are provided for manipulating the multiserver aspect of jIRCii. Each session in jIRCii has a session id. The first session is 0, the second is 1, etc. Most of these functions are related to manipulating the tab for the session in jIRCiis UI.

Notify Functions

The notify feature in jIRCii works much like an instant messaging buddy list. It tells you when someone is online or not.

jIRCii provides the following comparison operators for use in if statements with regard to the notify list.

jIRCii provides the following functions for accessing the notify list:

Servers.ini Functions

The file servers.ini is used by jIRCii to keep track of irc servers the user may want to connect to. The following functions are used for accessing this list of servers. The functions that return arrays return read-only arrays.

Sound Functions

String Formatting Codes

Sleep has a feature called parsed literals. Parsed literals are strings contained inside of double quotes. A feature of parsed literals is that certain escapes can be applied. An escape is started with a \ backslash and followed by a character. Sleep replaces some escapes with a specifictype of text. jIRCii uses this feature of sleep to make it easy to insert text formatting codes into your scripts. A \ backslash followed by a \ backslash is just a backslash.

The \b escape is equivalent to using Ctrl+B, \c is equivalent to using Ctrl+K etc. Also in jIRCii bold is a brighter version of the current color while reverse is a darker version of the current color.

Remember these escapes only work within double quoted strings

String Functions (Miscellaneous)

String Functions (Tokenizing)

jIRCii features a powerful built in string tokenizer. Strings are tokenized using the tokenize() function. A tokenized string is a string that is split up into parts (called tokens) by a specified delimiter. The return value of the tokenize function is referred to as $tokens.

jIRCii supports the following comparison operator for working with tokenized strings: string istoken $tokens true if string is a token inside of the tokenized string

The following functions exist for working with tokenized strings:

Timers

A timer in jIRCii is a way of executing a set of commands when a certain interval of time has passed.

Client Configuration Variables

This list is by no means a comprehensive list of all the configuration variables within jIRCii. The best thing to do is view the file jirc.prop after youve played around with the options for awhile. All configoptions in jIRCii have default values. These default values are not automatically saved to the configfile.

You can set these values from within jIRCii using: /eval setProperty(property, value)