Documentation

#TRIGGER

TRIGGER

Syntax: #TR id {pattern} {commands} classname options

This is one of the most powerful features of TeSSH. It allows you to define a command to be executed whenever the matching text is received from the server.

If the id is present, then the trigger is created with the given short name. Otherwise the name for the trigger is the same as the pattern. IDs are useful for giving short names to complicated trigger patterns, or for creating multiple triggers with the same pattern.

The pattern is the text to be matched. This pattern should always be enclosed in braces {}. The pattern indicates the text received from the server which causes this trigger to execute (or fire). This pattern can contain special pattern matching symbols and wildcards.

The commands are executed when the pattern is received from the server.

The classname is optional, and is the name of the class folder that this action is part of. Triggers can be enabled and disabled when part of a class. If the classname is not given, the current default class is used.

The options are optional, and are used to set various trigger properties. Options is a string list of values. Allowed values are:

nocr
Do NOT test this trigger at the end of each line received from the server. If this option is not given, then the trigger will be tested when a newline is received from the server.
prompt
Test this trigger at the end of each buffer of text received from the server (even if there is no newline. Used for trigger on server prompts). Normally when you specify this option, you should also specify the nocr option or else your trigger might fire twice.
case
Causes the pattern to be case-sensitive
verbatim
match the text of the pattern verbatim and not parse any special characters or wildcards in the pattern
notrig
Prevents other triggers from firing while this trigger is executing
color
Indicate that the pattern contains ANSI color control sequences
disable
Disable the trigger on startup
stop
Prevents processing any trigger after this one in the priority order
pri=value
Sets the priority of the trigger. You can also use the longer "priority=value" syntax.
regex
Marks the trigger as using regular expression patterns. Using the #REGEX command will automatically set this option for you.
line=color
Set the color of the line that this trigger fires on

For setting advanced trigger options, you normally go to the Package Editor dialog. In this screen, you can determine whether the action is triggered at the end of each line received from the server, or if it is just triggered at the end of receiving a block of data from the server. Responding to server prompts such as Username and Password require a trigger that activates after a block of text is received since these prompts are not normally followed by a newline.

See the Pattern Matching section for more detailed information on patterns.
More information on trigger options and trigger types is available here.
More information on multistate triggers (triggers with sequentially-checked patterns) is available here.

A simple trigger action

#TRIG {chats} {#COLOR red}
whenever a line containing the word 'chat' is received, the color of the line is changed to red.

Triggers for automatic logins

#TRIG {^Username:} {#CH}
#TRIG {^Password:} {#PW}
In the Preferences dialog, turn off the 'Trigger on Newline' option and turn on the 'Trigger on Prompt' so that these macros don't wait for a newline character. Note that the ^ character at the beginning of each pattern forces them to match the beginning of a line.

Parameters in triggers

#TRIG {^You get (%d) coins} {split %1} autosplit
Whenever you see a line like You get nnn coins the number of coins is stored in the %1 parameter. The command then uses this value to split the coins among the party members. A class name of autosplit is used so that you can enable and disable the trigger using the #T+ and #T- commands.

ADVANCED: Extracting data from a line

#TRIG {^~[&hp/&{maxhp}hp &mana/&{maxmana}ma~]} {#IF (@hp < @maxhp/10) {cast 'heal'}} "" "prompt"
The &varname syntax in the pattern tells the trigger to store the matching text in the named variable. It is a shortcut for (*) and then assigning the %nn parameter to the @varname variable. In this case, we are matching a server prompt. Since server prompts do not end in a newline, we add the "prompt" option to the end of the trigger definition. Since the server prompt in this example looks like:

[100/150hp 50/70ma]

We have to use a couple of tricks in the pattern definition (which is why this is an ADVANCED example). First, we want to match the [ character at the beginning of the prompt. But, the [ character is a special pattern matching character, so to match the verbatim character from the server instead of using [ as a pattern matching character, we put the ~ character in front of it
. The ~ character tells TeSSH to ignore any special property of the next character and just treat it as a normal character. You will need to use ~ to match any special characters from the server like [, @, (, etc. To match a ~ character itself, you would use ~~, of course.
The next trick is to make sure that the &maxhp and &maxmana variable only contain the numeric values, and not the text "hp" or "ma". Remember that &varname is equivalent to (*), so it will normally match both text and numbers. So, we put the literal text "hp" and "ma" in our pattern. But if the pattern had &maxhphp then how would TeSSH know that "maxhp" was the variable name and "hp" was the literal text? We have to enclose the name of the variable in braces {} to distinguish it from the literal text. So, we have &{maxhp}hp which tells the trigger to store the numeric value in the @maxhp variable, and then match the literal "hp" text from the server.

Take a look at the #SETPROMPT command for an easier way to capture information from this simple server prompt.

Add comment

Login or register to post comments