AdiIRC

h1. Notice: this is info for 1.8.8 and higher.

h1. Scripting

In the latest beta's, I am experimenting with a little more advanced scripting features and I will use this wiki to track progress and features.

Syntax, variables and functions will probably change a lot, so don't except previous scripts to still work in the next beta and so forth.

There are 2 types of scripting at the moment, one that have been here for a long time, and a new system.

All scripting is done in Commands -> Edit Commands where one line represent a script or a custom command and its trigger is one of 3 ways:

/something<whitespace> 

keys<whitespace>

OnEvent<whitespace>

Please note that variables and functions are *different* for these 2 types of scripts.

You can comment out a command by putting a # in front of it.

h1. Normal custom commands:

<pre>Syntax = /something<whitespace>/somethingelse</pre>

Here are some variables which can be used in Custom Commands, its like creating aliases of already available commands, e.g <pre>/hi /me says hi to $chan</pre> will show <pre>* kr0n says hi to #adiirc</pre> when typing <pre>/hi</pre>

Current variables are $1 to $9, $params, $chan and $me. $1 to $9 represents what you type after /yourcommand e.g <pre>/sup /say whats up $1</pre> when typing <pre>/sup kr0n</pre> it will show like this <pre>User: whats up kr0n</pre>

$params represents everything written after /yourcommand, $chan replaces itself with current channel and $me replaces itself with your current usernick. 

You can make combo commands by using | as a seperator, e.g <pre>/hi /me says hi to $chan | /me says hi again to $chan</pre>

$file[path] returns data from a file, $frand[path] fetchs a random line from a file and $floop[path] gets one line increasingly (line1, then line2, then line3 etc).

h1. Custom Commands by hotkeys

<pre>Syntax = key&key<whitespace>/something</pre>

In addition to making a custom command trigger by typing a /slash command, you make it trigger with a hotkey instead (note, these commmands will not be useable from the new scripting engine)

Useable modifies are ctrl, alt and shift and any character or number or F key.

An example

<pre>ctrl&o /msg $chan ohai i just pressed ctrl and o</pre>

Everytime you press ctrl and 'o' now, this command will be fired off.

<pre>ctrl&alt&o /msg $chan ohai i just pressed ctrl and alt and o</pre>

Everytime you press ctrl and alt and 'o' now, this command will be fired off.

h1. Unified Scripting

<pre>Syntax = OnEvent<whitespace>code</pre>

The new scripting tries to combine normal client commands, your custom commands, functions and events into one scripting language.

In Commands -> Edit Commands you can enter a scripting line with the following syntax:

Followed by either an expression like this (works recursivly)

<pre>

if (SOMETING == SOMETHINGELSE) { EXECUTE HERE }

if (SOMETING != SOMETHINGELSE) { EXECUTE HERE }

if (SOMETING ismatch SOMETHINGELSE) { EXECUTE HERE }</pre>

or by an executed command or function

You can now combine expressions with && (AND) and || (OR) like this

<pre>

if (SOMETHING == SOMETHING && SOMETHINGELSE != SOMETHINGELSE) { EXECUTE HERE }

if (SOMETHING == SOMETHING || SOMETHINGELSE != SOMETHINGELSE) { EXECUTE HERE }</pre>

The logic behind these expressions is not fully tested, id love any feedback on this.

It is also possible to use else if like this

<pre>if (SOMETHING == SOMETHING) { EXECUTE HERE } else if (SOMETHINGELSE == SOMETHINGELSE) { EXECUTE HERE }</pre>

In the future just "else" will be possible to.

(note: ismatch will check if SOMETHING exist inside SOMETHINGELSE e.g if something is "hello" and something else is "hello world" it would return True because "hello" exist)

Executed commands are /slash commands already in the client e.g /msg #channel hello world.

Executed functions are predefined functions in the client, only two exists for now.

An execution block can consist of both commands and functions if seperated by | (pipe) character like this <pre>/msg #channel hello world | .function bla bla | /msg #channel2 hello world</pre>

Furthermore there is a lot of predefined variables for use with these functions, for now they are:

$event / current event, e.g PRIVMSG 001 MODE and so forth

$channel / the channel the event occurred on, if any

$msg / the message to the channel/user or the message in a raw irc line e.g whois [kr0n] is a registered nick

$nick / the nick the event was sent from, can be a irc.server.com, a nick or null

$me / my current nick

$network / the network the event occured on e.g Quakenet

$ident / the from user ident if any

$host / the from user hostname if any

$myident / my ident

$myhost / my host

$server / host from the server e.g irc.server.com

Currently predefined functions are:

<pre>

.insert <nick (use null for nonick)> 

<where (a channel or $channel, a nick or $nick, or status)> 

<MsgType (MsgServer/MsgUser/MsgEmote/MsgCTCP/MsgNotice/MsgClient/MsgLog)> 

<$msg or message></pre>

<pre>

.eat <what (text or all)></pre>

.insert is used for inserting a specific message type into a chat window, its intended for use in cases where you want to override how adiirc shows a given event, but can also be used for adding additional messages.

.eat is used to tell adiirc to either "eat" the text output from an event or "eat" everything and don't act on this event at all.

Putting it all togheter, here are a few examples:

<pre>

OnEvent if ($event == NOTICE) { if ($msg ismatch hi there) { .insert $nick status MsgNotice $msg | .eat text } }</pre>

insert the notice into the server window and tells adiirc to "eat" its own text output from this notice

<pre>

OnEvent if ($event == PRIVMSG && $msg == herp) { /msg $channel derp }</pre>

if the event is a PRIVMSG AND the $msg equals "herp", then show "derp" in the channel

<pre>

OnEvent if ($event == PRIVMSG) { if ($nick == Q || $nick == $me) { /msg $channel Q or $me is speaking! } }</pre>

if the event is a PRIVMSG and the $nick equals "Q" OR $me then show "Q or $me is speaking" in the channel

<pre>OnEvent if ($event == OnOp && $nick == $me) { /msg $channel Thx for op! }</pre>

if the event is OnOp and the target nick is me, then show "Thx for op!" in the channel

A list of custom events that is also usable as $event ==

<pre>

OnOwner

OnDeOwner

OnSpecialOp

OnSpecialDeOp

OnOp

OnDeOp

OnHop

OnDeHop

OnVoice

OnDeVoice

</pre>

h1. Scripting changes in latest beta

This does not apply to the latest stable release!

*Scripting is now unified completly which means all variables applies to all scripts and:

$file[path] is now $file(path);

$frand[path] is now $frand(path);

$floop[path] is now $floop(path);

COMMAND|COMMAND must now be COMMAND | COMMAND for parsing simplicity, this will possibly be removed in the future please use COMMAND ; COMMAND instead*

*OnEvent* is now executed *AFTER* the event, use *OnBeforeEvent* for events where you want to .eat or in other ways manipulate the event.

Shorter aliases are added for simplicity.

<pre>

OnCommand /command { EXECUTE }

On EVENT { EXECUTE }

OnBefore EVENT { EXECUTE }

</pre>

New command /nmsg added for cross network output, and a new event OnSongChanged. 

Combine them and you can automatically announce song changes in a channel or to a user with:

<pre>

OnEvent if ($event == OnSongChanged) { /nmsg <network> <channel/Nick> $0-; }

</pre>

Announce to several channels with:

<pre>

OnEvent if ($event == OnSongChanged) { /nmsg <network> <channel/Nick> $0-;/nmsg <network> <channel/Nick> $0-; }

</pre>

Network is the network name where the channel is, e.g NordicIRC, freenode, Quakenet, look at the name of the server window you are connected on to find it.

Also added is better escaping, variables and a "null" variable, e.g

<pre>

OnEvent if ($event == PRIVMSG) { if (%test == null) { %test = SOMETHING;/echo test is %test } }

</pre>

New variable $now returns unixtime/ctime from current time.

New variable $active returns the current window Status/#channel/Nick.

New variable $! returns how many $0 $1 etc variables are filled (not sure if final name of it)

New variable $r! returns how many $raw0 $raw1 etc variables are filled (not sure if final name of it)

New variable $activeserver returns an id for current server

New variable $status returns current server status

These variables are saved into vars.ini unless removed (%var set to null) and reloaded when adiirc starts.

You can change/use them in any script.

Note also that all user set variables starts with % and client variables starts with $.

Some commands for manipulate variables:

<pre>

/set {-u seconds/-d] [%var] [value] / create or update a variable with value -u seconds, will delete the variable after X seconds, -d will decrease its value by 1 every second, then remove it

/unset [var] / deletes a variable

/inc {-u seconds/-d] [%var] [value] / increases a variable with value (only if value and var is ints) -u seconds, will delete the variable after X seconds, -d will decrease its value by 1 every second, then remove it

/dec {-u seconds/-d] [%var] [value] / decreases a variable with value (only if value and var is ints) -u seconds, will delete the variable after X seconds, -d will decrease its value by 1 every second, then remove it

/vars shows a list of all variables and their values

</pre>

var %variable = 4242, %variable2 = 4343; will create local variables that gets deleted when the script is done.

using += instead of = will append to the variable, if both variable and new value is numbers it will combine them to a new number %variable += 4242.

Variables is still work in progress, id love some feedback/ideas of what it can be used for.

halt can now be used instead of .eat all, it will halt immediately, ignoring rest of the script.

return will halt immediately, ignoring rest of the script, but not eat anything.

<pre>

OnLoad / Called when the script is loaded

OnUnload / Called when the script is unloaded

OnReload / Called when the script is reloaded

OnConnecting / Called when a server is connecting

OnLookingUp / Called when a server is looking up the hostname

OnConnected / Called when a server is connected

OnDisconnect / Called when a server gets disconnected

OnCommand / Called whenever a user types a /slash command in the client ($0- will hold the full command, $0 will be the first word, $1 the second and so on)

OnCTCPRequest / Called when a user recives a CTCP request

OnCTCPReply / Called when a user recives a CTCP reply

ACTION / Called when a user recives a ACTION (/me) message

OnNickChanged / Called when a user's nick changes, will only trigger on the user unlike NICK who triggers for everyone

OnSongChanged / Called when a song is changed in the selected media player

</pre>

A few examples using these.

<pre>

OnEvent if ($event == OnLoad) { %myvariable = This was set at startup }

OnEvent if ($event == OnUnLoad) { .msgbox varible set at startup was %myvariable }

OnEvent if ($event == OnReLoad) { .msgbox Script reloaded }

OnEvent if ($event == OnConnecting) { /echo i r conecting }

OnEvent if ($event == OnLookingUp ) { /echo i r looking up hostname }

OnEvent if ($event == OnConnected ) { /echo i r connected }

OnEvent if ($event == OnDisconnect) { /echo i r disconnected }

OnEvent if ($event == OnCommand) { if ($0 == /me) { /echo i typed /me } }

OnEvent if ($event == OnCommand) { /echo i typed $0, full command was $0- }

OnEvent if ($event == OnCTCPRequest) { /echo CTCP Request $0- from $nick }

OnEvent if ($event == OnCTCPReply) { /echo CTCP Reply $0- from $nick }

OnEvent if ($event == ACTION) { /echo ACTION $0- from $nick }

OnEvent if ($event == OnNickChanged) { /echo My nick is now $0 } 

OnEvent if ($event == OnSongChanged) { /echo Song changed to $0- }

</pre>

New Operators, all operators can now use ! to reverse the logic e.g !ison. If no operators are added it will test if remaining text is not null if (%test), if ($channel) or if (!$channel) etc.

<pre>

> / Will try and cast left and right variable to int and try "int1 greater than int2"

< / Will try and cast left and right variable to int and try "int1 lower than int2"

>= / Will try and cast left and right variable to int and try "int1 greater than or equal to int2"

<= / Will try and cast left and right variable to int and try "int1 lower than or equal to int2"

isbetween / Will try and cast left variable to int and right variable have to be int-int, e.g "40 isbetween 30-50"

ison / check if ($nick ison $channel) nick is the channel

isop / check if ($nick isop $channel) is operator on the channel

ishop / check if ($nick ishop $channel) is half operator on the channel

issop / check if ($nick issop $channel) is special operator on the channel

isowner / check if ($nick isowner $channel) is channel owner

hasvoice / check if ($nick hasvoice $channel) have voice on the channel

inchan / check if i am in chan (#channel inchan) (#channel !inchan)

isnum / check something is a number (5 isnum) (5 !isnum)

</pre>

A complete rewrite of the parser logic is done, introducing the "else" keyword, and you can now use any nested length of "if" "else if" and "else" e.g:

<pre>

OnEvent if ($event == PRIVMSG) { 

	if (%test == null) { 

		/echo Hello world; 

		if (%test == null) { 

			/echo Hello world; 

		} 

	} else if (%test == null) { 

		/echo Hello world

	} else (%test == null) { 

		/echo Hello world 

	} 

	if (%test == null) { 

		/echo Hello world 

	} 

}

</pre>

also ; is now useable like | for line ending.

Simple kickcounter script:

<pre>

OnBeforeEvent if ($event == OnCommand) { 

	if ($0 != /kick) {

		return; 

	}

	if (%kickcount == null) { 

		%kickcount = 0; 

	}

	%kickcount++;

	if (!$2) { 

		/kick $channel $1 Kick number %kickcount;

		halt; 

	} 

}

</pre>

You can now use "-" on $<number> variables to get all words from $<number> and after.

<pre>

OnEvent if ($event == OnCommand) { /echo $2- }

</pre>

When you type "/msg $me this is a test" you will get only "this is a test"

<pre>

OnEvent if ($event == OnCommand) { /echo $3- }

</pre>

When you type "/msg $me this is a test" you will get only "is a test"

<pre>

OnEvent if ($event == OnCommand) { /echo $0- }

</pre>

When you type "/msg $me this is a test" you will get "/msg $me this is a test"

$0- is now equal to $params and $msg, and $0 will return the first part e.g the command "/msg"

Also you can use $raw<number> like $raw0 $raw1 $raw0- to get parts of the raw irc message. This will likely be the default way when better parsing functions are added.

Several functions are added, they are all recursive and you can use any %variable or $variable as parameters:

They are also usable inside if () statements.

All variable numbers are floats and all functions supports floats for precise calculations.

<pre>

$replace(text, text2, text3) / replace all occurrences of text2 in text with text3

$upper(text) / return text uppercase

$lower(text) return text lowercase

$mid(text, startpos, endpos) / return part of text from startpos to endpos

$substr(text, startpos, endpos) / return part of text from startpos to endpos

$left(text, pos) / return pos characters starting from left of the text

$right(text, pos) / return pos characters starting from right of the text

$remove(text, text2) / replace all occurrences of text2 from text

$len(text) / return length of text

$count(text, text2) / counts all occurrences of text2 in text

$pos(text, text2) / returns first occurrences position of text2 in text

$lastpos(text, text2) / returns last occurrences position of text2 in text

$strip(text) / removes all color and font tags

$repeat(text, times) / repeats text X times

$insert(text, text2, pos) / inserts text2 into pos of text

$chr(num) / returns ascii character from the number num

$char(num) / returns ascii character from the number num

$calc(formula) / calculate any variation of +-*/

$formatdate(date, text) / formats a unix timestamp into date using date variables %d %m %y etc

$fdate(date, text) / formats a unix timestamp into date using date variables %d %m %y etc

$host(nick) / returns the hostmask of nick

$ident(nick) / returns the ident of nick

$(number) / dynamically gets a $0 $1 $2 variable e.g $(1) is same as $1 (not sure if final function name)

$cond(cond, execute1, execute2) / checks if cond is true then executes execute1, else executes execute2, will return string if not at the begining of the line

$iif(cond, execute1, execute2) / checks if cond is true then executes execute1, else executes execute2, will return string if not at the begining of the line

$round(num, decimals) / rounds down a float to X decimals

$regex(text, pattern) / does a regular expression test if text matches pattern, then returns the matched part

$file(path) / reads file to end and returns the entire output without newlines

$fileloop(path) / reads through a file one line at the time, line increases +1 every time the same file is called

$floop(path) / reads through a file one line at the time, line increases +1 every time the same file is called

$filerandom(path) / returns a random line from a file

$frand(path) / returns a random line from a file

$chan(num) / if num is 0 returns how many channels you are joined on this server else returns channel name in position num

$user(#chan, num) / if num is 0 returns how many users are on this #chan else returns nick in position num

$nick(#chan, num) / if num is 0 returns how many users are on this #chan else returns nick in position num

$server(num) / if num is 0 returns how many servers you are connected to else returns server id in position num

</pre>

All paths needs to be escaped e.g c:\\users\\kr0n\\file.txt if only a filename is entered, the script directory will be used.

All characters that needs to be escaped before used as strings are \ { } ;

In some cases you might have to escape ( ) | , # $ %

/* and */ needs to be escaped if you want to display them together\/* and \*/

<pre>

OnEvent if ($event == JOIN) { /echo $replace(this is a test, test, replaced test) }

</pre>

Shows "this is a replaced test"

<pre>

OnEvent if ($event == JOIN) { /echo $replace($replace(this is a test, test, replaced test), replaced test, replaced again test) }

</pre>

Shows "this is a replaced again test"

Here is an fullblown kickban example script using the script editor

<pre>

OnCommand /kb {

	if (!$1) {

		/echo /kb - Nick missing;

		return;

	}

	var %msg = $iif($channel, $2-, $3-);

	var %chan = $iif($channel, $channel, $2);

	# Set this for default ban reason, or remove for no default reason

	# Can be shortened to %msg = $iif(%msg, %msg, GTFO);

	if (!%msg) {

		%msg = GTFO;

	}

	if ($me isop %chan) {

		/raw MODE %chan +b *!$ident($1)@$host($1);

		/raw KICK %chan $1 %msg;

	} else {

		/echo You are not oper on %chan;

	}

}

</pre>

Simple calculator script:

<pre>

OnCommand /calc {

	if (!$1) {

		/echo /calc - Parameters missing;

		return;

	}

	# typing /calc -p <expression> sends output to channel

	if ($1 == -p) {

		/msg $channel Calculating : $2-;

		/msg $channel Result is : $calc($2-);

	} else {

		/echo Calculating : $1-;

		/echo Result is : $calc($1-);

	}

}

</pre>

Colored version

<pre>

OnCommand /calc {

	if (!$1) {

		/echo /calc - Parameters missing;

		return;

	}

	# typing /calc -p <expression> sends output to channel

	if ($1 == -p) {

		/msg $channel $chr(3)4Calculating : $2-;

		/msg $channel $chr(3)4Result is : $calc($2-);

	} else {

		/echo $chr(3)4Calculating : 4$1-;

		/echo $chr(3)4Result is : $calc($1-);

	}

}

</pre>

CTCP flood detection example

<pre>

OnEvent if ($event == OnCTCPRequest) {

	if (!%count) {

		/set -u 10 %count 1;

	} else {

		/inc -u 10 %count 1;

	}

	if (%count > 4) {

		/ignore -u 30 -t $nick!$ident@$host;

	}

}

</pre>

while (CONDITION) { EXECUTE } is now useable for a loop

Mass mode example

<pre>

OnCommand /mass {

	if (!$2) {

		/echo /mass - Parameters missing [+/-<mode> <nick> <nick> <nick>];

		return;

	}

	%len = 2;

	# equal to while (%len <= $count(%len, $chr(32)))

	while (%len <= $!) {

		if ($(%len) ison $channel) {

			/mode $channel $1 $(%len);

		}

		/inc %len;

	}

}

</pre>

It is now possible to use custom commands as functions, lets say you make a /calc like this.

<pre>

OnCommand /mycalc {

	return $calc($0+$1);

}

</pre>

Then you can call this function with eiter /mycalc <number> <number> the normal way or $mycalc(<number, <number>) like this

<pre>

OnCommand /testcalc {

	/echo $0 + $1 is $mycalc($0, $1);

	/echo 5 + 4 is $mycalc(5, 4);

}

</pre>

Typing /testcalc will show the result. These custom functions are fully nested like the client functions.

Simple convert temperature C to F or F to C

<pre>

OnCommand /temp {

	if ($1 == C) {

		/echo $round($calc(($2 * 9/5) + 32), 1) F;

	} elseif ($1 == F) {

		/echo $round($calc(($2 - 32) * 5/9), 1) C;

	}

}

</pre>

/temp C 20 will print 68 F

Shows info about users on a channel

<pre>

On JOIN {

	var %t = 0;

	/echo There are ($user($chan, 0)) users in ($chan);

	while (%t < $user($chan, 0)) {

		%t++;

		var %nick = $user($chan, %t);

		/echo User (%t) is (%nick) and is $iif(%nick isop $chan, opped, not opped);

	}

}

</pre>

Shows info about servers, channels and users

<pre>

On JOIN {

	var %s = $server(0), %c = 0, %u = 0, %t = 0, %c2 = 0;

	while (%t < %s) {

		%t++;

		/setserver $server(%t);

		%c += $chan(0);

		%c2 = 0;

		while (%c2 < $chan(0)) {

			%c2++;

			%u += $user($chan(%c2), 0);

		}

	}

	/echo You are on (%s) servers, (%c) channels with (%u) users;	

}

</pre>