# Data types

KVIrc built-in data types

KVirc has three basic built-in data types: simple variables, arrays of simple variables and associative arrays of variables.
There is a fourth builtin data type: object that allows creation of complex structures and object-oriented programming; the object data type is described in another document.

## Variables

The variables can be either global to the application or local to the command scope. The content of a variable is basically a string: any sequence of ASCII characters. In some contests the string may be interpreted as a number. All the variable names start with a percent '%' sign.

## 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.
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.
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

You don't need to declare variables. 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.

## 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.
The arrays have its own namespace thus %Array[] has nothing to do with %Array (that is a simple variable).
<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 %<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

## Array references

When <index> is an empty string then the subscript %<name>[] is called "array reference" (maybe a bit unproperly :). You may think that notation as referencing the "whole array".
The following example shows how the array assignment.

        %A[100]=x
        %A[200]=y
        %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 special syntax %<name>{}@ returns a comma separated list of keys in the dictionary; 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

Index, Language Overview

KVIrc 3.2.0 Documentation
Generated by root at Thu Mar 9 08:43:54 2006