Editing mirc/variables

{{Template:mIRC Guide}}

'''mIRC variables''' are items which can hold data temporarily, or permanently, for use 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.

== Variable Scope: Global vs. Local ==

There are two kinds of variables: local and global. '''Scope''' refers to the visibility of variables in your code. In other word, where these variables can 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 code line, or block in which they were created in. Once the script has finished, the variable is deleted. 

Syntax:

<syntaxhighlight lang="mirc">;single variable
var %temp = value
 
;multiple variables
var %a = value, %b = second value, %c = and so on and so forth</syntaxhighlight>

'''Note''': Since mIRC 6.21, you can avoid using the = sign when using the /var commmand.

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 addition alias that uses two local variables:

<syntaxhighlight lang="mirc">alias add {
  var %number1 = $1, %number2 = $2
  echo -a %number1 + %number2 = $calc(%number1 + %number2)
}</syntaxhighlight>

An example usage of the script above is: /add 1 3 which will output: 1 + 3 = 4. Once the add alias has finished executing, both "%number1" and "%number2" are destroyed. Remember, these local variables cannot be called upon outside of their code blocks.

<span style="color: #9E1010;">'''Incorrect use''' of local variables:</span>
<syntaxhighlight lang="mirc">alias wrong {
  var %myvar = 3
  wronger
}
alias wronger {
  echo -a %myvar
}</syntaxhighlight>

If you were to execute the above by typing ''/wrong'', you would get the following error: '''* /echo: insufficient parameters'''. This is because the local variable, in this case ''%myvar'', has been stored within the ''wrong'' alias code block, and is, therefore, unavailable to the ''/wronger'' alias that has been called.

=== 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:

<syntaxhighlight lang="mirc">;create variable
set %var value</syntaxhighlight>

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

<syntaxhighlight lang="mirc">;multiple variables
var -g %var = foo, %var2 = bar, %var3 = foobar</syntaxhighlight>

'''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...)

== The equel sign '=' ==

Although it's not require since 6.21, the equel sign can be used to assign a value to a variable without actually using a command:
<syntaxhighlight lang="mirc">%var = value</syntaxhighlight>
If %var is local, this will change the local variable.
If %var is global, it will naturally change the global variable.
If %var doesn't exist, it will create a global variable.

== 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: ===

<syntaxhighlight lang="mirc">;unset a single variable
unset %variable
 
;unset multiple variables
unset %var1 %var2 %var3</syntaxhighlight>

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

<syntaxhighlight lang="mirc">alias unsetWildExample {
  set %exampleHello hello there
  set %exampleTest another var
  set %exampleVar yet another var
 
  ;unset all of them
  unset %example*
}</syntaxhighlight>

You can also unset all of the variables using the '''/unsetall''' command.

<span style="color: #9E1010;">'''Caution:'''</span> This will permanently delete all of your variables! You cannot recover them once you have performed this command, so be careful.

== $null values ==

If a variable is referred to but does not exist, it returns the value $null. Likewise, a variable without any data stored in it returns $null as well.

<syntaxhighlight lang="mirc">alias nullExample {
  ; make sure our variable doesn't exist
  unset %example1
  if (%example == $null) {
    echo -a % $+ example1 is null!
  }
  ; set a variable with no data
  set %example2
  if (%example2 == $null) {
    echo -a % $+ example2 is also null!
  }
}</syntaxhighlight>

Upon executing ''/nullExample'', you will notice that mIRC will echo the following to the active window:

<pre>%example1 is null!
%example2 is also null!</pre>

== Math Operations ==

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

For Example:

<syntaxhighlight lang="mirc">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
}</syntaxhighlight>

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:

<syntaxhighlight lang="mirc">dec %var [value]</syntaxhighlight>

For Example:

<syntaxhighlight lang="mirc">alias example {
  var %g = 10
  dec %g
  ;9
  echo -a %g
}</syntaxhighlight>

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


<syntaxhighlight lang="mirc">inc %var [value]</syntaxhighlight>

For Example:

<syntaxhighlight lang="mirc">on *:action:$(slaps $me $+ *):#mSL:{
  ;increase the variable by 1
  inc %slaps
  msg $chan I have seen %slaps slaps!
}</syntaxhighlight>

== 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 consists of a static part (a part that doesn't change) and a dynamic part (the part that changes).

=== Saving Values ===

The basic syntax to save a dynamic variable is:

<syntaxhighlight lang="mirc">set %<static_part> $+ <dynamic_part>
; or (use var -g to make them global variables)
var %<static_part> $+ <dynamic_part></syntaxhighlight>

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:

<syntaxhighlight lang="mirc">on *:text:!setColor *:#:{
  ;save their favorite color
  set %color. $+ $nick $2
  notice $nick Your favorite color $qt($2) was saved!
}</syntaxhighlight>

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

<syntaxhighlight lang="mirc">set %color. $+ $nick $2</syntaxhighlight>

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

# mIRC evaluates the identifier $nick to "John" and $2 to blue<br /><syntaxhighlight lang="mirc">set %color. $+ John blue</syntaxhighlight>
# mIRC will then append "John" to "%color." Before executing the /set command, thus the final variable looks like this:<br /><syntaxhighlight lang="mirc">%color.John blue</syntaxhighlight>


=== Retrieving Values ===

'''Static Variables'''
Retrieving values from static variables is pretty straightforward. Let's assume you have a variable called ''%myvar'' and it's value is '''abc''', you can get this value simply by referring to the variable outright:

<syntaxhighlight lang="mirc">alias showVar {
  echo -a Here is the value of % $+ myvar: %myvar
}</syntaxhighlight>

Simply put, this will echo the following to the active window where you typed the ''/showVar'' command:

<pre>Here is the value of %myvar: abc</pre>


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

<syntaxhighlight lang="mirc">%<static> [ $+ [ <dynamic> ] ]</syntaxhighlight>

The '''evaluation brackets''', both '''[''' 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:

<syntaxhighlight lang="mirc">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.
  }
}</syntaxhighlight>

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

<syntaxhighlight lang="mirc">var %color = %color. [ $+ [ $2 ] ]</syntaxhighlight>

When you first glance at this statement, it might look a bit confusing, but in fact it is pretty straightforward. Let us continue with John's example and assume someone else typed ''!favColor John'':

#The first thing mIRC will evaluate is the innermost evaluation brackets '''[ ]''', in this case its ''$2'', which will evaluate to ''John''.<br /><syntaxhighlight lang="mirc">%color. [ $+ John ]</syntaxhighlight>
#mIRC will then evaluate the outer evaluation bracket "$+ John".<br />%color.John

Here is another example:

<syntaxhighlight lang="mirc">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
  }
}</syntaxhighlight>

The above code will echo the following:

<syntaxhighlight lang="mirc">1 = Item A
2 = Item B
3 = Item C
4 = Item D
5 = Item E</syntaxhighlight>

What this does is create a bunch of static variables, each with ascending-ordered numerical digits. You will notice we used the evaluation brackets around the variable counter, ''%x''. This allows mIRC to evaluate the variable, and attach it to the static portion of ''%array.''. Basically, during run-time, whatever the ''%x'' variable's value is will be automatically appended to ''%array.''.

Variables are a great resource to have at your fingertips within mIRC! As you've seen, they are very powerful, and yet don't require too much of a headache to understand :)

[[Category:mIRC]]