Manual:Alias Engine - Revision history

AnotherContrivedUsername: /* Considerations */ noting that named capture groups are unsupported, explaining how to use modifiers for alias regexes.

2024-06-17T16:00:30Z

Considerations: noting that named capture groups are unsupported, explaining how to use modifiers for alias regexes.

Zooka: added an examples section

2024-03-08T22:59:23Z

added an examples section

Vadi: Clean up code

2022-12-25T19:52:06Z

Clean up code

Vadi: /* React on input - Mudlets Alias Engine */

2022-12-25T19:48:41Z

React on input - Mudlets Alias Engine

Vadi: Simplify introduction to aliases

2022-12-25T19:47:42Z

Simplify introduction to aliases

Atari2600tim: /* Default keybindings in the main window */ add Ctrl+F

2022-11-29T15:20:38Z

Default keybindings in the main window: add Ctrl+F

Vadi: /* Default keybindings in the main window */

2021-04-10T04:47:38Z

Default keybindings in the main window

Fosterwerks: fixed typos in alias command "pwb"

2021-04-03T17:37:01Z

fixed typos in alias command "pwb"

Demonnic: /* React on input - Mudlets Alias Engine */

2021-03-13T18:44:24Z

React on input - Mudlets Alias Engine

Kebap: rename MUD to game everywhere

2021-01-05T11:05:04Z

rename MUD to game everywhere

@@ Line 141: / Line 141: @@
 | Ctrl+F||Search for text in the main output window.
 |}
 [[Category:Mudlet Manual]]

@@ Line 77: / Line 77: @@
 </syntaxhighlight>
-== Default keybindings in the main window ==
+== Alias Examples ==
 {| {{table}} class="wikitable"
 | align="center" style="background:#f0f0f0;"|'''Keypress'''

@@ Line 26: / Line 26: @@
 Script is:
 <syntaxhighlight lang="lua">
-send( f"put { weapon } in { bag }" )
+send(f"put {weapon} in {bag}")
 </syntaxhighlight>
 Depending on the values of our variables weapon and bag the command "pwb" will be substituted with an appropriate command. To set your weapon and bag variables we use 2 more aliases: Alias to set the weapon: <code>uw (\w)+</code>
@@ Line 32: / Line 32: @@
 Script:
 <syntaxhighlight lang="lua">
-weapon = matches[2];
+weapon = matches[2]
 send( "wield " .. weapon )
 </syntaxhighlight>
@@ Line 50: / Line 50: @@
 <syntaxhighlight lang="lua">
 if bagIsFull then
-     send( f"put { weapon } in { spareBag }" )
+     send(f"put {weapon} in {spareBag}")
 else
-     send( f"put { weapon } in { bag }" )
+     send(f"put {weapon} in {bag}")
 end
 </syntaxhighlight>
@@ Line 59: / Line 59: @@
 Script:
 <syntaxhighlight lang="lua">
-send( "tell Jane " .. matches[2] )
+send("tell Jane " .. matches[2])
 </syntaxhighlight>
 Sadly, Jane is your fiancée and the one thing she is a vegetarian and absolutely hates all words that relate to meat. Luckily, you know enough about aliases by now to make her believe that you’d never ever even think about meat. So you head to your global function script (any script item will do as long as you define your variables '''<span style="color:blue">outside of</span>''' your function definitions. See the scripts chapter below for more information. In your script "my global functions" you add a Lua table containing a list of all of all words that a vegetarian might hate. For example:
 <syntaxhighlight lang="lua">
-happyJaneTable = { "meat", "burger", "steak", "hamburger", "chickenburger" }
+happyJaneTable = {"meat", "burger", "steak", "hamburger", "chickenburger"}
 </syntaxhighlight>
 Now you can upgrade your tell-jane script to automatically search our tell for all words that Jane might not like. In case such a word is found we substitute the entire tell with "How is the weather?".
 <syntaxhighlight lang="lua">
-for key, value in ipairs( happyJaneTable ) do     -- looking at each element of the list
+for key, value in ipairs(happyJaneTable) do       -- looking at each element of the list
      badWord = happyJaneTable[key]                 -- check out the Lua table chapter below for more info
-     begin, end = string.find( command, badWord )  -- begin holds the start position of the word, end* the end-position
+     begin, end = string.find(command, badWord)    -- begin holds the start position of the word, end* the end-position
      if begin ~= nil then                          -- we have found a bad word
-         send( "tell Jane How is the weather?" )
+         send("tell Jane How is the weather?")
          return
      end

@@ Line 4: / Line 4: @@
 {{note}} A screencast is available on getting started with aliases - [http://www.youtube.com/view_play_list?p=15A249142399F3CB&playnext=1&playnext_from=PL watch it]!
-In Mudlet software, there is a feature called "aliases" that allows you to set up certain phrases or commands that will automatically trigger certain actions or responses. These actions are defined using a specific type of language called "Perl regex expressions." Aliases only work on the input that the user types into the command line, while a separate feature called "triggers" works on the output that the game sends back. When you type a command and press enter, it is sent to the alias feature to see if it matches any of the phrases or commands that have been set up. If it does match, the alias will take over and either send a different command to the game or run a script (a set of instructions) that you have defined. This system is powerful because it gives you control over what happens when a certain phrase or command is entered. You can even change the user's input as it is being processed, allowing you to manipulate the command before it is sent to the game.
+Mudlet has a feature called "aliases" that allows you to set up certain phrases or commands that will automatically trigger certain actions or responses. These actions are defined using a specific type of language called "Perl regex expressions." Aliases only work on the input that the user types into the command line, while a separate feature called "triggers" works on the output that the game sends back. When you type a command and press enter, it is sent to the alias feature to see if it matches any of the phrases or commands that have been set up. If it does match, the alias will take over and either send a different command to the game or run a script (a set of instructions) that you have defined. This system is powerful because it gives you control over what happens when a certain phrase or command is entered. You can even change the user's input as it is being processed, allowing you to manipulate the command before it is sent to the game.
 [[File:alias-diagram.png|600px]]

@@ Line 4: / Line 4: @@
 {{note}} A screencast is available on getting started with aliases - [http://www.youtube.com/view_play_list?p=15A249142399F3CB&playnext=1&playnext_from=PL watch it]!
-Alias react on user input. Mudlet uses hierarchically ordered powerful Perl regex expression alias. We have explicitly chosen not to offer multi condition alias, alias chains or the same trigger types the trigger engine offers because this would be way over the top and is simply not needed for alias expansion - although it should be noted that the processes are closely related, except that aliases, '''i.e. input triggers''', operate on a different data stream, namely the user input stream, whereas triggers operate on the game output data stream. The only real difference between output triggers and input triggers is that input triggers can change the input stream they work on, whereas output triggers cannot change the stream itself - output triggers can change what is printed on the screen as a result of the stream, but they cannot change the stream itself. This is a fundamental difference and a deeper understanding is key to getting to grips with Mudlets alias engine. When you enter a command on the keyboard and press enter or return, the text that you have typed in the command line will be forwarded to the alias unit, i. e. the input trigger unit, in form of the Lua variable <span style="color:red">command</span>. This variable will be matched against all active alias in the hierarchy unless access to an alias branch is locked by the user or by a script. '''<span style="color:blue">If an alias matches, it will intercept the user command and the original command will be ignored.</span>''' Upon a match the clear text command is being send as a command to the game in replacement of the original command, if a clear text command has been specified by the <span style="color:blue">''user''</span> and the attached alias script is being executed. However, the initial command that the user has typed in the command line will <span style="color:blue font-weight:bold">not</span> be sent unless you do this as part of your script. Consequently, if you want your alias to send a command to the game, you’ll either have to specify a clear text command for simple cases or send commands via the attached alias script e.g. <code>send("kill monster")</code>. You may argue that you feel that it is unnecessary work to be forced to send a command replacement yourself, but this very fact makes our alias system way more powerful because it gives you complete control about what is happening. Why is this so? The initial user command is being held in the Lua variable <span style="color:red">command</span>. When this value changes within the alias unit processing chain, the initial user input that the aliases work on can be rewritten and changed in the process. Consequently, you can substitute the user input step by step - or alias by alias - without that anything happens as far as sending commands is being concerned unless you explicitly decide to do so.
+In Mudlet software, there is a feature called "aliases" that allows you to set up certain phrases or commands that will automatically trigger certain actions or responses. These actions are defined using a specific type of language called "Perl regex expressions." Aliases only work on the input that the user types into the command line, while a separate feature called "triggers" works on the output that the game sends back. When you type a command and press enter, it is sent to the alias feature to see if it matches any of the phrases or commands that have been set up. If it does match, the alias will take over and either send a different command to the game or run a script (a set of instructions) that you have defined. This system is powerful because it gives you control over what happens when a certain phrase or command is entered. You can even change the user's input as it is being processed, allowing you to manipulate the command before it is sent to the game.
 [[File:alias-diagram.png|600px]]

@@ Line 125: / Line 125: @@
 |-
 | Ctrl+Enter||Close split screen (scroll all the way to the bottom).
 |}
 [[Category:Mudlet Manual]]

@@ Line 124: / Line 124: @@
 | Ctrl+<Click>||Select the whole line.
 |-
-| Ctrl+Enter||Close split screen.
+| Ctrl+Enter||Close split screen (scroll all the way to the bottom).
 |}
 [[Category:Mudlet Manual]]

@@ Line 20: / Line 20: @@
 Let’s move on to a more complicated example that is needed very often.
-We want our script to automatically put the weapon in the correct bag as we have many bags and many weapons. The pattern stays the same. ^pwb The ^ at the beginning of the line means that the command starts with pwd and no other letter in front of this. If we define our pattern more clearly, the pattern will match less often. Without the ^ the alias will match and the alias script will always be run whenever there is the sequence of letters "pwd" in your commands. This may not always be what you want. This is why it’s usually a good idea to make the pattern definition as exact as needed by being less general. The more general the pattern, the more often it will match.
+We want our script to automatically put the weapon in the correct bag as we have many bags and many weapons. The pattern stays the same. ^pwb The ^ at the beginning of the line means that the command starts with pwd and no other letter in front of this. If we define our pattern more clearly, the pattern will match less often. Without the ^ the alias will match and the alias script will always be run whenever there is the sequence of letters "pwb" in your commands. This may not always be what you want. This is why it’s usually a good idea to make the pattern definition as exact as needed by being less general. The more general the pattern, the more often it will match.
 Back to our task: The pattern is <code>^pwb</code>. Let’s assume that we have defined 2 variables in some other script. The variable "weapon" is the weapon we use and the variable "bag" is the name of the bag. NOTE: In Mudlet global variables can be accessed anywhere from within Mudlet scripts - no matter if they have been defined in a trigger script, in an alias script or in a key or button script. As soon as it’s been defined it somewhere it is usable. To make sure that a variable is local only, i. e. cannot be referenced from other scripts, you have to use the keyword local in front of your variable definition. Back to our alias: Pattern is: <code>^pwb</code>
@@ Line 28: / Line 28: @@
 send( f"put { weapon } in { bag }" )
 </syntaxhighlight>
-Depending on the values of our variables weapon and bag the command "pwd" will be substituted with an appropriate command. To set your weapon and bag variables we use 2 more aliases: Alias to set the weapon: <code>uw (\w)+</code>
+Depending on the values of our variables weapon and bag the command "pwb" will be substituted with an appropriate command. To set your weapon and bag variables we use 2 more aliases: Alias to set the weapon: <code>uw (\w)+</code>
 Script:

@@ Line 4: / Line 4: @@
 {{note}} A screencast is available on getting started with aliases - [http://www.youtube.com/view_play_list?p=15A249142399F3CB&playnext=1&playnext_from=PL watch it]!
-Alias react on user input. Mudlet uses hierarchically ordered powerful Perl regex expression alias. We have explicitly chosen not to offer multi condition alias, alias chains or the same trigger types the trigger engine offers because this would be way over the top and is simply not needed for alias expansion - although it should be noted that the processes are closely related, except that aliases, '''i.e. input triggers''', operate on a different data stream, namely the user input stream, whereas triggers operate on the MUD output data stream. The only real difference between output triggers and input triggers is that input triggers can change the input stream they work on, whereas output triggers cannot change the stream itself - output triggers can change what is printed on the screen as a result of the stream, but they cannot change the stream itself. This is a fundamental difference and a deeper understanding is key to getting to grips with Mudlets alias engine. When you enter a command on the keyboard and press enter or return, the text that you have typed in the command line will be forwarded to the alias unit, i. e. the input trigger unit, in form of the Lua variable <span style="color:red">command</span>. This variable will be matched against all active alias in the hierarchy unless access to an alias branch is locked by the user or by a script. '''<span style="color:blue">If an alias matches, it will intercept the user command and the original command will be ignored.</span>''' Upon a match the clear text command is being send as a command to the MUD in replacement of the original command, if a clear text command has been specified by the <span style="color:blue">''user''</span> and the attached alias script is being executed. However, the initial command that the user has typed in the command line will <span style="color:blue font-weight:bold">not</span> be sent unless you do this as part of your script. Consequently, if you want your alias to send a command to the MUD, you’ll either have to specify a clear text command for simple cases or send commands via the attached alias script e.g. <code>send("kill monster")</code>. You may argue that you feel that it is unnecessary work to be forced to send a command replacement yourself, but this very fact makes our alias system way more powerful because it gives you complete control about what is happening. Why is this so? The initial user command is being held in the Lua variable <span style="color:red">command</span>. When this value changes within the alias unit processing chain, the initial user input that the aliases work on can be rewritten and changed in the process. Consequently, you can substitute the user input step by step - or alias by alias - without that anything happens as far as sending commands is being concerned unless you explicitly decide to do so.
+Alias react on user input. Mudlet uses hierarchically ordered powerful Perl regex expression alias. We have explicitly chosen not to offer multi condition alias, alias chains or the same trigger types the trigger engine offers because this would be way over the top and is simply not needed for alias expansion - although it should be noted that the processes are closely related, except that aliases, '''i.e. input triggers''', operate on a different data stream, namely the user input stream, whereas triggers operate on the game output data stream. The only real difference between output triggers and input triggers is that input triggers can change the input stream they work on, whereas output triggers cannot change the stream itself - output triggers can change what is printed on the screen as a result of the stream, but they cannot change the stream itself. This is a fundamental difference and a deeper understanding is key to getting to grips with Mudlets alias engine. When you enter a command on the keyboard and press enter or return, the text that you have typed in the command line will be forwarded to the alias unit, i. e. the input trigger unit, in form of the Lua variable <span style="color:red">command</span>. This variable will be matched against all active alias in the hierarchy unless access to an alias branch is locked by the user or by a script. '''<span style="color:blue">If an alias matches, it will intercept the user command and the original command will be ignored.</span>''' Upon a match the clear text command is being send as a command to the game in replacement of the original command, if a clear text command has been specified by the <span style="color:blue">''user''</span> and the attached alias script is being executed. However, the initial command that the user has typed in the command line will <span style="color:blue font-weight:bold">not</span> be sent unless you do this as part of your script. Consequently, if you want your alias to send a command to the game, you’ll either have to specify a clear text command for simple cases or send commands via the attached alias script e.g. <code>send("kill monster")</code>. You may argue that you feel that it is unnecessary work to be forced to send a command replacement yourself, but this very fact makes our alias system way more powerful because it gives you complete control about what is happening. Why is this so? The initial user command is being held in the Lua variable <span style="color:red">command</span>. When this value changes within the alias unit processing chain, the initial user input that the aliases work on can be rewritten and changed in the process. Consequently, you can substitute the user input step by step - or alias by alias - without that anything happens as far as sending commands is being concerned unless you explicitly decide to do so.
 [[File:alias-diagram.png|600px]]
-The example in the diagram above shows 2 matching aliases, but only one of them sends commands to the MUD - and only if the player is healthy enough to attack the opponent. The other alias that matched the user input (enemy) choses a fitting opponent and sets the variable enemy accordingly, otherwise it issues a warning that attacking one of the available enemies would be too dangerous.
+The example in the diagram above shows 2 matching aliases, but only one of them sends commands to the game - and only if the player is healthy enough to attack the opponent. The other alias that matched the user input (enemy) choses a fitting opponent and sets the variable enemy accordingly, otherwise it issues a warning that attacking one of the available enemies would be too dangerous.
-For an alias to match the command text the same rules as explained above in the trigger section apply. However, to simplify matters there is only one alias type. As alias are not performance critical we could reduce the amount of trigger types to just Perl regex as this type can do it all and performance is no issue with alias as the amount of data is much less. Even if you type like a madman you’ll never get close to sending the same amount of text to the MUD than the amount of text the MUD sends back to you.
+For an alias to match the command text the same rules as explained above in the trigger section apply. However, to simplify matters there is only one alias type. As alias are not performance critical we could reduce the amount of trigger types to just Perl regex as this type can do it all and performance is no issue with alias as the amount of data is much less. Even if you type like a madman you’ll never get close to sending the same amount of text to the game than the amount of text the game sends back to you.
-What does it mean that a regex is true or "matched"? A trigger or an alias fires - or executes its commands/script - when the text matches the pattern of the trigger or alias. In most cases this means that the text contains the trigger/alias pattern. If the regex pattern is <code>reen</code> then a text "The green house" will match because "reen" is contained in the text. More complex regex patterns can also hold information on where in the text a certain pattern must occur in order to match. <code>^tj</code> only matches when the letters "tj" occur at the beginning of the text. Consequently, a text like "go tj" would not match. Regex patterns can also capture data like numbers, sequences of letters, words etc. at certain positions in the text. This is very useful for MUD related scripting and this is why it is explained below.
+What does it mean that a regex is true or "matched"? A trigger or an alias fires - or executes its commands/script - when the text matches the pattern of the trigger or alias. In most cases this means that the text contains the trigger/alias pattern. If the regex pattern is <code>reen</code> then a text "The green house" will match because "reen" is contained in the text. More complex regex patterns can also hold information on where in the text a certain pattern must occur in order to match. <code>^tj</code> only matches when the letters "tj" occur at the beginning of the text. Consequently, a text like "go tj" would not match. Regex patterns can also capture data like numbers, sequences of letters, words etc. at certain positions in the text. This is very useful for game related scripting and this is why it is explained below.
 Let’s get back to alias. We start with a simple example.
-We want Mudlet to send "put weapon in bag" whenever we type "pwb". Consequently, the pattern is <code>pwb</code> and as the task is so simple it’s enough to enter "put weapon in bag" in the send field. Then we click on save to save the changes and activate the alias by clicking on the padlock icon. Then we leave the trigger editor and test our new alias. After typing "pwb" and pressing return Mudlet will send the command "put weapon in bag" to the MUD.
+We want Mudlet to send "put weapon in bag" whenever we type "pwb". Consequently, the pattern is <code>pwb</code> and as the task is so simple it’s enough to enter "put weapon in bag" in the send field. Then we click on save to save the changes and activate the alias by clicking on the padlock icon. Then we leave the trigger editor and test our new alias. After typing "pwb" and pressing return Mudlet will send the command "put weapon in bag" to the game.
 Let’s move on to a more complicated example that is needed very often.