![]() |
![]() |
Data typesKVIrc built-in data types |
||||||||||||||||||||||||||||
VariablesAll 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 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. 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
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. 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
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 destructionUsually 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.
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 typesKVirc 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:
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. <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.
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).
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:
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 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{})).
ObjectsObjects are described in this document |