Revision as of 02:31, 10 December 2013

Template:mIRC Guide Normal code is executed, as you are probably aware, top down and left right. Evaluation brackets are a mechanism by which a program can alter the natural behavior of the mIRC interpreter.

Evaluation brackets allows us to:

1. Change the order of evaluation
2. Change the number of evaluations

Order of Evaluation

Consider the following code:

//echo -a Hello World, it's $me $+ !

A typical code is evaluated from left to right, one word at a time.

alias x echo -a $1 | return $1
alias eval_example {
  echo -a $x(1) $x(2) $x(3) $x(4)
}

If we run the code above we will get the following result:

1
2
3
4
1 2 3 4

As expected, $x(1) was evaluated first, $x(2) was evaluated second, $x(3) was evaluated third and $x(4) was evaluated last. Earlier we said that we can use evaluation brackets to change the order of evaluation. We will demonstrate that in our next example:

alias x echo -a $1 | return $1
alias eval_example {
  echo -a $x(1) [ $x(2) ] $x(3) $x(4)
}

In this example we surrounded $x(2) with a pair of bracket. The code produced the following result:

2
1
3
4
1 2 3 4

From the output you can see that $x(2) was evaluated first (as shown in the graph below). Once the content of the evaluation bracket was evaluated, the parser went on to evaluating the rest of the line like it would normally from left to right.

Note: Changing the order of evaluation does not change the position of the evaluated value in the actual line.

We can have multiple groups of brackets on the same line. Note that once the parser is done evaluating the first block (from left to right), the parser will proceed to the next pair of evaluation brackets. Let's look at the following example:

alias x echo -a $1 | return $1
alias eval_example {
  echo -a $x(1) [ $x(2) ] $x(3) [ $x(4) ]
}

The code above produced the following results:

2
4
1
3
1 2 3 4

This time we have two pairs of evaluation brackets. mIRC went from left to right evaluating $x(2) first then $x(4). The parser then went on to evaluate rest of the line.

Nested evaluation brackets

Once the parser reached the first evaluation group, it enters it. The process begins all over again inside the evaluation group - it evaluates the content from left to right. If we nest another pair of evaluation brackets we force the parser to evaluate that part first then continue on to the rest of the evaluation content inside that bracket.

Consider the following code:

alias a echo -a A
alias b echo -a B
alias c echo -a C
alias eval_example {
  noop $a [ $b [ $c ] ]
}

The code above produces the following result:

C
B
A

The graph above demonstrates how once the parser enters the outer pair of brackets, the entire process starts all over and the first thing that gets evaluated are the inner brackets.

Note: once an evaluation group is complete, it is take out of the rest of the line.

Interestingly enough, with three identifiers it is possible to generate every single permutation by just using evaluation brackets:

alias a set %str %str $+ A
alias b set %str %str $+ B
alias c set %str %str $+ C
alias d unset %str
alias eval_example {
  echo -a ABC =>   $a   $b     $c     %str $d
  echo -a ACB => [ $a ] $b [   $c ]   %str $d
  echo -a BAC =>   $a [ $b ]   $c     %str $d
  echo -a BCA =>   $a [ $b ] [ $c ]   %str $d
  echo -a CAB =>   $a   $b [   $c ]   %str $d
  echo -a CBA =>   $a [ $b [   $c ] ] %str $d
}

Will produce the following result:

ABC => ABC
ACB => ACB
BAC => BAC
BCA => BCA
CAB => CAB
CBA => CBA

Number of Evaluations

Until now we have been dealing with the order by which the interpreter evaluates things. We will now move on to looking at how many times a single evaluation block gets evaluated.

Under normal conditions, every part of the line is evaluated exactly once.

For simplicity sake we will define a normal condition as any statement that does not contain $(), $eval(), or $evalnext(). The statement above should feel pretty intuitive. Consider:

//echo -a [ $!me ] [ $!me ]

The above code is logically equivalent to:

//echo -a $!me $!me

In both cases everything is evaluated once. A single pair of evaluation brackets causes the interpreter to evaluate the code once.

A code segment is evaluated once more for every additional pair of enclosing evaluation brackets unless:
     1.  The code segment contains spaces, and
     2.  It does not contain $+ to "close the space gap"
If the conditions above are violated, the code segment is evaluated only once. Any additional enclosing evaluation brackets are simply ignored.

We will talk about the $+ case later on.

Spaces in code segment

A space in the code segment is a violation of the first part. This nullifies the behavior of the reset of the enclosing brackets. Here is an example:

alias exe echo -a I was called!
; example:
alias example echo -a [ [ [ [ [ [ [ [ [ [ [ [ [ Hi! [ $!exe ] ] ] ] ] ] ] ] ] ] ] ] ] ]

The code above will indeed print:

Hi! $exe

Note: The exe alias was never called, not even once. Before we move on, it is important to note that if we have a code segment inside another code segment. That code segment follows the rules all over from the start. Consider the following example:

//echo -a [ [ [ a $!me ] ] ] <=> [ [ [ a [ $!me ] ] ] ] <=> [ [ [ a [ [ $!me ] ]  ] ] ]

The last part had a sub-code segment with no spaces: "[ [ $!me ] ]". Since $!me has no spaces, it will be evaluated once (to $me) and then the outer brackets will evaluate it once again to your name. In my case we get "a David". Since now we have a space in the code segment, all the outer brackets are nullified (as with the other two cases separated by <=>).

The code above will produce something like:

a $me <=> a $me <=> a David

Multiple evaluations

If we follow the simple rule above, we can easily evaluate a specific code segment multiple files. Consider the following example:

alias exe echo -a I was called! | return Hi!
; example:
alias example echo -a [ [ [ [ [ $!!!!exe ] ] ] ] ]

The above code prints:

I was called!
Hi!

Here is a more interesting example of multiple evaluations:

alias a return $!b
alias b return $!c
alias c return $!d
alias d return Surprise!
alias example echo -a [ [ [ [ $a ] ] ] ]

The above code will print:

Surprise!

Solving the space issue using $+()

By know we already know that the following code will only evaluated once since it violates the first rule: spaces in the code segment.

//echo -a [ [ a $!me ] ]

Prints:

a $me

The easiest way to fix this issue is to surround the entire group with $+() and put a space ($chr(32)) between the two tokens. This means we no longer have spaces (note that spaces inside the identifier are superfluous).

//echo -a [ [ $+(a, $chr(32), $!me) ] ]

Because we now have no spaces, the additional evaluation bracket is not ignored and our code is evaluated once again:

a David

$+ Special behaviors