Revision as of 04:59, 30 November 2013

Template:mIRC Guide

mIRC variables are items which can hold temporary data to be used at a later time. You can create, edit, or delete them at any time. All mIRC variables must be prefixed with a % sigil (example %var or %cookies). Variables are untyped – therefore capable of storing letters, numbers, or strings at any given point. There are two kinds of variables: local and global.

Variable Scope: Global vs. Local

Scope refers to the visibility of variables in your code. In other word, where can these variables be seen from.

Local Variables

Local Variables are given local scope. They are created for the duration of the script that made them and they can only be accessed from within the alias they were created in. Once the script is done the variable is deleted. Local variables are automatically deleted at the end of the alias or event block.

Syntax:

;single variable
var %temp = value
 
;multiple variables
var %a = value, %b = second value, %c = and so on and so forth

Local variables are good for temporary things like string manipulations and math expressions. Most of your code will use local variables.

Below is a simple add alias that uses two local variables:

alias add {
  var %number1 = $1, %number2 = $2
  echo -a %number1 + %number2 = $calc(%number1 + %number2)
}

An example usage of the script above is: /add 1 3 which will output: 1 + 3 = 4. Once the add alias finish executing, both "%number1" and "%number2" are destroyed .

Global Variables

A Global variable is a variable that is accessible from every alias or event. They can be created and edited from every script. They are not deleted unless they are purposely destroyed using the unset command (we will talk about that later on).

Syntax:

;create variable
set %var value

Note: The /set command does not use the = operator.

Because the /set command can only set a single variable at a time, you can use the /var command in conjunction with -g switch to set multiple global variables.

;multiple variables
var -g %var = foo, %var2 = bar, %var3 = foobar

Practical use: a global variable is good for storing variables that you will need to use in the future from another script or at different time. (Login System, Away System, Sockets, Etc...)

Unsetting Variables

If you have already set a variable you can unset it at any time during using the /unset command. The unset command supports a single variable or multiple variables. Generally, there is no reason to unset local variables as they will get destroyed anyway at the conclusion of the script execution.

Syntax:

;unset a single variable
unset %variable
 
;unset multiple variables
unset %var1 %var2 %var3

The /unset command supports wildcard characters to be able to unset multiple variables. For example:

alias unsetWildExample {
  set %exampleHello hello there
  set %exampleTest another var
  set %exampleVar yet another var
 
  ;unset all of them
  unset %example*
}

You can also unset all the variables using the /unsetall

$null values

If a variable is referred to but does not exist, it returns the value $null.

alias nullExample {
  ;make sure our variable doesn't exist
  unset %example
  if (%example == $null) {
    echo -a % $+ example is null!
  }
}

Math Operations

The standard assignment operator (=) can also be used to do basic 2 operand math operations.

For Example:

alias mathExample {
  ;10
  var %a = 5 + 5
  ;9
  var %b = %a - 1
  ;90
  var %c = %b * %a
  ;print it to the screen
  echo -a %c
}

mIRC has two additional commands that can be used to easily increase and decrease the value of a numerical variable.

The dec command allows you to decrease the value of a variable by 1 or by a given value if specified:

dec %var [value]

For Example:

alias example {
  var %g = 10
  dec %g
  ;9
  echo -a %g
}

The inc command allows you to increase the value of a variable by 1 or by a given value if specified:

inc %var [value]

For Example:

on *:action:$(slaps $me $+ *):#mSL:{
  ;increase the variable by 1
  inc %slaps
  msg $chan I have seen %slaps slaps!
}

Dynamic Variable Names

In many occasions you may need to save individualized data (data for a particular user or channel for example). Dynamic variables allow you to do just that. A dynamic variable's name usually consist of a static part (a part that doesn't change) and a dynamic part (the part that changes).

Saving

The basic syntax to save a dynamic variables is:

set %<static_part> $+ <dynamic_part>
; or (use var -g to make them global variables)
var %<static_part> $+ <dynamic_part>

Although you can omit the static part out, its strongly discouraged because variables should have a meaningful name that explains their purpose.

Let's take a look at an example:

on *:text:!setColor *:#:{
  ;save their favorite color
  set %color. $+ $nick $2
  notice $nick Your favorite color $qt($2) was saved!
}

Let's take a closer look at the variable assignment statement:

set %color. $+ $nick $2

The static part is "color." Which is never going to change, the dynamic part is "$nick". Let's assume someone by the name John types "!setColor blue". This is what happens:

1. mIRC evaluates the identifier $nick to "John" and $2 to blue
   set %color. $+ John blue
2. mIRC will then append "John" to "%color." Before executing the /set command, thus the final variable looks like this:
   %color.John blue

Retrieving

Retrieving a value from a dynamic variable is a little bit more complicated. The basic syntax is as follows:

%<static> [ $+ [ <dynamic> ] ]

The evaluation brackets, [ and ], are an essential part of retrieving the value from a dynamic variable. They allow us to force mIRC to evaluate part of a statement before anything else. Take a look at the rest of the myColor script:

on *:text:!favColor *:#:{
  var %color = %color. [ $+ [ $2 ] ]
  if (%color != $null) {
    notice $nick $2's favorite color is %color $+ .
  }
  else {
    notice $nick $2 does't have a favorite color set yet.
  }
}

In the example above we retrieved the color from the dynamic variable and set it to a local variable called %color for the rest of the script. Let's take a closer look at the retrieval statement:

var %color = %color. [ $+ [ $2 ] ]

When you first glance at this statement, it might look a bit confusing, but infect its straightforward. Lets continue with John's example and assume someone else typed !favColor John

1. The first thing mIRC will evaluate is the innermost evaluation brackets [ ], in this case its "$2", which will evaluate to "John".
   %color. [ $+ John ]
2. mIRC will then evaluate the outer evaluation bracket "$+ John".
   %color.John

Here is another example:

Alias varExample {
  var %array.1 = Item A
  var %array.2 = Item B
  var %array.3 = Item C
  var %array.4 = Item D
  var %array.5 = Item E
  var %x = 1
  while (%x <= 5) {
    echo -a %x = %array. [ $+ [ %x ] ]
    inc %x
  }
}

which will have the following output:

1 = Item A
2 = Item B
3 = Item C
4 = Item D
5 = Item E