Difference between revisions of "Category:Aliases"

From Scriptwiki
Jump to: navigation, search
m (Aliases: parameters and events)
m (explained $prop)
 
(9 intermediate revisions by 5 users not shown)
Line 3: Line 3:
  
 
=== Example ===
 
=== Example ===
 +
; These two work exactly the same way although they are stored in different places
 +
 
  ; this is placed in the "Aliases" section
 
  ; this is placed in the "Aliases" section
 
  moo { [[echo]] -ag moo }
 
  moo { [[echo]] -ag moo }
Line 10: Line 12:
  
 
== Naming aliases ==
 
== Naming aliases ==
You can give an alias virtualy any name you want, but keep a few things in mind:
+
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.
 
* 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.
+
* Some inbuilt commands act differently than the rest, if you have an alias called [[timer|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.
 
* 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:
 
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 } }
+
; 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-Then-Else|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 } }
 
   
 
   
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.
+
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
 
  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
 
  echo -ag I am $me but my custom identifer returns $.me
 +
 
 +
; call timertest a second time to echo the amount of elapsed milliseconds
 
  timertest
 
  timertest
This should return:
+
 
 +
Finally, the example above would return:
 +
 
 
  I am Dana but my custom identifer returns AveIT!
 
  I am Dana but my custom identifer returns AveIT!
 
  16 ms
 
  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.
+
'''''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:
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.
+
!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 ==
 
== Aliases: parameters and events ==
Line 45: Line 65:
 
=== Events ===
 
=== Events ===
 
When calling an alias from an event, the identifiers related to that event will still be available in that alias.
 
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 }
+
  on *:[[On_text|TEXT]]:hi:#: { myAlias }
 
   
 
   
 
  [[alias]] myAlias { [[msg]] [[$chan]] [[$nick]] said hi! }
 
  [[alias]] myAlias { [[msg]] [[$chan]] [[$nick]] said hi! }
  
 
This would be exactly the same as:
 
This would be exactly the same as:
  on *:TEXT:hi:#: { [[msg]] [[$chan]] [[$nick]] said hi! }
+
  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.
 
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 ==
 
== 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.
+
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 ===
 
=== Error handling ===
Line 61: Line 81:
 
  ; the (useless) idea of the following identifier is to message "moo" to the currently active channel
 
  ; the (useless) idea of the following identifier is to message "moo" to the currently active channel
 
  ; if it is on QuakeNet
 
  ; if it is on QuakeNet
  [[alias]] moo {
+
  alias moo {
   [[if]] ([[$network]] != QuakeNet) || (![[$chan]]) { [[return]] 0 }
+
   if ([[$network]] != QuakeNet) || (!$chan) { return 0 }
   [[else]] {
+
   else {
     [[msg]] [[$chan]] moo
+
     msg $chan moo
     [[return]] 1
+
     return 1
 
   }
 
   }
 
  }
 
  }
Line 71: Line 91:
 
To use this as error handling you could do the following:
 
To use this as error handling you could do the following:
 
  %error = $moo
 
  %error = $moo
  [[if]] (!%error) {
+
  if (!%error) {
 
     ; do what you want to do if the command failed
 
     ; do what you want to do if the command failed
 
     ; in this case when there was no channel active
 
     ; in this case when there was no channel active
Line 81: Line 101:
 
     ; the server was QuakeNet
 
     ; the server was QuakeNet
 
  }
 
  }
  [[else]] {
+
  else {
 
     ; the script should never reach this place!
 
     ; the script should never reach this place!
 
  }
 
  }
Line 102: Line 122:
  
 
=== Forced identifiers ===
 
=== 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]].
+
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
 
  ; this alias can only be called as an identifier
 
  [[alias]] qnet {
 
  [[alias]] qnet {
Line 113: Line 133:
 
Calling the alias will result in a return value of either 0 or 1, while calling it as a command will do completely nothing.
 
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 ==
+
=== 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]]
 
* [[$isid]]
 +
* [[$prop]]
 +
* [[$show]]
 +
 
[[Category:mIRC_Help]]
 
[[Category:mIRC_Help]]

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

Pages in category "Aliases"

The following 7 pages are in this category, out of 7 total.