Revision as of 03:30, 8 November 2018

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

Syntax:

Aliases have the following basic syntax:

;single-line alias
alias aliasName /commands
 
;multi-line alias
alias aliasName {
  /commands
}

A simple hello world alias would look like this:

Alias hello {
  echo -a Hello World!
}

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:

//hello

This will print:

Hello World!

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:

/example A B C D
; or
... $example(A, B, C, D)

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 /tokenize command. More information about $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:

aliasName {
  ; commands
}

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

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

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
}

We can run the code using the follow statement:

/example A B C D

This will produce the following result:

4 arguments passed
The first 3 arguments are:
Arg1 = A
Arg2 = B
Arg3 = C

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.

;This identifier does not need any arguments
echo -a $me
;This identifier requires that we pass it some arguments:
echo -a $calc(1 + 1)

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:

alias example {
  return hello there!
}

we can call that identifier using like this:

//echo -a $example

This will print:

hello there!

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.

; converts degrees to radians
alias convert {
  return $calc($1 * $pi / 180)
}

For example:

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

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

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

For example:

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

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:

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

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

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

We can also call it as a command:

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

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.

alias example {
  foo
  echo -a $result
}
alias foo {
  return result!
}

Output:

/example
result!

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:

alias example {
  if ($show) {
    ;Indicate we are doing something
    echo -a we are doing something
    ;Show more debug info.
  }
  ;do something
}

Output:

/example
we are doing something
/.example

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

Shortcuts and Function Keys

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:

alias SF1 {
  echo -a Shift+F1 was pressed!
}

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.

Alias -l <name> {
  ;code
}

Exposing private and public functionality

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

alias -l example {
  echo -a Local code called me!
}
alias example {
  echo -a Non-local script called me!
}

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.

Alias order

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

• 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 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 files, if you have the same alias defined twice in the same file, it's possible to change that order from the script editor's menu

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.