View source for Category:Aliases

== 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 <nowiki>"Aliases"</nowiki> section of the mIRC Scripts Editor, by using the /alias command from either the command line or in the <nowiki>"Remote"</nowiki> 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.
* Some inbuilt commands act differently than the rest, if you have an alias called [[timertest|Timer]], you will not beable 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:
 /alias me { [[If-Then-Else|if]] ([[$isid]]) { [[return]] AveIT! } | [[describe]] [[$active]] [[$1-]] }
 /alias timertest { if (!%timerstart) [[set]] %timerstart [[$ticks]] | else { echo -ag [[$calc]]($ticks - %timerstart) ms | unset %timerstart } }
 
 Here, the $isid identifer checks to make sure we're calling $me and not /me, if we are calling /me make sure we do /describe to the active channel with the parameters suppled.
 timertest
 echo -ag I am $me but my custom identifer returns $.me
 timertest
 This should 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 prefox 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 <nowiki>"m"</nowiki> folowed by a number of <nowiki>"o's"</nowiki>, 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 *:[[On_Text|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.

== Also See ==
* [[$isid]]
[[Category:mIRC_Help]]