# Operators

Variable operators , assignments & co.

Operator constructs are commands just like the other ones. All the operators work on local or global variables and dictionaries.
The generic operator syntax is:
<left_operand> <operator> [right_operand]
where <left_operand> and [right_operand] depend on the <operator>.
Some operators have no [right_operand] and these are called unary operators: they operate directly on <left_operand>.

## = (Assignment)

The assignment is the "plainest" of the binary operators: it works just like in any other programming language.
If the <left_operand> is a variable, then the <right_operand> is assigned to it; if the variable doesn't exists yet , it is created.
If <right_operand> evaluates to an empty value then the variable is unset.

    # Assigning a constant to the global variable %Tmp
    %Tmp = 1
    # Assigning a string constant to the global variable %Tmp
    %Tmp = some string
    # Assigning a string constant to the local variable %tmp
    %tmp = "some string with whitespace         preserved"
    # Assigning a variable to another variable copies its contents
    %tmp = %somevariable
    # Assigning a variable string to the global variable %Z
    %Z = my eyes are %color
    # Assigning a variable string (with a function call inside) to the local variable %x
    %x = the system os is $system.osname
    # Assigning an empty string to the local variable %y unsets %y
    %y =
    # This is equivalent to the above
    %y = ""
    # This is equivalent too, if $function evalutates to an empty string
    %y = $function()

If the <left_operand> is a dictionary/array entry, then the <right_operand> is assigned to it; if the dictionary/array entry doesn't exist (or the whole dictionary/array doesn't exists) it is created.
If <right_operand> evaluates to an empty value then the dictionary/array entry (and eventually the whole dictionary/array, if there are no other entries) is unset.

    # Assigning a variable string to a global dictionary entry
    %Dict[key] = $system.osname\ian
    # Unsetting a local dictionary entry
    %mydict[23] = ""

If the <left_operand> is an array reference then the semantics depend on the <right_operand> type. If <right_operand> is an array reference then its contents are copied to the <left_operand>.
If <right_operand> is a dictionary (keys) reference then its values are copied to to <left_operand>.
If <right_operand> is a scalar then the value is assigned to every entry of <left_operand>.
This is an easy way of unsetting a whole array: just assign an empty string.
If the <left_operand> is a dictionary reference then the semantics depend on the <right_operand> type. If <right_operand> is a dictionary reference then its contents are copied to the <left_operand>.
If <right_operand> is an array reference then its contents are copied to to <left_operand> using the array indexes as keys.
If <right_operand> is a dictionary key reference then the keys are copied to the <left_operand> using numeric indexes starting from 0 as keys.
If <right_operand> is a scalar then the value is assigned to every key of <left_operand>.
This is an easy way of unsetting a whole dictionary: just assign an empty string to all its keys.
(If you play with huge dictionaries/arrays it might be a good idea to unset them when no longer needed)

    # Assigning a dictionary to another: %mydict[] becomes a copy of %anotherdict[]
    %mydict[] = %anotherdict[]
    # %mydict[] gets the values of the dict returned by $features
    %mydict[] = $features
    # Assigning a string to ALL the keys of %mydict
    %mydict[] = "some default value"
    # Unsetting a whole dictionary
    %mydict[] =
    %AnotherGlobalDict[] = ""

## =~ (Binding operator)

This operator is a really ugly, poor and clueless attempt to reach at least 1% of the power of the perl =~ operator :D
It allows some complex string operations to be performed efficently by operating directly on the left operand (in fact this is a lot faster in KVIrc since at least one step of parsing is skipped).
Its basic syntax is:
<left_operand> =~ <operation>[parameters]
Where <operation> may be one of 't','s' and parameters depend on it.
<left_operand> is the target of the <operation>.
If <left_operand> is an array or dictionary, the <operation> is executed on each item they contain.
Operation 't' is the transliteration.
The complete syntax with parameters is:
<left_operand> =~ t/<search characters>/<replacement characters>/
where <search characters> is a string of characters that are replaced with the corresponding characters in <replacement characters>.
This operation can be also named 'y' or 'tr' (to preserve some compatibility with other languages).

    %A=This is a test string
    echo %A
    %A=~ tr/abcdefghi/ABCDEFGHI/
    echo %A

Operation 's' is the substitution.
The complete syntax with parameters is:
<left_operand> =~ s/<search pattern>/<replacement pattern>/[flags]
where <search pattern> is an extended regular expression to be matched in the <left_operand> and <replacement string> is a special pattern that will replace any occurence found.
<search pattern> may contain parentheses to capture parts of the matched text. <replacement string> can contain the escape sequences \\N where N is a number between 1 and 9 to be replaced by the captured text.
(We use \\N because KVIrc will first unquote the string when parsing...)
\\0 is a special escape that will be replaced by the entire match (is always valid!).
WARNING: the "capture-text" feature is not available if KVIrc has been compiled with qt older than 3.0.0. You can find out if the feature is available by looking for the string "Qt3" in the array returned by $features.
[flags] may be a combination of the letters 'g','i' and 'w'.
'g' causes the search to be global and not stop after the first occurence of <search pattern>.
'i' causes the search to be case insensitive.
'w' causes the search pattern to be interpreted as a simple wildcard regular expression.

    %A=This is a test string
    echo %A
    %A=~ s/([a-z])i([a-z])/\\1I\\2/
    echo %A
    %A=~ s/([a-z])i([a-z])/\\1@\\2/gi
    echo %A

## X= (Arithmetic Self-operators)

The general syntax is:
<left_operand> <operation> <right_operand>
Where <left_operand> and <right_operand> must evaluate to numbers.
All these operators perform the operation on <left_operand> and <right_operand> and then store the result in <left_operand> (which therefore must be a variable, an array entry or a dictionary entry).
<operation> may be one of:
+= : sums the <right_operand> to <left_operand>
-= : subtracts <right_operand> from <left_operand>
*= : multiplies <left_operand> by <right_operand>
%= : calculates <left_operand> modulus <right_operand>
|= : calculates <left_operand> bitwise-or <right_operand>
&= : calculates <left_operand> bitwise-and <right_operand>
/= : divides <left_operand> by <right_operand>

## ++ and -- (Increment and Decrement)

These two operators work only on numeric operands.
The general syntax is:
<left_operand> <operator>
There is no <right_operand>.
++ increments <left_operand> by one, -- decrements <left_operand> by one.
These are equivalent to += 1 and -= 1.

## .= , << , <+ , <, (String concatenation operators)

All these operators work also on whole arrays and dictionaries.
Operator .= : APPENDS the <right_operand> to the <left_operand>
Operator <+ is a synonim for .= (backward compatibility)
Operator << : appends <right_operand> to <left_operand> separating the two strings by a single space if and only if <left_operand> and <right_operand> are non-empty.
Operator <, : is similar to '<<' ; appends , separating with a single ',' with the same condition.

Examples

First set the variable %var

    %var = Ciao ciao

Then append a nickname...

    %var << Pragma

%var now contains "Ciao ciao Pragma"
Append a '!' character

    %var <+ !

%var now contains "Ciao ciao Pragma!" Now reset it.

    %var =

Now %var is unset.
Reset it with a comma separated list of items

    %var = Pragma,Diabl0,Arter|o
    %var <, MalboroLi

%var now contains "Pragma,Diabl0,Arter|o,MalboroLi"
Now a longer example.

    %var = l
    echo It's name starts with the letter %var!
    %var <+ inux
    echo Yes , it is %var!
    %var << OS
    echo Use %var!
    %var <, Mac OS
    echo There are two items in this list : %var
    %var = $strlen(%var)
    echo And it is %var characters long (including the comma)
    %var--
    echo Excluding the comma : %var
    %var+=%var
    echo Now it is doubled : %var
    %var =
    echo Now the var is unset (empty): (%var) !

Index, Language Overview

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