Introduction

This lesson assumes that the user has some basic knowledge about writing aliases, simple loops, and general identifiers.

Not all token identifiers will be touched in this lesson but only a few because this is meant to be more of an introduction to tokens.

What are tokens?

Tokens are actually strings of anything separated by something. Confusing? Maybe. To make it simpler, every word in this paragraph is a token. For example, in the sentence "Que hermosa mujer", the word "que" is a token, the word "hermosa" is a token, and also the word "mujer". Those words are separated by a space. The space between each word is called the delimiter.

Tokens can be anything, words or group of words, or numbers. And also delimiters can be anything, a single number, a comma, a dot, a space. But remember that a delimiter cannot be more than a single character. For the meantime, just remember the example above. Hopefully, that has given you a picture of what tokens are.

What are token identifiers?

Token identifiers are tools in scripting. They allow you to control strings of data.

Some of the more commonly used (and simpler) tokens are the following:

$gettok $istok $numtok $addtok $remtok

Don't let the names bother you, each and every one of the above will be explained. Once you have understood these, understanding the rest of the token identifiers will not be a problem.

$gettok

This identifier has got to be the most commonly used identifier. Every scripter has used this in one way or another.

What $gettok does is get a token from a string (get it? "get tok"). So if you have a sentence and you want to grab a single word from it, you will use the $gettok identifier.

Here's an example. Supposing we have a list of nicks and we want to extract the fourth nick from that list, we use:

$gettok(blue-elf madgoat khaled moo,4,32)

Try and type the following (exactly as you see it) within mIRC and hit enter:

  //echo -a The fourth token is $gettok(blue-elf madgoat khaled moo,4,32)

Now try and change the number 4 to 1 and see what happens. And then try and change the number to 2 or 3.

So the tokens in the above example are "blue-elf madgoat khaled moo" and the delimiter is 32. The reason why 32 is used is because it is the ASCII number of a space, or in mIRC terms, $chr(32) is a space.

If for instance, the string is "blue-elf.madgoat.khaled.moo", the tokens are still the same but the delimiter is now a dot, the ASCII number of which is 46. To be able to grab a token from that string, it will appear like this:

$gettok(blue-elf.madgoat.khaled.moo,3,46)

Now try this:

//echo -a $gettok(blue-elf.madgoat.khaled.moo,3,46) is the third token.

Try having different words in the sentence, and once again change the number 3 to any number and see what happens.

$istok

This is one of the tokens that is easier to understand. What it does is to simply check if a token is in the string of text. Here is an example:

$istok(this is the sentence,this,32)

It will check if the word "this" is already in the text. The syntax therefore is $istok(string of words,token,delimiter).

This identifier is usually used for if-else statements as they return the value $true or $false. For example:

$istok(one two three,two,32) will return a $true value $istok(boy.girl.man.woman,dog,46) will return a $false value

Once again, try this identifier by using the /echo method mentioned above.

$numtok

Another easy identifier, it simply counts how many tokens there are in a string. For instance:

  //echo -a There are $numtok(There are N words in this sentence.,32) words in this sentence.

Once again, test this identifier by changing the delimiter to a dot or an exclamation mark.

$addtok

When using token identifiers, sometimes it becomes inevitable that you want to add something to a variable, or a string of words. This is where the $addtok comes in handy.

The help file says:

$addtok(text,token,C) Adds a token to the end of text but only if it's not already in text.

Pretty straightforward, actually. What it does is add a token to the string of text or tokens that you have, but only if the token is not yet in the text. Therefore, as the examples in the help file shows:

$addtok(a.b.c,d,46) would return a.b.c.d

And the next example will not add the letter "c" because "c" is already in the text.

$addtok(a@b@c@d,c,64) will return a@b@c@d

Here is an example alias that uses $addtok with variables.

alias addnicks {
  %Nicks = ""
  %Number = 0
  :loop
  inc %Number
  if (%Number <= 10) {
    %Nicks = $addtok(%Nicks,$nick(#,%Number),32)
    goto loop
  }
  echo -a The first ten nicks in # are: %Nicks
}

Try the above alias and see what it does.

On a sidenote, if you still want to add the token even if it's already in the text, do not use $addtok. For example, in the above alias, you can change line number 7 from:

         %Nicks = $addtok(%Nicks,$nick(#,%Number),32)

... to this:

         %Nicks = %Nicks $nick(#,%Number)
  

Remember that $addtok only adds a token if it is NOT in the text. So you should use some other means as shown above if you want something else.

$remtok

This identifier is the opposite of $addtok. It removes a token from a string. The help file says:

$remtok(text,token,N,C) Removes the Nth matching token from text.

Now we have an extra parameter, which is the N. The N there is a number. It will remove the first token from the string if it matches the token that you have given. For example:

$remtok(a.b.c.d,b,1,46) will return a.c.d

Try typing the following and see what it does:

   //echo -a $remtok(Which word will be removed,word,1,32)

Note that even if the mIRC.hlp does not mention it anywhere, the N parameter seems to be optional. If the N is not specified, mIRC will automatically remove the first matching token. For example:

  //echo -a $remtok(This word will remove the first instance of word,word,32)

The above will have the same result as typing:

  //echo -a $remtok(This word will remove the first instance of word,word,1,32)

On the other hand, the example below will remove the second "word":

  //echo -a $remtok(This word will remove the first instance of word,word,2,32)

One very important thing to remember when using $remtok is that, it is not the same as the $remove identifier! $remove will not care if what you have specified is a token or a part of another word, it will simply remove all instances of that parameter.

This example will remove all instances of "word":

  //echo -a $remove(This words will remove the word,word)

But the following will not..

  //echo -a $remtok(This words will remove the first instance of word,word,32)

Do it yourself

Play around with tokens and test the given examples. And try to change the tokens and use numbers or symbols and other words and delimiters. Experimenting is one of the best ways you can learn tokens.

Hints and Tips:

* Difference between istok and isin

$istok is different from the "isin" operator in if-else statements! $istok finds exact word matches. Here is an example, type them within mIRC:

  //if (the isin these quick little brown foxes) echo -a true | else echo -a false

The above will echo the word "true" because the word "the" IS IN the text but it is NOT NECESSARILY A TOKEN but it may be part of a token.

On the other hand, the following will echo false.

  //if ($istok(these quick little brown foxes,the,32) == $true) echo -a true | else echo -a false

That's why, always remember the differences between $istok and the isin operator because they do not produce the same results all the time.

* Commas as delimiters

If the string of tokens is separated by a comma, you will need to set the string of tokens into a variable because mIRC does not parse it correctly. Thus, instead of:

  echo -a $gettok(this,is,a,bad,way,3,44)

... use the following:

 set %variable this,is,a,bad,way
 echo -a $gettok(%variable,3,44)

* Getting the ASCII value

If you are not sure how to get the ASCII value of a delimiter, use the Character Map that is included in a standard Windows installation. If not, an easier way would be to use the following alias (you can rename it to anything you want):

  GetAsc /echo -a The ASCII number of $1 is $asc($1)

* Variable size limit

Although indirectly related, you should keep in mind that variables have a size limit of around 950 characters. This means that a single variable can have a value the length of which is less than or about 950 letters, words, symbols, numbers, altogether.

This is mentioned here because scripters tend to use $addtok with their variables and forgetting the limit which causes your script to be disrupted.

* Achieving arrays

For those who are programmers of other languages and are new to mIRC scripting, remember that at the time this article was written, arrays are not supported by mIRC. The closest thing you can achieve arrays is by using tokens.