Data types

KVIrc built-in data types

Variables

All the variable names start with a percent '%' sign and follow with a name made up of alphanumeric characters and underscores. The variables can be either global to the application or local to the command scope. The variables that start with an uppercase letter are assumed to be global while the other are assumed to be local. This behaviour can be modified with the use of the global and local keywords (their usage is actually encouraged as experiment: we want to know if this method is better or worse than using the case of the first letter as discriminant). Variable names are case insensitive. There is a third kind of variables named "extended scope variables": they are explained below.

Global variables


A global variable name is formed by a "percent" sign (%), followed by an uppercase letter from A to Z, followed by a sequence of characters in range ('a' to 'z','0' to '9','.','_').
"%INDEX","%My_nickname","%Foo","%Bar1" and "%Foo.BAR" are examples of valid global variable names.
The global keyword can be used to force a variable starting with a lowercase letter to be global while the local keyword can invert this behaviour for local variables. A global variable is global to the entire application, not to the current frame or irc context; be sure to remember this.
You can type
    /%Hello = "Hello world!"
in the commandline of any KVIrc window and then execute
    echo %Hello
in the commandline of any other KVIrc window. You will see "Hello world!" printed in the second window view.

Local variables


A local variable name is formed by a "percent" sign (%), followed by an lowercase letter from a to z, followed by a sequence of characters in range ('a' to 'z','0' to '9','.','_').
"%index","%my_nickname","%foo","%bAR1" and "%foo.BAR" are examples of valid local variable names.
The global keyword can be used to force a variable starting with a lowercase letter to be global while the local keyword can invert this behaviour for local variables. A local variable exists only in the current command scope. The exact command scope definition is rather tricky and depends on the internal KVIrc implementation. Just be aware that:
- An alias body is a command scope.
- An event body is a command scope.
- Any sequence of commands executed at once in a window commandline is a command scope.
You will notice that finding out the current command scope is rather intuitive.
When you type
    %text = "very important text";
in the commandline of any KVIrc window and then try to execute
    echo %text
you will see nothing printed. The variable %text was local to the "command scope" and disappeared immediately after the execution of the assignment.
But if you execute
    %text = "hello"; echo %text wold!
you will see "hello world!" printed in the current window.

Extended scope variables

Variables that start with a ':' character are "extended scope" variables. "%:index" , "%:Hello" , "%:something.else" are all valid special scope variable names.
They're actually used in popups and in timers (but later I might find other usages as well :).
"Extended scope" means that these variables are somewhere in the middle between global and local variables. They normally act as local , but in some cases their lifetime and visibility may be extended.
For example , in the popups , all the special scope variables are visible during all the "lifetime" of a popup (so from the prologue code call to the moment when the user selects an item and the corresponding code is executed).
This allows you to pre-calculate some data or conditions in the popup prologue and use this data in the popup item conditions and item handlers.

Variable creation and destruction

Usually you don't need to declare variables (however you CAN do it with the global and local keyword). A variable starts to exist at the time that you assing something to it.
    %MyVar = some funky text
    %X = 2445833
    %SevenSpaces = "       "
It terminates its existence at the time that you assingn it an empty string:
    %MyVar = ""
    %X = %MyVar
    %SevenSpaces =
The example is based on global variables, but it is valid for local ones as well.
A non existing variable is equivalent to an empty one: you will never get a warning about non existing variables. This convention allows KVIrc to automatically manage the variable creation and destruction.

Data types

KVirc has four basic built-in data types: scalars, arrays of scalars, associative arrays scalars (also known as hashes or dictionaries) and objects.
Scalars are typed internally to integers, strings, real numbers and booleans but KVIrc will usually make all the necessary conversions automatically so you basically don't need to care about it: you can just think the variable as being a variant (or just a string, if this makes the thing simplier for you). Unlike in perl, there is a single namespace for all the datatypes:
    %a = "10"
    %a = $array(10,20)
Both statements refer to the same variable. This also means that a variable can change its type "on the fly" from a simple scalar to an array of scalars or a hash (or even an object, as you will see later). KVIrc is able to implicitly convert scalars to arrays (with a single element) and the inverse where needed.

Variable evaluation

A variable can appear in every place where a parameter is expected: so after the command name, after a switch or inside an identifier parameters. KVirc will try to extract the longest possible variable name after a literal percent '%' sign everywhere in the parameter string. So the command sequence
    %number = 1st; echo this is my %number variable test
will first assign "1st" to the variable "%number" and then execute "echo this is my 1st variable test". The following example will NOT work as expected.
    %number = 1; echo this is my %numberst variable test
KVirc will assign "1" to %number in this case but the next variable name extracted will be "%numberst" that is actually empty; so finally "echo this is my variable test" will be executed. To avoid this problem you can use the backslash escape character:
    %number = 1; echo this is my %number\st variable test

Arrays

Arrays are collections of items indexed by numbers.
The general syntax for an array is:
%<name>[<index>]
<name> is the name of the array and follows the rules valid for the simple variables: the names starting with an uppercase letter designate a global array, the others designate local ones.
Extended scope arrays can be created as well: normally they act as local, but may have extended lifetime in some scopes.
<index> must be a subscript that evaluates to a positive integer and it selects an item in the array. The first index of the array is 0 and the last is equal to size-1.
You can obtain the size of the array by evaluating $length(%<name>) or by using the subscript %<name>[]#.
You don't need to declare the size of the array: it is automatically handled. When you assign a non-empty string to an item, the array is automatically enlarged to contain the index that you are assigning to. If the array was not existing before the assignment, it is created.
If the first assignment index is greater than 0 the items below that index will be empty: will just behave as empty/unset variables.
    # Create an array with 21 elements
    %Names[20]=Pragma
To remove an item from the array you assign it an empty string.
When you remove the highest indexed item the array is automatically shrunk to the next highest non-empty item. If there are no other non-empty items the array is destroyed.
Please note that the memory occupation of the array depends on the <index>.
By assigning a value to the 10000'th item (index 9999) you allocate 10000 entries! (in fact at least ((10000 * 4) + value size) bytes).
An array is destroyed when it contains no more items or when it goes out of scope (a local array obviously).
    # Creating an array with 800 entries
    %Array[799]=test
    echo %Array[]#
    %Array[299]=test
    echo %Array[]#
    %Array[799]=
    echo %Array[]#
    # Now it contains 300 elements

You can reference the whole array by using its name without the square parentheses or by using tye subscript %<name>[] which is also an assertion (that the variable %<name> is in fact an array). Using %<name>[] will thus throw a warning if %<name> is not an array while %<name> will not. You can assign arrays to each other:
    %A = $array(10,20,30)
    %B[]=%A[]
    %B=%A
    echo %B[200]
When you pass an array reference to a command or function, it is evaluated as a comma separated list of entries.
    %Array[0]=Pippo
    %Array[1]=Pluto
    %Array[2]=Paperino
    echo %Array
By assigning a string to an array you assign it to all the array entries:
    %Array[0]=Pippo
    %Array[1]=Pluto
    %Array[2]=Paperino
    echo %Array
    %Array[]=undefined
    echo %Array
This is useful when you want to unset an array: just assign an empty string to all its entries:
    %Array[200]=Test
    echo %Array[]#
    %Array[]=
    echo %Array[]#
You can loop through all the array items by using the foreach command:
    %Array[0]=Pippo
    %Array[1]=Pluto
    %Array[2]=Paperino
    foreach(%item,%Array[])echo %item
Obviously also the traditional for and while indexed-looping methods are available:
    %Array[0]=Pippo
    %Array[1]=Never show this
    %Array[2]=Pluto
    %Array[5]=Hidden again
    %Array[8]=Paperino
    for(%i=0;%i < %Array[]#;%i+=2)echo Entry %i: \"%Array[%i]\";

Dictionaries

Dictionaries are associative arrays of strings. They look close to the perl hashes. The general syntax for a dictionary name is:
%<name>{<key>}
<name> is the name of the dictionary and follows the same rule as for the variables: the names starting with an uppercase letter designate a global dictionary, the others designate local ones.
Again , the dictionaries have its own namespace: you can safely use %Names , %Names[] and %Names{} as different entities in your script.
Extended scope dictionaries can be created as well: normally they act as local, but may have extended lifetime in some scopes.
A dictionary associates a "data string" to each "key string" used. The key can be any string not containing an "unescaped" '}' character and is case insensitive: "key" is equivalent to "KEY" or "KeY".
    %Ages{Pragma} = 24
This assignment associates the key "Pragma" to the number "24" in the global dictionary "%Ages". If the array was not existing yet, it is created first. If the key "Pragma" was already existing, the value associated is replaced with the new value.
To remove an association you simply assign the empty string to it:
    %Ages{pragma} =
The dictionary is automatically destroyed when there are no more associations in it (eg. when you assign the empty string to the last key).
Dictionaries can be used easily to simulate arrays:
    %Links{21} = "http://www.kvirc.net"
Even multidimensional ones:
    %Pixels{324.312} = 1
Remember that in the example above the key "324.312" is a single string.
Obviously the key can contain variables and functions just as any other parameter.
An empty key performs operations on the whole dictionary (just like for the arrays):
You can assign dictionaries:
    %Test2{}=%Test1{}
Assign a scalar to all the items
    %Data{} = "unspecified"
The example above associates the string "unspecified" to all the existing keys in the dictionary %Data. By using this method you can easily destroy a dictionary: simply assign the empty string to it.
    %Data{} =
Other operators have similar semantic when working on "empty keys".

Dictionary evaluation

A dictionary can appear in every place where a variable can appear.
    echo My age is %Ages{$mynick}
If you pass an empty key, the dictionary evaluates to the comma separated list of values stored in it. The values have no defined order. The list is interpreted as single "string" in contexts where a "string" is required, and as a list of "strings" in context where lists of strings are expected. (<-- hehe :)
The special syntax %<name>{}# returns the number of keys in the dictionary. The same value can be obtained by using $length. The special syntax %<name>{}@ returns an array of of keys in the dictionary. The same array is returned by $keys(). The keys have no defined order (well, you may be only sure that the order of the keys is exactly equal to the values order (%name{})).
    %Songs{Jimi Hendrix} = Voodo child
    %Songs{Shawn Lane} = Gray piano's flying
    %Songs{Mina} = Brava
    %Songs{Greg Howe} = "Full Throttle"
    # This is a "single string" evaluation context
    echo %Songs{}
    # This is a "list of strings" evaluation context
    foreach(%var,%Songs)echo %var
    foreach(%var,$keys(%Songs))[cmd]echo [/cmd] %var : %Songs{%var}

Objects

Objects are described in this document

Index, Language Overview
KVIrc 3.2.4 Documentation
Generated by root at Mon Nov 6 10:28:12 2006