MUSHclient documentation: dialog IDD_EDIT

Edit trigger

Edit trigger
When a trigger matches MUSHclient does not evaluate any further triggers (unless "Keep Evaluating" is checked). Thus a trigger can be used as a "blocker" to stop further triggers down the list from being processed. Triggers with lower sequence numbers are evaluated before triggers with higher sequence numbers. Thus, use sequence numbers to control the evaluating sequence. Triggers with the same sequence number are evaluated in an undefined order. Trigger: This is the text that you are expecting from the MUD. If it is matched on exactly, then the text in the "send" box is acted upon and your script (if any) is called. (...) Click to edit the trigger text in a larger window. If the trigger is a regular expression the larger window also has an extra "helper" button to assist you in adding regular expression items. Match: (colour) on (colour) You can make a trigger match a particular colour line by setting these options. Leave the colours at "(any)" to match on any colour. You can also match on a line in bold/italic/inverse or any combination of these. These check-boxes are "tri-state", which means they can be: 1. Unchecked (the line must not be bold, for example) 2. Checked (the line must be bold, for example) 3. Greyed out (it doesn't matter if the line is bold or not) The first character of the matching text is checked for the specified colour. Bold Check to match if the first character of the matching text is bold. Uncheck if the first character must not be bold. Greyed out if you don't care. Italic Check to match if the first character of the matching text is italic. Uncheck if the first character must not be italic. Greyed out if you don't care. Inverse Check to match if the first character of the matching text is inverse. Uncheck if the first character must not be inverse. Greyed out if you don't care. Send: What to send to the "send" destination. The default send destination is back to the MUD. You can use %1 to match the first wildcard, %2 to match the second wildcard, and so on up to %9. For wildcards above 9 you can use %<n> (for example, %<50> for wildcard 50). For named wildcards you can use %<name> (for example, %<mob> for a wildcard with the name "mob"). Named wildcards are produced by using a regular expression and a group like: (?P<mob>.+?) %0 represents the whole matching text. Use %% to represent a single % symbol. You can also use %C to insert the contents of the Clipboard, and %N to insert the current trigger's name (label). If you are sending to script then any quotes or other special characters in the send text (inside the wildcard contents) are "escaped" appropriately for the script language you are using. (...) Click to edit the send text in a larger box. Alternatively press Alt+Enter to open the editing dialog box. Enabled If checked, the trigger is enabled (active). Ignore case If checked, the trigger match is case insensitive. If not checked, the "case" of the matching text must agree exactly. Omit from log file If checked, the matching line is not logged to the log file (if open). Omit from output If checked, the matching line is omitted from the output window. Keep evaluating If checked, the same line is checked against further triggers. If unchecked the first matching trigger cancels trigger evaluation. You can change the order in which triggers are evaluated by amending the sequence field. Regular expression If checked, the trigger match text is a regular expression. See "regular expressions" in the help for more information. You can convert an "ordinary" trigger to a regular expression by clicking the "Convert to Regular Expression" box. Then you can edit the regular expression to customise it. Repeat on same line If checked, the trigger is matched repeatedly against the same line (this only applies to regular expressions). This lets you colour individual words which might appear more than once on a line. Expand variables If expand variables is on (checked) then a variable name in the format @name is expanded. To put a @ symbol itself in the trigger, use two @@. Here is an example of such an trigger: unlock @direction For this trigger to work you would need a variables, "direction". You can set variables by using the configuration dialog box, or through a scripting command (if scripting is enabled), like this: `/SetVariable ("direction", "north")` If you want to use variables inside regular expressions and not have special characters "fixed" by putting backslashes inside them, use the syntax: `@!variable` Temporary If checked, the trigger will not be saved to the world file. In other words, it is a temporary one only for use in this session. Multi-line, match ... lines. If checked, this trigger will match multiple lines, starting with the current line (the most recently received), and including the number of lines specified in the adjacent box. For multi-line triggers MUSHclient assembles a "block of text" which is the specified number of lines, working backwards from the current line, each one ending with a newline character (assembled in the order in which they arrived, of course). This text block is then passed to the regular expression handler to see if it matches. The number of lines is lines with a newline at the end of the, not necessarily the number of lines you see on the screen. For instance, if the MUD sent some 200-character lines that line-wrapped, each line is counted as one line, even if you see four lines on the screen. A simple example would be to match on: `You are hungry. You are thirsty.` To match this you might have the regular expression: `Match: ^You are hungry\.\nYou are thirsty\.\n\z` The \n represents the "newline" character (hex 0A) between the two lines, the \. is a single period (at the end of the sentences) and the \z is an "anchor" to the end of the text block. The \z is not really necessary for this example, but could be useful for longer ones. For this example the "number of lines" would be 2, as you are trying to match a 2-line block. A more complex example is to match your inventory, which might be: `You are carrying: a magic mushroom a torch a dragonskin a bag recall scroll` Note the blank line at the end of the inventory. A matching trigger might be: `Match: ^You are carrying:\n(([ ]{5}.\n))[^ ]\z` This matches "You are carrying" followed by a newline, followed by any number of lines starting with 5 spaces. It then matches a line which does NOT start with a space. Finally it is anchored to the end of the text block with \z so that if there is more than one inventory recently it will find the last one. In this case the number of lines needs to be the largest number you expect in your inventory, as the middle part of the regular expression can match more than one line. You could choose any number up to 200. Another example matches a "who" list, which might look like this: `Connected players Bob Alice Nick 3 players` The regular expression could be: `Match: ^Connected players\n(?s)(.)\n(\d) players?\n\z` This example uses the "\n" character to indicate line breaks, and the words "Connected players" to start the list, and "X players" to end it. Limitations on multi-line triggers The higher the number of lines you specify, the slower the trigger matching will run, as it has to assemble, and then test, a larger string. Multiple line triggers must be regular expressions, as the syntax for matching line breaks does not exist for normal triggers. Because of the way they work some trigger processing is not available to multi-line triggers (eg. colouring lines, omit from output, omit from log). They will match output from the MUD (not notes or commands that might be in the output window), even if that output was omitted from the output window by a previous trigger. Make wildcards lower-case If checked, any matching wildcards are forced to lower-case before being used. This lets you match on an upper-case word, but send it back to the MUD in lower case. One-shot If checked, once this trigger fires, it is deleted. Convert to Regular Expression Click to convert an ordinary trigger to a regular expression. Change colour and style to: If the trigger matches you can colour the matching word or line, by setting the options below. If the trigger matches a regular expression, then only the matching portionn of the line will be changed. A non regular expression always changes the colour of the whole line. Choose a colour from the drop-down list. The default is "no change" which means the matching text will stay in whatever colour they were to start with. Otherwise you can choose from any of the 16 custom colours which you can set up in the custom colour configuration diaglog. You can also choose "other" and then click on the two colours swatches which will appear to make the trigger matching text be coloured in any foreground or background colour you choose. Both / Text / Back If you are choosing to change the colour of the match text, you can select from the drop-down box whether the change applies to both text and background (the default), or text-only, or background only. If you change the text only, then the underlying background colour is preserved. If you change the background only, then the text colour is preserved, but you can highlight the word(s) with a different shade of background. Bold Click to make the matching text bold. This is greyed out if you do not have "show bold" enabled in the Output configuration screen. Italic Click to make the matching text italic. This is greyed out if you do not have "show italic" enabled in the Output configuration screen. Underline Click to make the matching text underlined. This is greyed out if you do not have "show underline" enabled in the Output configuration screen. Send to: Where to send the "send" text to. The default is to the MUD, however you can choose other places, like the output window (as a note to yourself), a notepad, or simply enter a script command in the "send" box and send to "script". The "send-to" box lets you choose to send the "send" text to one of: world (the MUD) command (the command window) output (directly to the output window, as a note to yourself) status (to the status line) notepad - new (create a new notepad window) notepad - append (append to a notepad window) log file (directly to the log file) notepad - replace (replace an existing notepad window) world - speedwalk delay (queue for delayed send at the speedwalk rate) variable (set a variable, whose name you provide in the variable box) execute (execute through normal command parser, so aliases, speedwalks etc. will be executed) speedwalk (send to world after converting speedwalk string) script (execute as a script command in the current scripting language) world - immediate (to the MUD immediately, even if you are speedwalking) script- after omit (execute as a script command, after omitting the matching line from output, if that option was checked) If you send to "script (after omit)", and are using Lua scripting, MUSHclient will create a global variable called "TriggerStyleRuns", into which is placed an entry for each style run in the matching trigger. Variable: If you have chosen "send to variable" then enter the variable to be set here. Sound If a sound is chosen then that will be played when the trigger matches. Browse... Click to browse for a sound file. Test Click to test the chosen sound. No sound Click to have no sound play. Only if inactive If checked, the sound is played only if the world window is not active. You can use this to play an "alert" sound if a message arrives for you (eg. Place your name in the trigger match text) but if that world window is not currently active, Sequence: By entering a sequence number you can make triggers evaluate in a particular order. The lower the number, the earlier the trigger is evaluated (that is, low numbers are evaluated before high numbers). If two triggers have the same sequence the evaluation order is not defined (that is, it could be anything). Copy wildcard X to Clipboard. You can choose to copy any of the first matching 10 wildcards to the Clipboard. Label: The name (label) of this trigger. Use this if you want to refer to the trigger in scripts. Rules for names Names of triggers, aliases, timers and variables must follow these rules: Start with a letter (A-Z) Be followed by letters (A-Z), numbers (0-9) or the underscore character (_) Script: Which script routine to call in your script file. The script routine must be defined with three arguments. For example, in Vbscript: `sub myTrigger (name, output, wildcards) world.Note "Trigger " & " name has fired!" end sub` However in Lua all arguments are optional (as is usual with Lua function calls). Also if you are using Lua scripting there is a fourth (optional) argument, which is a table of all the style runs in the matching trigger. Each entry has a sub table for: textcolour - the RGB colour of the text in this style (number) backcolour - the RGB colour of the background (number) text - the actual text length - the length of the style run style - style bits (bold=1, underline=2, blink=4) or'ed together (eg. bold underline would be 6) If you use "send to script (after omit)" then the style runs are also available from the global variable: TriggerStyleRuns. Group: You can put triggers, aliases and timers into groups, and enable or disable the entire group. If you wish to do that put a group name here. See Also ... Topics Aliases Default triggers/aliases/timers/macros/colours Getting started Groups Plugins Regular Expressions Timers Triggers Dialog Trigger configuration list Functions (AddTrigger) Adds a trigger (AddTriggerEx) Adds a trigger - extended arguments (DeleteTemporaryTriggers) Deletes all temporary triggers (DeleteTrigger) Deletes a trigger (DeleteTriggerGroup) Deletes a group of triggers (EnableTrigger) Enables or disables a trigger (EnableTriggerGroup) Enables/disables a group of triggers (GetPluginTriggerInfo) Gets details about a named trigger for a specified plugin (GetPluginTriggerList) Gets the list of triggers in a specified plugin (GetTrigger) Gets details about a named trigger (GetTriggerInfo) Gets details about a named trigger (GetTriggerList) Gets the list of triggers (GetTriggerOption) Gets the value of a named trigger option (GetTriggerWildcard) Returns the contents of the specified wildcard for the named trigger (IsTrigger) Tests to see if a trigger exists (SetTriggerOption) Sets the value of a named trigger option (StopEvaluatingTriggers) Stops trigger evaluation (Help topic: dialog=IDD_EDIT_TRIGGER)

When a trigger matches MUSHclient does not evaluate any further triggers (unless "Keep Evaluating" is checked). Thus a trigger can be used as a "blocker" to stop further triggers down the list from being processed. Triggers with lower sequence numbers are evaluated before triggers with higher sequence numbers. Thus, use sequence numbers to control the evaluating sequence. Triggers with the same sequence number are evaluated in an undefined order.

Trigger:

This is the text that you are expecting from the MUD. If it is matched on exactly, then the text in the "send" box is acted upon and your script (if any) is called.

(...)

Click to edit the trigger text in a larger window. If the trigger is a regular expression the larger window also has an extra "helper" button to assist you in adding regular expression items.

Match: (colour) on (colour)

You can make a trigger match a particular colour line by setting these options. Leave the colours at "(any)" to match on any colour. You can also match on a line in bold/italic/inverse or any combination of these. These check-boxes are "tri-state", which means they can be:

1. Unchecked (the line must not be bold, for example)
2. Checked (the line must be bold, for example)
3. Greyed out (it doesn't matter if the line is bold or not)

The first character of the matching text is checked for the specified colour.

Bold

Check to match if the first character of the matching text is bold. Uncheck if the first character must not be bold. Greyed out if you don't care.

Italic

Check to match if the first character of the matching text is italic. Uncheck if the first character must not be italic. Greyed out if you don't care.

Inverse

Check to match if the first character of the matching text is inverse. Uncheck if the first character must not be inverse. Greyed out if you don't care.

Send:

What to send to the "send" destination. The default send destination is back to the MUD.

You can use %1 to match the first wildcard, %2 to match the second wildcard, and so on up to %9. For wildcards above 9 you can use %<n> (for example, %<50> for wildcard 50).

For named wildcards you can use %<name> (for example, %<mob> for a wildcard with the name "mob"). Named wildcards are produced by using a regular expression and a group like: (?P<mob>.+?)

%0 represents the whole matching text.

Use %% to represent a single % symbol. You can also use %C to insert the contents of the Clipboard, and %N to insert the current trigger's name (label).

If you are sending to script then any quotes or other special characters in the send text (inside the wildcard contents) are "escaped" appropriately for the script language you are using.

(...)

Click to edit the send text in a larger box.

Alternatively press Alt+Enter to open the editing dialog box.

Enabled

If checked, the trigger is enabled (active).

Ignore case

If checked, the trigger match is case insensitive. If not checked, the "case" of the matching text must agree exactly.

Omit from log file

If checked, the matching line is not logged to the log file (if open).

Omit from output

If checked, the matching line is omitted from the output window.

Keep evaluating

If checked, the same line is checked against further triggers. If unchecked the first matching trigger cancels trigger evaluation. You can change the order in which triggers are evaluated by amending the sequence field.

Regular expression

If checked, the trigger match text is a regular expression. See "regular expressions" in the help for more information. You can convert an "ordinary" trigger to a regular expression by clicking the "Convert to Regular Expression" box. Then you can edit the regular expression to customise it.

Repeat on same line

If checked, the trigger is matched repeatedly against the same line (this only applies to regular expressions). This lets you colour individual words which might appear more than once on a line.

Expand variables

If expand variables is on (checked) then a variable name in the format @name is expanded. To put a @ symbol itself in the trigger, use two @@.

Here is an example of such an trigger:

unlock @direction

For this trigger to work you would need a variables, "direction".

You can set variables by using the configuration dialog box, or through a scripting command (if scripting is enabled), like this:


/SetVariable ("direction", "north")

If you want to use variables inside regular expressions and not have special characters "fixed" by putting backslashes inside them, use the syntax:


@!variable

Temporary

If checked, the trigger will not be saved to the world file. In other words, it is a temporary one only for use in this session.

Multi-line, match ... lines.

If checked, this trigger will match multiple lines, starting with the current line (the most recently received), and including the number of lines specified in the adjacent box.

For multi-line triggers MUSHclient assembles a "block of text" which is the specified number of lines, working backwards from the current line, each one ending with a newline character (assembled in the order in which they arrived, of course). This text block is then passed to the regular expression handler to see if it matches. The number of lines is lines with a newline at the end of the, not necessarily the number of lines you see on the screen. For instance, if the MUD sent some 200-character lines that line-wrapped, each line is counted as one line, even if you see four lines on the screen.

A simple example would be to match on:


You are hungry.
You are thirsty.

To match this you might have the regular expression:


Match: ^You are hungry\.\nYou are thirsty\.\n\z

The \n represents the "newline" character (hex 0A) between the two lines, the \. is a single period (at the end of the sentences) and the \z is an "anchor" to the end of the text block. The \z is not really necessary for this example, but could be useful for longer ones.

For this example the "number of lines" would be 2, as you are trying to match a 2-line block.

A more complex example is to match your inventory, which might be:


You are carrying:
     a magic mushroom
     a torch
     a dragonskin
     a bag
     recall scroll

Note the blank line at the end of the inventory.

A matching trigger might be:


Match: ^You are carrying:\n(([ ]{5}.*\n)*)[^ ]\z

This matches "You are carrying" followed by a newline, followed by any number of lines starting with 5 spaces. It then matches a line which does NOT start with a space. Finally it is anchored to the end of the text block with \z so that if there is more than one inventory recently it will find the last one.

In this case the number of lines needs to be the largest number you expect in your inventory, as the middle part of the regular expression can match more than one line. You could choose any number up to 200.

Another example matches a "who" list, which might look like this:


Connected players
  Bob
  Alice
  Nick
3 players

The regular expression could be:


Match: ^Connected players\n(?s)(.*)\n(\d*) players?\n\z

This example uses the "\n" character to indicate line breaks, and the words "Connected players" to start the list, and "X players" to end it.

Limitations on multi-line triggers

The higher the number of lines you specify, the slower the trigger matching will run, as it has to assemble, and then test, a larger string.
Multiple line triggers must be regular expressions, as the syntax for matching line breaks does not exist for normal triggers.
Because of the way they work some trigger processing is not available to multi-line triggers (eg. colouring lines, omit from output, omit from log).
They will match output from the MUD (not notes or commands that might be in the output window), even if that output was omitted from the output window by a previous trigger.

Make wildcards lower-case

If checked, any matching wildcards are forced to lower-case before being used. This lets you match on an upper-case word, but send it back to the MUD in lower case.

One-shot

If checked, once this trigger fires, it is deleted.

Convert to Regular Expression

Click to convert an ordinary trigger to a regular expression.

Change colour and style to:

If the trigger matches you can colour the matching word or line, by setting the options below.

If the trigger matches a regular expression, then only the matching portionn of the line will be changed. A non regular expression always changes the colour of the whole line.

Choose a colour from the drop-down list. The default is "no change" which means the matching text will stay in whatever colour they were to start with.

Otherwise you can choose from any of the 16 custom colours which you can set up in the custom colour configuration diaglog.

You can also choose "other" and then click on the two colours swatches which will appear to make the trigger matching text be coloured in any foreground or background colour you choose.

Both / Text / Back

If you are choosing to change the colour of the match text, you can select from the drop-down box whether the change applies to both text and background (the default), or text-only, or background only.

If you change the text only, then the underlying background colour is preserved.

If you change the background only, then the text colour is preserved, but you can highlight the word(s) with a different shade of background.

Bold

Click to make the matching text bold. This is greyed out if you do not have "show bold" enabled in the Output configuration screen.

Italic

Click to make the matching text italic. This is greyed out if you do not have "show italic" enabled in the Output configuration screen.

Underline

Click to make the matching text underlined. This is greyed out if you do not have "show underline" enabled in the Output configuration screen.

Send to:

Where to send the "send" text to. The default is to the MUD, however you can choose other places, like the output window (as a note to yourself), a notepad, or simply enter a script command in the "send" box and send to "script".

The "send-to" box lets you choose to send the "send" text to one of:

world (the MUD)
command (the command window)
output (directly to the output window, as a note to yourself)
status (to the status line)
notepad - new (create a new notepad window)
notepad - append (append to a notepad window)
log file (directly to the log file)
notepad - replace (replace an existing notepad window)
world - speedwalk delay (queue for delayed send at the speedwalk rate)
variable (set a variable, whose name you provide in the variable box)
execute (execute through normal command parser, so aliases, speedwalks etc. will be executed)
speedwalk (send to world after converting speedwalk string)
script (execute as a script command in the current scripting language)
world - immediate (to the MUD immediately, even if you are speedwalking)
script- after omit (execute as a script command, after omitting the matching line from output, if that option was checked)

If you send to "script (after omit)", and are using Lua scripting, MUSHclient will create a global variable called "TriggerStyleRuns", into which is placed an entry for each style run in the matching trigger.

Variable:

If you have chosen "send to variable" then enter the variable to be set here.

Sound

If a sound is chosen then that will be played when the trigger matches.

Browse...

Click to browse for a sound file.

Test

Click to test the chosen sound.

No sound

Click to have no sound play.

Only if inactive

If checked, the sound is played only if the world window is not active. You can use this to play an "alert" sound if a message arrives for you (eg. Place your name in the trigger match text) but if that world window is not currently active,

Sequence:

By entering a sequence number you can make triggers evaluate in a particular order. The lower the number, the earlier the trigger is evaluated (that is, low numbers are evaluated before high numbers). If two triggers have the same sequence the evaluation order is not defined (that is, it could be anything).

Copy wildcard X to Clipboard.

You can choose to copy any of the first matching 10 wildcards to the Clipboard.

Label:

The name (label) of this trigger. Use this if you want to refer to the trigger in scripts.

Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

Start with a letter (A-Z)
Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Script:

Which script routine to call in your script file. The script routine must be defined with three arguments. For example, in Vbscript:


sub myTrigger (name, output, wildcards)
  world.Note "Trigger " & " name has fired!"
end sub

However in Lua all arguments are optional (as is usual with Lua function calls).

Also if you are using Lua scripting there is a fourth (optional) argument, which is a table of all the style runs in the matching trigger. Each entry has a sub table for:

textcolour - the RGB colour of the text in this style (number)
backcolour - the RGB colour of the background (number)
text - the actual text
length - the length of the style run
style - style bits (bold=1, underline=2, blink=4) or'ed together (eg. bold underline would be 6)

If you use "send to script (after omit)" then the style runs are also available from the global variable: TriggerStyleRuns.

Group:

You can put triggers, aliases and timers into groups, and enable or disable the entire group. If you wish to do that put a group name here.

See Also ...

Topics

Aliases
Default triggers/aliases/timers/macros/colours
Getting started
Groups
Plugins
Regular Expressions
Timers
Triggers

Dialog

Trigger configuration list

Functions

(AddTrigger) Adds a trigger
(AddTriggerEx) Adds a trigger - extended arguments
(DeleteTemporaryTriggers) Deletes all temporary triggers
(DeleteTrigger) Deletes a trigger
(DeleteTriggerGroup) Deletes a group of triggers
(EnableTrigger) Enables or disables a trigger
(EnableTriggerGroup) Enables/disables a group of triggers
(GetPluginTriggerInfo) Gets details about a named trigger for a specified plugin
(GetPluginTriggerList) Gets the list of triggers in a specified plugin
(GetTrigger) Gets details about a named trigger
(GetTriggerInfo) Gets details about a named trigger
(GetTriggerList) Gets the list of triggers
(GetTriggerOption) Gets the value of a named trigger option
(GetTriggerWildcard) Returns the contents of the specified wildcard for the named trigger
(IsTrigger) Tests to see if a trigger exists
(SetTriggerOption) Sets the value of a named trigger option
(StopEvaluatingTriggers) Stops trigger evaluation

(Help topic: dialog=IDD_EDIT_TRIGGER)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.