Latest revision |
Your text |
Line 2: |
Line 2: |
| 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]]. | | 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: === | + | ==== Syntax: ==== |
| Aliases have the following basic syntax: | | Aliases have the following basic syntax: |
| | | |
Line 51: |
Line 51: |
| '''Note:''' Aliases from the aliases tab can freely call aliases from the remote tab and vice versa. | | '''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 === | | === Aliases Prefixes === |
Line 59: |
Line 56: |
| ==== Command Prefixes ==== | | ==== Command Prefixes ==== |
| | | |
− | ===== . prefix (silencing) =====
| + | = . prefix (silencing) = |
| | | |
| You can prefix your command call by a dot '.' to prevent mIRC from displaying its typical message, such as {{mIRC|/timer|.timer}}. | | 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) = |
− | | |
− | ===== ! 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. | | 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 ====
| + | == 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) =====
| + | = / 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 '.' | | 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) =====
| + | = ~ 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.
| + | 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. |
− | 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 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 == | | == Commands == |
Line 139: |
Line 123: |
| | | |
| <pre>hello there!</pre> | | <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 == | | == Identifiers Properties == |
Line 217: |
Line 187: |
| <pre>/logfind *kicked* | | <pre>/logfind *kicked* |
| * Logfind Match: [12:33] * Foo was kicked by *.example.com (Flooding (Limit is 12 lines per 10 seconds))</pre> | | * 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: == | | == Additional alias features: == |
Line 310: |
Line 226: |
| <h3 id="shortcuts">Shortcuts and Function Keys</h3> | | <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. | + | 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: | | For Example: |
| | | |
− | <pre>alias SF1 { | + | <syntaxhighlight lang="mIRC">alias SF1 { |
| echo -a Shift+F1 was pressed! | | echo -a Shift+F1 was pressed! |
− | } | + | }</syntaxhighlight> |
− | 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 == | | == Local Aliases == |
Line 342: |
Line 253: |
| }</syntaxhighlight> | | }</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. | + | 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:
| |
− | | |
− | * files are read from top to bottom and only the first found alias in file will be used
| |
− | * if the call is made from a script and there is an alias for that name in the script file, that alias is used (regardless if the alias is local or not)
| |
− | * 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 alias name defined twice in the same file, the 2nd one cannot be executed.
| |
− | * If none is found, then mIRC check if this is a built-in command name
| |
− | * If still no match and if it was a command call, 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 will execute aliases found in the file first.
| |
| | | |
− | == See also ==
| + | [[Category:mIRC|aliases]] |
− | * {{mIRC|$isalias}}
| |
− | * {{mIRC|$script}}
| |
− | * {{mIRC|$scriptline}}
| |
− | * {{mIRC|$result}}
| |
− | * {{mIRC|/return}}
| |
− | * {{mIRC|/returnex}}
| |
− | * {{mIRC|$color}}
| |
− | * {{mIRC|/echo}}
| |
− | * {{mIRC|$v1}}
| |