Editing mirc/aliases

{{mirc title|Aliases}}
In many cases, it is easier to code a large program by working with a single, small, unit of logic at a time. Aliases, more commonly known in other languages as functions, are blocks of code which performs a specific task and can be relatively independent of the rest of the script. Most aliases are created to be used multiple times by different scripts. In addition to their normal usage, aliases can also be used to create custom [[#Shortcuts_and_Function_Keys|shortcuts and function keys operations]].

=== Syntax: ===
Aliases have the following basic syntax:

<syntaxhighlight lang="mIRC">;single-line alias
alias aliasName /commands

;multi-line alias
alias aliasName {
  /commands
}</syntaxhighlight>

A simple hello world alias would look like this:

<syntaxhighlight lang="mIRC">Alias hello {
  echo -a Hello World!
}</syntaxhighlight>

The keyword "alias" is required to tell mIRC the following code is an alias. "hello" is the name of the alias. Everything inside the pairs of brackets ({ and }) will get executed when this alias is called. To call that alias, we would simple call the name of it:

<syntaxhighlight lang="mIRC">//hello</syntaxhighlight>

This will print:

<pre>Hello World!</pre>

=== Alias arguments ===

Data can be passed to aliases via the argument list. The argument list is always evaluated from left to right. The arguments are passed to the alias via the $N identifiers, where N is a numeric value from starting at one.

If we called an alias called "example" like this:

<syntaxhighlight lang="mIRC">/example A B C D
; or
... $example(A, B, C, D)</syntaxhighlight>

Alias example will have $1 returning 'A', $2 returning 'B', $3 returning 'C', and $4 returning 'D'. The total number of tokens available can be retrieved via the $0 identifiers. In this case $0 will return 4.

The exact rules on how $N work is identical to the how they work with the [[Token Manipulation - mIRC#Tokenizing_a_string|/tokenize command]]. More information about $1- {{mIRC|$1-|here}}

=== Aliases Tab ===

The aliases tab is designed specifically for aliases only. Note that because it can only be used for aliases, the "alias" prefix must be left out:

<syntaxhighlight lang="mIRC">aliasName {
  ; commands
}</syntaxhighlight>

'''Note:''' Aliases from the aliases tab can freely call aliases from the remote tab and vice versa.

=== Commands vs. Identifiers ===

in mSL, aliases can serve as both '''identifiers''' and '''commands'''. These two terms are used to describe the type of alias it is. In general, a '''command''' will usually not return anything but simply process some type of data. An '''Identifier''' on the other hand will generally return some kind of a value.

=== Aliases Prefixes ===

==== Command Prefixes ====

===== . prefix (silencing) =====

You can prefix your command call by a dot '.' to prevent mIRC from displaying its typical message, such as {{mIRC|/timer|.timer}}.

'''Note''': Silencing a custom aliases command call makes all the custom aliases command call in that original be silenced too, with no way to unsilence them (see second example in the {{mIRC|$show}} page)

===== ! prefix (built-in call) =====

By default, a command call will call any custom alias you may have defined, you can force a call to a mIRC built-in command by using the '!' prefix, /!join makes sure it calls the mIRC built-in join command instead of the custom join alias you may have defined.

==== Identifier Prefixes ====

===== $$ special construct (required value) =====

You can use {{mIRC|$$|$$identifier}} to halt a routine if the value returned by the identifier is $null, typically, this allows to quickly stops if a parameter is missing.

===== / and . prefix (custom call) =====

By default, an identifier call will call the built-in mIRC identifier, you can force a call to your own custom identifier by using the '/' or '.' prefix, $/me makes sure it calls your custom identifier. If you do not have the alias defined, mIRC consider it a call to an alias named with the '/' or the '.'

===== ~ prefix (built-in call) =====

In essence, such a call to an identifier will only look at built-in identifiers, custom aliases won't be searched for.
This will bypass the Identifier Warning message but it's a bit unclear why this is useful, it can allow you to check if an identifier exist in mIRC's own language and has a value but you cannot use it to check built-in which would return $null then, and you have to execute the function, checking for "$findfile" or "$zip" would be problematic.

===== ! prefix (delay evaluation) =====

You can use $!identifier to return the plain text identifier instead of it getting evaluated, the rest of the line is evaluated normally, $!+( $me ) does not delay the evaluation of $me

=== Restriction on alias name ===

Given the alias prefixes above, you cannot start the name of an alias with a command prefix if you are going to call it as a command, same idea for identifier.



== Commands ==

A command usually does not return any value, but instead, it processes the arguments it's given. In a command, every argument is separated by a space. $0 will contain the total number of arguments passed to that alias. $N (where N is a number 1 to $0) will contain the arguments. For example:

<syntaxhighlight lang="mIRC">alias example {
  echo -a $0 arguments passed
  echo -a The first 3 arguments are:
  echo -a Arg1 = $1
  echo -a Arg2 = $2
  echo -a Arg3 = $3
}</syntaxhighlight>

We can run the code using the follow statement:

<syntaxhighlight lang="mIRC">/example A B C D</syntaxhighlight>

This will produce the following result:

<pre>4 arguments passed
The first 3 arguments are:
Arg1 = A
Arg2 = B
Arg3 = C</pre>

== Identifiers ==

Generally, an identifier is a value-returning alias. This means we pass some arguments to that alias and we expect it to return something in return. Identifiers are prefixed with the dollar symbol ($). An identifier may or may not need arguments to be passed to it. If the identifier requires that some arguments be passed to it, the arguments must be in a parenthesis, comma delimited.

<syntaxhighlight lang="mIRC">;This identifier does not need any arguments
echo -a $me
;This identifier requires that we pass it some arguments:
echo -a $calc(1 + 1)</syntaxhighlight>

Unlike a command, arguments are now comma delimited. As a result, passing a single argument with spaces is possible. In addition, since identifiers require that some value be returned back, we use the '''/return''' keyword to return some value. The /return command allows the calling routine to continue on using the value returned. Below is an example:

<syntaxhighlight lang="mIRC">alias example {
  return hello there!
}</syntaxhighlight>

we can call that identifier using like this:

<syntaxhighlight lang="mIRC">//echo -a $example</syntaxhighlight>
This will print:

<pre>hello there!</pre>

By default, 'return' strips leading/trailing/consecutive spaces from the result before returning it. Consider the following aliases:
<source lang="mIRC">
alias example_result   return   $str($chr(32),2) $+ a $+ $str($chr(32),2) $+ a $+ $str($chr(32),2)
alias example_resultex returnex $str($chr(32),2) $+ a $+ $str($chr(32),2) $+ a $+ $str($chr(32),2)
</source>

'return' removes the extra spaces, while returnex preserves them, as shown by:
<source lang="mIRC">
//echo -a $replace($example_result  ,$chr(32),.)
output: a.a
//echo -a $replace($example_resultex,$chr(32),.)
output: ..a..a..
</source>

== Identifiers Properties ==

Properties are a unique feature to identifiers with arguments. They allow you to pass one more additional remark to the alias. That remark can be retrieved from within the alias using the '''$prop''' identifier. Properties are usually a way to manipulate the arguments we pass to the alias.

Consider this basic alias that returns some quantity of degrees in radians.

<syntaxhighlight lang="mIRC">; converts degrees to radians
alias convert {
  return $calc($1 * $pi / 180)
}</syntaxhighlight>

For example:

<pre>//echo -a $convert(1)
0.017453
//echo -a $convert(15.5)
0.270526</pre>

We can add two properties to make it convert from degrees to radians and and vice versa.

<syntaxhighlight lang="mIRC">; converts degrees to radians
alias convert {
  if ($prop == deg2rad) return $calc($1 * $pi / 180)
  if ($prop == rad2deg) return $calc($1 * 180 / $pi)
  ; invalid property
  return 0
}</syntaxhighlight>

For example:

<pre>//echo -a $convert(10).deg2rad
0.174533
//echo -a $convert(0.174533).rad2deg
10.000004
//echo -a $convert($convert(15.5).deg2rad).rad2deg
15.499998</pre>

== Aliases as Both an Ident and Cmd ==

Although most aliases do only serve as identifiers or commands, it is possible to act as both. 

Consider the following alias, logfind. Logfind finds the first matching line from the log for the active window. If it's called as an identifier, we wil return the matching line. If it's called as a command, we will print it instead:

<syntaxhighlight lang="mIRC">; Finds the first matching line from the log for the active window
alias logfind {
  ; find the log file
  var %logfile $window($active).logfile
  var %match = $read(%logfile, nw, $1)
  ; if it was an identifier, return the match
  if ($isid) return %match
  ; print it if it was a command
  echo -agc info * Logfind Match: %match
}</syntaxhighlight>

We can call that alias as an identifier, for example:

<pre>//echo -a $logfind(*kicked*)
[12:33] * Foo was kicked by *.example.com (Flooding (Limit is 12 lines per 10 seconds))</pre>

We can also call it as a command:

<pre>/logfind *kicked*
* Logfind Match: [12:33] * Foo was kicked by *.example.com (Flooding (Limit is 12 lines per 10 seconds))</pre>

Also note that when an alias is called as a /my_alias command it inherits the $parms string as existing in the parent alias, but when called as $my_alias identifier the $parms string is set to $null.

=== replacing built-in commands ===

You can intercept any script's use of a built-in command, as long as they have not used the ! prefix to force execution of the built-in command without searching all the aliases for a match. For example, here's something to trap echo commands and remove colors, bold, etc from the displayed string:

<source lang="mIRC">
alias echo {
  if ($1 isnum 0-) var %text $strip($2-)
  else             var %text $strip($1-)
  echo %text
}
</source>

Because an alias is not re-entrant, using 'echo' inside an alias of the same name cannot be intercepted by that same alias, though it can be trapped by another alias named echo, unless this alias calls it like !echo. This does not completely trap all colors, because it does not remove the color from "/echo -c ctcp message".

Especially if your alias is non-local, beware about trapping built-in commands without supporting ALL variations of syntax for them. For example, the /server command has different behaviors for different purposes. There are some sets of switches which join a server, and other syntax for modifying the servers.txt file.

Incorrect trapping of built-in commands is one source of bugs that can be easy to overlook, so you may need to use $isalias(built_in_command) to see if any of your scripts has trapped it, and even that doesn't see local aliases unless $isalias is used from within that same script.

Something else which might need to be preserved is the state of $v1 and $v2. Consider the following while the above 'alias echo' is trapping the :

<source lang="mIRC">
//if (var1 != var2) echo -a $ $+ v1 is $v1 and $ $+ v2 is $v2 | echo test | !echo and now $ $+ v1 is $v1 and $ $+ v2 is $v2
output:
$v1 is var1 and $v2 is var2
test
and now $v1 is test and $v2 is 0-
</source>

Note how the first echo interprets $v1 and $v2 before sending to the alias echo, so the values are not altered. But now see how the identical message has been altered by the if() statement within alias echo, due to $v1 and $v2 created in one alias being seen in the editbox or another alias. In case this can be an interference for the calling scripts, you can save the $v1 and $v2 values before altering them, then restore them afterwards:

<source lang="mIRC">
alias echo {
  var -p %v1 $v1 , %v2 $v2
  if ($1 isnum 0-) var %text $strip($2-)
  else             var %text $strip($1-)
  echo %text
  if (%v1 == %v2) noop
}
</source>

This saves the $v1 and $v2 as they exist when entering the alias. Then before exit, it creates a dummy if() statement which has the effect of restoring them.

== Aliases for other users ==

A consideration in creating aliases which might be executed by other users is to take into account that other users will not use the same colors that you do. There are large user bases who use each of black or white backgrounds, and there are lots of colors which contrast well against one yet have poor contrast against the other. In the default 'mIRC Classic" color set, 8 "Yellow" and 11 "LightCyan" do poorly against a White background, but do well against Black. On the other hand, 2 "NavyBlue" does well against White but poorly against Black. And of course, the White and Black text colors obviously don't contrast well against the same color background.

One choice for your script is to override the background while setting text color, but even that doesn't guarantee the user has set that pair of index colors to be a good contrast against each other. To guarantee the actual color hues display as you intend, you can use color index 16-98 as long as the script will be used on v7.52 or higher, because on older versions interpret those color indexes as black. Only a few color hues of the default 0-15 "mIRC Classic" colors are duplicated exactly within the 16-98 range, so others might need to choose the closest approximation.

Another choice is to use echo's -c switch to set the color which that user has assigned in their Alt+K dialog. For example, if your alias wishes to mimic a blue error message similar to those from built-in mIRC commands:

<source lang="mIRC">/echo -ac info this displays in the same color as mIRC error messages</source>

== Additional alias features: ==

Regardless of whether or not an alias was called as a command or as an identifier, if it used the /return command to return back, you can get that value using the '''$result''' identifier.

<syntaxhighlight lang="mIRC">alias example {
  foo
  echo -a $result
}
alias foo {
  return result!
}</syntaxhighlight>

Output:

<pre>/example
result!</pre>

In addition, aliases can be coded to work in verbose mode or not. If the command was prefixed with the dot (.) symbol, $show will return $false, otherwise it will $true. For example:

<syntaxhighlight lang="mIRC">alias example {
  if ($show) {
    ;Indicate we are doing something
    echo -a we are doing something
    ;Show more debug info.
  }
  ;do something
}</syntaxhighlight>

Output:

<syntaxhighlight lang="mIRC">/example
we are doing something
/.example</syntaxhighlight>

'''Note:''' /echo -q is a built-in alternative to doing that, the echo will be displayed or not depending on the value of $show.

<h3 id="shortcuts">Shortcuts and Function Keys</h3>

Aliases can be used to redefine function keys and shortcuts by simply renaming them the actual key or key combinations. For the F-keys all you need is to name the actual alias F1 through F12. C OR S can be used for the Shift and Ctrl Key, but cannot create a hotkey involving the ALT key. For example SF1 is Shift+F1 keys, and CF1 is Ctrl+F1, but you cannot have a hotkey alias for Ctrl+Shift+Fkey or for Alt+Fkey.

For Example:

<pre>alias SF1 {
  echo -a Shift+F1 was pressed!
}
alias cF4 { echo -sg cF4 executed prevents ctrl+F4 closing active window! }
alias F1 { echo -sg F1 executed prevents opening the F1 help window! }
alias F11 { echo -sg F11 executed prevents F11 toggling full-screen mode on/off (can still use menubar/view) }
alias sF9 { echo -sg shift+F9 executed - skipping currently playing sound file! }
</pre>

== Local Aliases ==

By default, every alias is public. This means any script from any file is able to call that alias (even from the editbox). An alias can be made local by using the -l switch. A local alias is only visible to local scripts - scripts that are in the same file as the alias itself. This is especially useful when your aliases have common names and you don't want to cause conflicts when distributing your script to other people.

<syntaxhighlight lang="mIRC">Alias -l <name> {
  ;code
}</syntaxhighlight>

=== Exposing private and public functionality ===

It's possible to allow more functionality for local aliases and hide that from outside scripts.

<syntaxhighlight lang="mIRC">alias -l example {
  echo -a Local code called me!
}
alias example {
  echo -a Non-local script called me!
}</syntaxhighlight>

If some code local to that script file calls example, the local alias will execute. If some other code outside of this script file calls it the second alias will execute instead. Note that the local alias must be on top, or else the other aliases inside that script will see only the non-local alias above it.

=== Alias order ===

The order used by mIRC to locate your alias is as follow:

* If the name exists as a built-in $identifier, your alias cannot be called as an identifier unless you use the . or / prefixes as described above. If the name exists as a built-in /command, it cannot execute your alias if the ! command prefix is used as describe above.
* if the call is made from a script and there is a local alias for that name in the script file, that alias is used
* otherwise, if the call is made from a script and there is a non local alias for that name in the same script file, that alias is used (see the note)
* if none of the above is true, then the order in which you loaded the script is used. mIRC looks for the first non local alias in the order 1-or-more aliases files in the Alt+D tab of the script editor, followed by the scripts of the Alt+R tab in the order they're loaded. If you have the same non-local alias name defined twice in the same file, the 2nd one cannot be executed. If you have the same non-local alias defined in 2 different script files, it's possible to change that order from the script editor's menu (file/order).
* If none is found, then mIRC check if this is a built-in command name
* If still no match, then it sends the command to the server, which sends back RAW numeric 421 if it's an invalid server command

'''Note:''': The command line of a timer behaves as if it's inside the script from where it was launched. It can execute local aliases within that script, and give preference to non-local aliases located in that same script. The alias on a higher scriptline is executed regardless whether the top or bottom alias is -l local.

[maroon edit: this next paragraph doesn't make sense to me, but i want other opinions before i change it]
'''Note''': This means that local aliases only guarantees no other script file can call the alias, they does not help making sure that alias is called if a code in the same script file calls your alias: a non local alias also guarantees the alias is called if it's in the same script file, the order in which you loaded the script won't matter. 

== See also ==
* {{mIRC|$isalias}}
* {{mIRC|$script}}
* {{mIRC|$scriptline}}
* {{mIRC|$result}}
* {{mIRC|/return}}
* {{mIRC|/returnex}}
* {{mIRC|$color}}
* {{mIRC|/echo}}
* {{mIRC|$v1}}