$gettok is pretty simple, and a lot of the $XXXtok identifiers work similarly, so the learning curve is smaller for the others. When it's relevant, these identifiers have a case-sensitive variant for situations where hunting for a token needs to tell the difference between Nick and nick.
$gettok(text,N,C)
or
$gettok(STUFF,token-number,separator)
This assumes STUFF is a list of items that you can parse to grab part of it. Token-number lets you specify which token(s) you want. Token 0 is the total number of tokens, 1 is the 1st, etc. -1 is the last token, -2 is next-to-last, etc. You can use a range to grab several tokens. $gettok($1-,2-4,32) grabs the 2nd thru 4th words, $gettok($1-,2-,32) grabs the 2nd thru infinity tokens.
The last parameter is the ASCII character that separates your tokens from each other. If it's a normal sentence and you're wanting to grab the 2nd word, you use 2 as the token, and 32 is the ascii value for the space character. Comma is a common separator, so you often see 44 as the last parameter. You want to pick a separator that won't be part of any of your tokens, because unlike CSV format it doesn't let you put double-quotes around your token to allow the separator to be within the token. You can parse the foldernames of your c:\path\path\ by using 92 as your separator, because that's the ASCII value of "\".
So the userid name on the computer is likely to be the 2nd foldername in the path:
//echo -a $sysdir(desktop)
... so you can grab the username with:
//echo -a $gettok( $sysdir(desktop) , 3 , 92)
if you have a long list of tokens, and you just want the LAST token, you can get it 2 ways, you can use $numtok(STUFF,separator) or $gettok(STUFF,0,separator) to count the number of tokens and then use $calc() to subtract 1. Or you can use -1 as the token. -2 is the next-to-last, etc.
//echo -a mirc is installed into the $gettok( $mircexe , -2 , 92) folder.
When using tokens, you must always make sure to have 'something' as a token between your separators, because 2 consecutive separators doesn't treat this as being a $Null token, it treats the pair as a single separator.
//echo -a $gettok( a.b.c.d.e , 4 , 46)
... returns the value 'd'. If you replace the 'b' with a space the value is still 'd'. However if you delete the 'b' so you have 2 consecutive periods touching, the pair of periods becomes 1 separator, so 'c' becomes the 2nd token, and the above 4th token shifts from being 'd' to being 'e'.
The $XXXtok identifiers ignore leading or trailing separators, so a period in front of the 'a' or behind the 'e' won't change any of the answers. If you use $gettok($mircdir,1-,92) it always strips off the final backslash because there's no token following that final backslash. $gettok(LIST,1-,46) displays the same regardless whether LIST is a.c.d.e or a..c.d.e because it's stripping repeating, leading, or trailing separators.
You may sometimes see scripts doing things like
if ($event isin TEXT JOIN) do something
this is fine if you've controlled what $event could possibly be. However, if you've trapped the events CONNECT CONNECTFAIL DISCONNECT, this method will always trigger for CONNECT because it's "isin" the other words. For those cases, you can use $istok:
var %filetype $gettok($filename,-1,46)
; this grabs the last token following the last period, so it works for file.name.txt and file.txt, but returns the entire filename if there's no extension.
if ( $istok( jpg gif png bmp , %filetype , 32 ) echo -a this is a picture
Instead of a separate check for each filetype, you can do 1 check for everything.
Be careful when using $addtok, because this adds the token only if the token isn't already there. So if you're using $addtok to fill 20 slots in a list of bettors and fill 20 slots in a list of betting amounts, anyone who has multiple bets placed will have their user name only added the 1 time - while bet amounts will be added only if they're unique. Better would be using $puttok to oerwrite the Nth token. You'll have similar issues with tokens as you had with zapping an ITEM in your points.ini - you'd need to write $false or 0 to keep the token from being $null and dropping off the list.
If you store your list of 20 in a tokenized variable, you can avoid all those disk reads and writes. Instead of cycling through the list deleting the tokens 1 at a time you could deal with each of the 20 bets individually, then you can just wipe your bet list with:
/set %betlist 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0
or
set %betlist $str(0.,19) $+ 0
