![]() |
![]() |
Data typesKVIrc 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. VariablesThe 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 variablesA 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
Local variablesA 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
But if you execute
Extended scope variablesVariables 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 destructionYou don't need to declare variables. A variable starts to exist at the time that you assing something to it.
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 evaluationA 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
ArraysArrays 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.
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).
Array referencesWhen <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.
DictionariesDictionaries 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".
To remove an association you simply assign the empty string to it:
Dictionaries can be used easily to simulate arrays:
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:
Dictionary evaluationA dictionary can appear in every place where a variable can appear.
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{})).
|