Difference between revisions of "Category:Aliases"

Revision as of 21:19, 10 April 2006

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

; 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 virtualy 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.
• When you give an alias used as an identifier the same name as an existing mIRC identifier, mIRC's identifier gets preference.

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 $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 as 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 an identifier -- it can't be used as a command -- or vice versa you can use the identifier $isid.

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