Introduction

Xirc implements the KVirc Scripting language by Szymon Stefanek and the KVIrc Development Team. The version of the 'parser' implemented by Xirc was completely re-written in ObjectiveC using Foundation framework. Currently the Xirc scripts are compatible to the 95% with the KVIrc scripts.
The Xirc implementation doesn't support classes like C++.

The language was inspired by C++,sh,perl,php and mIrc scripting language implementations. It is a compromise between flexibility and speed, a 'workaround' for many intrinsic problems of an IRC-oriented scripting language.

Xirc scripting langauge allows you to:

• Implement automated reactions to the events generated by an IRC network
• Add new complex commands
• Add interface elements like popups and menus
• Add advanced interface elements like complete dialogs

The language contains all the common constructs of structured programming. You will find almost all the C control commands, sh/perl-like variables, arrays and and functions. Obviously you will also find most of the RFC1459 IRC commands and other tools to "play" with an IRC connection.

Scripts

You use XIS to implement scripts. A script is basically a finite list of XIS instructions. When you type a command in the Xirc input field you infact execute a small one-line script. You can store longer scripts in Xirc memory and execute them at later time. Scripts can be also read from external files by the means of the parse command.

Basic Syntax

A script contains a list of instructions separated by newlines or ';' characters. Placing an instruction per line does not require a terminating character, placing more instructions in a single line require them to be separated by ';'. The most common instructions in XIS are commands. A command is basically a keyword followed by a list of space separater parameters. The simplest (and the most useful) command in XIS is echo; it prints all its parameters to a Xirc window.
The following is an example of a valid script that uses only echo commands.

echo "This is the first line"

ECHO This is the second line;

echo "This is the third line"; echo This is still on the third line;

eChO "This is the fourth line"; Echo "This is still on the fourth line"

You have probably noticed that the terminating ';' character is optional when the command is the last in a line. The commands are case insensitive; 'echo' is equivalent to 'Echo', to 'ECHO' and to 'eChO'. In fact, most of Xirc is case insensitive. Another interesting thing is that when you execute the script you don't see the enclosing quotes around the printed text: more about this in the following sections.

Parameters processing

Most of the commands accept (and sometimes require) a list of parameters. For example, the join command (that is used to join an IRC channel) accepts two parameters: the first one is the channel to join and the second is the password. The simplified syntax for join is:

join <channel> [<password>]

The line above is an example of syntax specification. All the commands are described by such syntax lines. join is the command and it stands exactly for the literal string "join" typed in a script. <channel> is in angular parenthesis and rappresents a mandatory parameter: you must substitute a real channel name in its place otherwise the command will fail and Xirc will probably complain too. [password] is still a parameter but the square parentheses indicate that it is optional: if you specify it, then it will be interpreted as the channel password, if you don't then no password will be used.

You can finally join a channel by writing:

join #xirc xircpass

or , since #kvirc usually has no password , by writing:

join #xirc

In the example above the optional parameter [password] is omitted.

Parameters, spaces and quotes

From the examples above is obvious that XIS command parameters are separated by spaces. What is not totally obvious is that multiple spaces are allowed but Xirc will automatically reduce them to exactly one (just like HTML parsers or the shell interpreters do). This is an useful behaviour in an IRC client since spaces usually carry no information and in text oriented protocols make the parsing really harder (:D).

The spaces are simplified in normal processing but there are ways to force Xirc to interpret the spaces just as they are. The first method are the quotation marks: all the spaces enclosed in quotation marks will be preserved.

echo This   text    will    have    spaces    simmplified

echo But    "this    one    not"

The first example will print out with spaces simplified but the second not. The quotes are also a nice trick to embed spaces into a single parameter that would be obviously splitted in two or more.

echo Parameter1 Parameter2 "Parameter 3 ( with spaces )" Parameter4

By running the examples above you may have noticed that the spaces are preserved but the quotes are then stripped! Yes, this is another tricky behaviour. But don't be afraid: it is really easier to use than to explain. There is obviously a method to preserve the quotes too and it is also another method to preserve the spaces but that leads us to the next paragraph.

Command blocks

Commands can be 'grouped' in blocks by using the classic C braces. Here is a single line example:

{ echo First command; echo Second command; } echo Third command

Multi line example:

{

     echo First command

     echo Second command

}

echo Third command

Basic examples

Sum two values and store the result in the variable '%c'

%a = 1;

%b = 2;

%c = $(%a + %b);

echo The result is: %c;

You are able to execute complex operations like this:
Prints all odd number from 0 to 9!

for(%a = 0; %a < 10; %a++)

{

if(%a % 2 == 0) echo Even number: %a;

else echo Odd number: %a;

}

Returns the upper case string of string contained in the variable '%a'

%a = "How are you?";

echo %a --> $str.uppercase(%a);

Accessing the Xirc scripting context from perl

%pippo = test;

%Pluto = 12345;

perl.begin

$mypippo = Xirc::getLocal("pippo");

$mypippo =~s/^pi/ze/g;

$mypluto = Xirc::getGlobal("Pluto");

$mypluto =~ s/23/xx/g;

Xirc::setLocal("pippo",$mypluto);

Xirc::setGlobal("Pluto",$mypippo);

perl.end

echo "\%pippo is" %pippo;

echo "\%Pluto is" %Pluto;