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.


== 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}}.

=== ! 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 ==

=== / 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) ===

You can force a call to an identifier to return $null if it's not a built-in identifier by using the '~' prefix, $~sup will always return $null.

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

=== 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>

=== 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>

== 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 and S can be used for the Shift and Ctrl Key. For example SF1 is Shift+F1 keys.

For Example:

<syntaxhighlight lang="mIRC">alias SF1 {
  echo -a Shift+F1 was pressed!
}</syntaxhighlight>

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

[[Category:mIRC|aliases]]