Difference between revisions of "Category:Aliases"

Latest revision as of 17:27, 29 November 2009

Basic

mIRC script allows you to create your own set of commands and identifiers, refered to as aliases. Aliases can be called from the command line, from other aliases, from popup and from remote scripts. An alias in mIRC can not be called recursively. They can be created by either putting them in the "Aliases" section of the mIRC Scripts Editor, by using the /alias command from either the command line or in the "Remote" section of the Scripts Editor. Creating an alias in the command line results in it being placed in the "Aliases" section of the Script Editor.

Example

; These two work exactly the same way although they are stored in different places

; this is placed in the "Aliases" section
moo { echo -ag moo }

; this is placed in the "Remote" section
alias moo { echo -ag moo }

Naming aliases

You can give an alias virtually any name you want, but keep a few things in mind:

• When you give an alias used as a command the same name as an existing mIRC command, your alias gets preference.
• Some inbuilt commands act differently than the rest, if you have an alias called timertest, you will not be able to start a timer called test, like this: /timertest 0 1 MyTestFunction in this situation you can prefix the command with an exclamation mark (!) as shown below in the example.
• When you give an alias used as an identifier the same name as an existing mIRC identifier, mIRC's identifier gets preference, unless you prefix your alias with a period.

Example:

; at first we add a new alias called "me". If it is used as "$me", it's supposed to return "AveIT!", else it's the usual
; /me alias sending an action to the active channel
/alias me { if ($isid) { return AveIT! } | else { describe $active $1- } }
 
; this alias will return the amount of milliseconds (ticks) pasted between two callings. 
; When called the first time, it will set a variable %timerstart to the current value of $ticks.
; When called the second time, it echo's the difference between the set variable and the current value of ticks.
; This difference is obviously the elapsed time.
/alias timertest { if (!%timerstart) set %timerstart $ticks | else { echo -ag $calc($ticks - %timerstart) ms | unset  %timerstart } }

In the following example, both the custom 'me' and the 'timertest' alias will be used:

; call timertest the first time to set the variable %timertest
timertest
 
; echo $me (that's the default $me alias as it can't be overwritten in the usual way)
; and $.me (that's our custom alias returning 'AveIT!')
echo -ag I am $me but my custom identifer returns $.me
 
; call timertest a second time to echo the amount of elapsed milliseconds
timertest

Finally, the example above would return:

I am Dana but my custom identifer returns AveIT!
16 ms

Note: If you want to start a timer called test with the alias called timertest, you have to prefix the timer with the ! to use the inbuilt mIRC timer command: !timertest 1 1 echo -ag This is my test. It is not encouraged to call an alias starting with timer, or identifers with mircdir, getdir, mididir, or any other alias which can be used with a suffix.

Aliases: parameters and events

mIRC script allows you to pass parameters to your aliases, just like you pass parameters into built-in mIRC commands or identifiers. They can be referred to as $0, $1, $2 ... $N.

Parameters

alias moo { echo -ag m $+ $str(o,$$1) }

Assuming you pass a number as parameter this would echo an "m" folowed by a number of "o's", depending on the number you specified as parameter. This alias can be called in 2 different ways:

/moo 12
$moo(27)

Note that $moo doesn't return anything in this case, it will simply echo the message.

Events

When calling an alias from an event, the identifiers related to that event will still be available in that alias.

on *:TEXT:hi:#: { myAlias }

alias myAlias { msg $chan $nick said hi! }

This would be exactly the same as:

on *:TEXT:hi:#: { msg $chan $nick said hi! }

This in turn means that you don't have to pass a identifier supplied by an event into your alias as parameter.

Commands vs identifiers

Being that you can use your aliases as both commands and identifiers, the question may rise which you should pick. The general answer is quite simple: if you want your alias to have a return value use identifiers and in any other case use commands.

Error handling

However, mIRC's built-in error handling cannot be used for your aliases, so for proper error handling you might want to use return values. For example, you could use return value 1 when an action was succesfull and 0 when it was not.

; this identifier returns 1 if it was succesfull in what it would do and 0 if it wasn't
; the (useless) idea of the following identifier is to message "moo" to the currently active channel
; if it is on QuakeNet
alias moo {
  if ($network != QuakeNet) || (!$chan) { return 0 }
  else {
    msg $chan moo
    return 1
  }
}

To use this as error handling you could do the following:

%error = $moo
if (!%error) {
   ; do what you want to do if the command failed
   ; in this case when there was no channel active
   ; or the server was not QuakeNet
}
elseif (%error = 1) {
   ; do what you want to do if the command succeeded
   ; in this case when there was an active channel and
   ; the server was QuakeNet
}
else {
   ; the script should never reach this place!
}

Although the same identifier could have been run as a command as well, error handling would not have been possible that way. Of course the alias itself has some error handling already, but there are cases in which you want an action to be able to fail.

Another reason to prefer identifiers over comands are parameters. When you call an alias as a command every space will result in a new parameter and there is no way you can get around that. Using an alias as an identifier it is possible to get around the comma and thus have your parameters contain a comma. Here's how to do that:

; calling an identifier with a comma in a parameter
alias test {
  ; the while loop will echo every parameter
  var %i = $0
  while (%i) {
    echo -ag $ [ $+ [ %i ] ]
    dec %i
  }
}

var %param = abcdef,ghijk
%someVar = $test(%param)

The snippets above would result in having the identifier $test echo only 1 parameter: the data which was set in %param. Would you do the same for a command -- replacing the comma with a space -- it would result in /test getting 2 parameters. Handling parameters is much easier if you are a 100% sure which parameter will contain which data, and an identifier is more reliable in doing so.

Forced identifiers

To force an alias to be used only as an identifier or vice versa, you can use the identifier $isid. This will return $true if the alias was called as an $identifier or $false if it was called as a /command.

; this alias can only be called as an identifier
alias qnet {
  if ($isid) {
    ; the following code only gets executed if the alias was called as an identifier
    if ($network === QuakeNet) { return 1 }
    else { return 0 }
  }
}

Calling the alias will result in a return value of either 0 or 1, while calling it as a command will do completely nothing.

Properties

Custom identifiers can use their own properties, which can be checked by using the $prop identifier.

In the example below, $value can have either .squared or .sqrt appended to it in order to change its function. For example, $value(4).squared would return 16, whilst $value(4).sqrt would return 2. Without a property, the alias returns the value provided unmodified.

alias value {
  if ($isid && $1 isnum) {
    if (!$prop) return $1
    elseif ($prop == squared) return $calc($1 ^ 2)
    elseif ($prop == sqrt) return $calc($1 ^ 0.5)
  }
}

See Also

• $isid
• $prop
• $show