Manual:Trigger Engine - Revision history

Slysven: /* "multiline / AND" and "OR" Condition Triggers */ Reposition OR-trigger example image in better place

2024-11-20T20:43:28Z

"multiline / AND" and "OR" Condition Triggers: Reposition OR-trigger example image in better place

Dt192: /* Perl Regex */

2024-06-26T19:15:37Z

Perl Regex

Dt192: /* Perl Regex */

2024-06-26T19:15:02Z

Perl Regex

Zooka: /* Perl Regex */

2024-05-17T05:56:50Z

Perl Regex

Zooka: /* Lua Syntax Primer: Expressions */ acronym fix

2024-04-24T10:51:18Z

Lua Syntax Primer: Expressions: acronym fix

Zooka: /* Trigger Engine */ moved up in page

2024-04-23T11:04:18Z

Trigger Engine: moved up in page

Zooka: /* Testing triggers */

2024-04-23T11:02:58Z

Testing triggers

Zooka: /* Testing triggers */

2024-04-23T11:02:42Z

Testing triggers

Zooka: /* Named patterns */ rewrite

2024-04-23T11:01:53Z

Named patterns: rewrite

Zooka: /* Named capturing groups in Perl regex triggers and tempRegexTrigger */ removed, merged into named patterns

2024-04-23T10:59:55Z

Named capturing groups in Perl regex triggers and tempRegexTrigger: removed, merged into named patterns

@@ Line 312: / Line 312: @@
 OR-Triggers execute when '''any one of''' their conditions is true. To make OR-Triggers you simply have to add a few conditions to the conditions list e.g. in our example: "pond", "frog", "Plop". The trigger will now also execute on lines like this: "A frog is green" or "You hear a loud Plop!" because "frog" matched in the first line and "Plop" matched in the second line.
 Multiline / AND triggers execute when '''all of''' their conditions are true. Taking the previous patterns of "pond", "frog", "Plop" and clicking the 'AND' button will make the trigger not fire on "A frog is green" or "You hear a loud Plop!" anymore, because all 3 patterns don't match. It however would fire on "In a brown pond, the frog said Plop!" because all 3 patterns matched. As you might have noticed, all 3 patterns are on the same line: this means that in a multiline/AND trigger, the next pattern starts matching on the same line to make this work.
@@ Line 318: / Line 320: @@
 The simplest form of AND-Triggers in Mudlet are Trigger Chains or Filter Chains, whatever you’d like to call it.
 [[File:AND trigger.png|thumb|All of the patterns have to match for it to fire. This is a common example of a "shielded regex" - don't run the expensive regex all the time unless you really need to, and match on the faster begin of line the majority of the time|alt=|none|666x666px]]

@@ Line 112: / Line 112: @@
 | <b>String:</b> || The frog swims in the pond.
 |-
-| <b>Outcome:</b> || <span style="color: green;">match (\w matches pond, and is also saved to <nowiki>matches[2]</nowiki> variable)</span>
+| <b>Outcome:</b> || <span style="color: green;">match (\w+ matches pond, and is also saved to <nowiki>matches[2]</nowiki> variable)</span>
 |}
 ----
@@ Line 121: / Line 121: @@
 | <b>String:</b> || The frog swims in the swamp.
 |-
-| <b>Outcome:</b> || <span style="color: green;">match (\w matches swamp)</span>
+| <b>Outcome:</b> || <span style="color: green;">match (\w+ matches swamp)</span>
 |}
 ----
@@ Line 130: / Line 130: @@
 | <b>String:</b> || The fish swims in the pond.
 |-
-| <b>Outcome:</b> || <span style="color: red;">no match (fish should be changed to a regex pattern \w)</span>
+| <b>Outcome:</b> || <span style="color: red;">no match (fish should be changed to a regex pattern \w+)</span>
 |}
 ----

@@ Line 100: / Line 100: @@
 === Perl Regex ===
-This trigger type will match text using Regular Expressions (Regex). Regex in Perl is a special text string for describing a search pattern within a given text.  For example <nowiki>\w</nowiki> is used to match a single word, or <nowiki>\d</nowiki> is used to match a single digit.
+This trigger type will match text using Regular Expressions (Regex). Regex in Perl is a special text string for describing a search pattern within a given text.  For example <nowiki>\w+</nowiki> is used to match a single word, or <nowiki>\d</nowiki> is used to match a single digit.
 Pattern matching also allows the match to be saved in the <nowiki>matches</nowiki> table variable if enclosed in parentheses.  <nowiki>matches[1]</nowiki> contains the entire line of the trigger whereas <nowiki>matches[2]</nowiki> contains the first regex pattern (in our examples <nowiki>pond</nowiki> or <nowiki>swamp</nowiki>).
@@ Line 108: / Line 108: @@
 {|
 |-
-| <b>Pattern:</b> || The frog swims in the (\w).
+| <b>Pattern:</b> || The frog swims in the (\w+).
 |-
 | <b>String:</b> || The frog swims in the pond.
@@ Line 117: / Line 117: @@
 {|
 |-
-| <b>Pattern:</b> || The frog swims in the (\w).
+| <b>Pattern:</b> || The frog swims in the (\w+).
 |-
 | <b>String:</b> || The frog swims in the swamp.
@@ Line 126: / Line 126: @@
 {|
 |-
-| <b>Pattern:</b> || The frog swims in the (\w).
+| <b>Pattern:</b> || The frog swims in the (\w+).
 |-
 | <b>String:</b> || The fish swims in the pond.

@@ Line 121: / Line 121: @@
 | <b>String:</b> || The frog swims in the swamp.
 |-
-| <b>Outcome:</b> || <span style="color: green;">match (\w matches pond)</span>
+| <b>Outcome:</b> || <span style="color: green;">match (\w matches swamp)</span>
 |}
 ----

@@ Line 218: / Line 218: @@
 ==== Lua Syntax Primer: Expressions ====
-{{note}} Mudlet used to only allow the boolean ''true'' value as the return value to consider the pattern to have been a match. It has since been improved to allow any value Lua would consider true - but if you see any LFCs making use of ''and true or false'' at the end, that'd be why.
+{{note}} Mudlet used to only allow the boolean ''true'' value as the return value to consider the pattern to have been a match. It has since been improved to allow any value Lua would consider true - but if you see any Lua Function Conditions (LFC) making use of ''and true or false'' at the end, that'd be why.
 <syntaxhighlight lang="lua">
@@ Line 230: / Line 230: @@
 The operators ''and'' and ''or'' behave differently in Lua than in most other programming languages as they are not guaranteed to return a boolean value.[http://hisham.hm/2011/05/04/luas-and-or-as-a-ternary-operator/]
-Lua function conditions effectively means that you run the Lua code they represent on every single line that is received from the game, unless the LFCs are part of a multi-condition trigger, in which case the LFCs would only be run when they would be the current test-condition of their respective trigger state. LFCs are implemented in such a way that the trigger engine only calls the compiled byte code, but running as few scripts as possible is always the best idea. LFCs are nice and handy, and for most people the performance aspect will not be relevant at all.
+Lua Function Conditions (LFC) effectively means that you run the Lua code they represent on every single line that is received from the game, unless the LFCs are part of a multi-condition trigger, in which case the LFCs would only be run when they would be the current test-condition of their respective trigger state. LFCs are implemented in such a way that the trigger engine only calls the compiled byte code, but running as few scripts as possible is always the best idea. LFCs are nice and handy, and for most people the performance aspect will not be relevant at all.
 === Line Spacer ===

@@ Line 41: / Line 41: @@
 resetFormat()
 </syntaxhighlight>
 == Pattern Matching Types ==
@@ Line 325: / Line 354: @@
 Imagine the following scenario: You want to collect some berries. You know that the room contains some berries if the room description contains the words "You are inside a forest. There are some strawberries." or "You are inside a forest. There are some blackberries." and there are always only one kind of berry in the room. You make a new substring trigger for this line, but instead of choosing a regular trigger, you chose to add a new trigger group. Now you add <code>You are inside a forest\. There are some (\w+)\.</code> as an Regular Expression to the expression list of the trigger group. '''<span style="color:blue">When adding conditions to a trigger group, the trigger group turns from an organizational unit into a filter unit, if the "filter" option is checked.</span>''' From now on this folder is a filter and will only let its matches pass through. In our case this is exactly what we want, because we don’t want to collect all sorts of berries, but we only want 2 particular kinds, namely, strawberries and blackberries, and we know that these berries can only be trusted if they are picked inside a forest as other areas may contain contaminated berries. Now you add two regular triggers to our berry-in-the-forest filter - one containing the condition: <code>strawberries</code> and the other one <code>blackberries</code>. Then we add the commands to pick the particular kind of berry to both triggers (send field). Now what happens is that as soon as a room description reads "You are inside a forest. There are some strawberries/blackberries." the filter will let the kind of berry pass through to our two berry triggers and they will issue commands to pick berries, if there are such berries. However, in any other situation the words "strawberries" and "blackberries" will NOT trigger a pick - only in the above scenario when the filter parent’s condition is met. This is a very nice way to solve complicated problems with a few easy filter chains. This example is trivial, but using filter chains will rapidly show you how formerly complicated things that could only be solved with very complicated regular expressions can be solved easily now with a couple of filter chains.
 == Named Capture Patterns ==

@@ Line 326: / Line 326: @@
 Imagine the following scenario: You want to collect some berries. You know that the room contains some berries if the room description contains the words "You are inside a forest. There are some strawberries." or "You are inside a forest. There are some blackberries." and there are always only one kind of berry in the room. You make a new substring trigger for this line, but instead of choosing a regular trigger, you chose to add a new trigger group. Now you add <code>You are inside a forest\. There are some (\w+)\.</code> as an Regular Expression to the expression list of the trigger group. '''<span style="color:blue">When adding conditions to a trigger group, the trigger group turns from an organizational unit into a filter unit, if the "filter" option is checked.</span>''' From now on this folder is a filter and will only let its matches pass through. In our case this is exactly what we want, because we don’t want to collect all sorts of berries, but we only want 2 particular kinds, namely, strawberries and blackberries, and we know that these berries can only be trusted if they are picked inside a forest as other areas may contain contaminated berries. Now you add two regular triggers to our berry-in-the-forest filter - one containing the condition: <code>strawberries</code> and the other one <code>blackberries</code>. Then we add the commands to pick the particular kind of berry to both triggers (send field). Now what happens is that as soon as a room description reads "You are inside a forest. There are some strawberries/blackberries." the filter will let the kind of berry pass through to our two berry triggers and they will issue commands to pick berries, if there are such berries. However, in any other situation the words "strawberries" and "blackberries" will NOT trigger a pick - only in the above scenario when the filter parent’s condition is met. This is a very nice way to solve complicated problems with a few easy filter chains. This example is trivial, but using filter chains will rapidly show you how formerly complicated things that could only be solved with very complicated regular expressions can be solved easily now with a couple of filter chains.
-== Testing triggers ==
+== Testing Triggers ==
 You can test your triggers with the <code>`echo</code> alias from the command line.  This requires the echo package, which is installed by default on a new profile.

@@ Line 336: / Line 336: @@
 </code>
-Or from from your lua code using [[Manual:Miscellaneous_Functions#feedTriggers|feedTriggers]]
+Or from your Lua code using [[Manual:Miscellaneous_Functions#feedTriggers|feedTriggers]]
 <syntaxhighlight lang="lua">

@@ Line 353: / Line 353: @@
 Alternatively, you can also record a replay and play it - triggers will be matched on it.
-== Named patterns ==
+== Named Capture Patterns ==
 You can use named patterns - that is, giving your captures names instead of [2], [3], [4] numbers - by adding '''?<variablename>''' to your capture in Mudlet 4.11+:
@@ Line 371: / Line 371: @@
 You can programatically check if your Mudlet supports this feature with <code>mudlet.supports.namedPatterns</code>.
 [[Category:Mudlet  Manual]]

← Older revision		Revision as of 10:59, 23 April 2024
Line 325:		Line 325:

	Imagine the following scenario: You want to collect some berries. You know that the room contains some berries if the room description contains the words "You are inside a forest. There are some strawberries." or "You are inside a forest. There are some blackberries." and there are always only one kind of berry in the room. You make a new substring trigger for this line, but instead of choosing a regular trigger, you chose to add a new trigger group. Now you add <code>You are inside a forest\. There are some (\w+)\.</code> as an Regular Expression to the expression list of the trigger group. '''<span style="color:blue">When adding conditions to a trigger group, the trigger group turns from an organizational unit into a filter unit, if the "filter" option is checked.</span>''' From now on this folder is a filter and will only let its matches pass through. In our case this is exactly what we want, because we don’t want to collect all sorts of berries, but we only want 2 particular kinds, namely, strawberries and blackberries, and we know that these berries can only be trusted if they are picked inside a forest as other areas may contain contaminated berries. Now you add two regular triggers to our berry-in-the-forest filter - one containing the condition: <code>strawberries</code> and the other one <code>blackberries</code>. Then we add the commands to pick the particular kind of berry to both triggers (send field). Now what happens is that as soon as a room description reads "You are inside a forest. There are some strawberries/blackberries." the filter will let the kind of berry pass through to our two berry triggers and they will issue commands to pick berries, if there are such berries. However, in any other situation the words "strawberries" and "blackberries" will NOT trigger a pick - only in the above scenario when the filter parent’s condition is met. This is a very nice way to solve complicated problems with a few easy filter chains. This example is trivial, but using filter chains will rapidly show you how formerly complicated things that could only be solved with very complicated regular expressions can be solved easily now with a couple of filter chains.		Imagine the following scenario: You want to collect some berries. You know that the room contains some berries if the room description contains the words "You are inside a forest. There are some strawberries." or "You are inside a forest. There are some blackberries." and there are always only one kind of berry in the room. You make a new substring trigger for this line, but instead of choosing a regular trigger, you chose to add a new trigger group. Now you add <code>You are inside a forest\. There are some (\w+)\.</code> as an Regular Expression to the expression list of the trigger group. '''<span style="color:blue">When adding conditions to a trigger group, the trigger group turns from an organizational unit into a filter unit, if the "filter" option is checked.</span>''' From now on this folder is a filter and will only let its matches pass through. In our case this is exactly what we want, because we don’t want to collect all sorts of berries, but we only want 2 particular kinds, namely, strawberries and blackberries, and we know that these berries can only be trusted if they are picked inside a forest as other areas may contain contaminated berries. Now you add two regular triggers to our berry-in-the-forest filter - one containing the condition: <code>strawberries</code> and the other one <code>blackberries</code>. Then we add the commands to pick the particular kind of berry to both triggers (send field). Now what happens is that as soon as a room description reads "You are inside a forest. There are some strawberries/blackberries." the filter will let the kind of berry pass through to our two berry triggers and they will issue commands to pick berries, if there are such berries. However, in any other situation the words "strawberries" and "blackberries" will NOT trigger a pick - only in the above scenario when the filter parent’s condition is met. This is a very nice way to solve complicated problems with a few easy filter chains. This example is trivial, but using filter chains will rapidly show you how formerly complicated things that could only be solved with very complicated regular expressions can be solved easily now with a couple of filter chains.
−
−	~~==Named capturing groups in Perl regex triggers and tempRegexTrigger==~~
−
−	Since Mudlet 4.11+ you can use named capturing groups in , so you can access your matches not only by numeric index of your capturing group but also under certain name. It is especially useful when you have multiple patterns with different ordering of capture groups.
−
−	~~Let's assume we want to capture name and class of character, but MUD outputs it two ways.~~
−	~~# <code>My name is Dargoth. My class is a warrior.</code>~~
−	~~# <code>I am a wizard and my name is Delwing.</code>~~
−
−	~~Instead of creating two different triggers we can create only one containing alternative matching patterns:~~
−
−	~~# <code>^My name is (?<name>\w+)\. My class is a (?<class>\w+)\.</code>~~
−	~~# <code>^I am a (?<class>\w+)\ and my name is (?<name>\w+)\.</code>~~
−
−	Notice that class and name come in different order, therefore in first case we will have name under matches[2] and in second case under matches[3]. With named capture groups in both cases we will have name available under matches.name and class under matches.class.
−
−	~~Code example to handle named matches above:~~
−	~~<syntaxhighlight lang="lua">~~
−	~~echo("Name: " .. matches.name .. "\n")~~
−	~~echo("Class: " .. matches.class .. "\n")~~
−	~~</syntaxhighlight>~~
−
−	~~To verify whether named groups are available you can use flag <code>mudlet.supports.namedGroups</code>.~~

	== Testing triggers ==		== Testing triggers ==