/usr/share/doc/kildclient/html/ch08s02.xhtml is in kildclient-doc 3.2.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>8.2. Basic Triggers</title><link rel="stylesheet" type="text/css" href="docbook.css"/><link rel="stylesheet" type="text/css" href="kildclient.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/><link rel="prev" href="ch08s01.xhtml" title="8.1. Creating and Editing Triggers"/><link rel="next" href="sec_trigger_highlight.xhtml" title="8.3. Changing the Style of the Matched Text"/></head><body><header><div class="navheader"><table style="width: 100%; "><tr><th style="text-align: center; " colspan="3">8.2. Basic Triggers</th></tr><tr><td style="width: 20%; text-align: left; "><a accesskey="p" href="ch08s01.xhtml">Prev</a> </td><th style="width: 60%; text-align: center; ">Chapter 8. Triggers</th><td style="width: 20%; text-align: right; "> <a accesskey="n" href="sec_trigger_highlight.xhtml">Next</a></td></tr></table><hr/></div></header><section class="sect1" id="idm1081"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.2. Basic Triggers</h2></div></div></div><p>The simplest kind of trigger specifies only a pattern and an
action. Below these parameters are described in detail.</p><p>What exactly is <em class="replaceable"><code>pattern</code></em>? It is a
<span class="emphasis"><em>regular expression</em></span>. In short, a regular
expression is a way to specify text patterns that are looked for in
the lines that the server sends. If you know Perl, you certainly know
what is a regular expression. If not, it is advised that you look for
some more information on it, there are plenty of tutorials on the
Internet. For those who know them, you can use the full power of
Perl's regular expressions in triggers, because Perl is used for the
matching.</p><p>What about the <em class="replaceable"><code>action</code></em>? It can be
anything that could be entered in the command line. It can be a simple
command, that is sent to the MUD. Or you can send several commands at
separating them with <code class="literal">%;</code> as described in
<a class="xref" href="sec_interacting.xhtml" title="3.2. Interacting with the MUD">Section 3.2, “Interacting with the MUD”</a>. Finally, you can execute some Perl
code when a trigger matches, and this allows you to do virtually
anything you want.</p><p>Below is an example of a very simple trigger. To create this
trigger, inform the <span class="guilabel">Pattern</span>
and <span class="guilabel">Action</span> parameters shown below. Leave the
other parameters in their default values.</p><div class="example" id="ex_simplest_trigger"><div class="example-title">Example 8.1. A very simple trigger</div><div class="example-contents"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Pattern: <code class="literal">has attacked you!</code></p></li><li class="listitem"><p>Action: <code class="literal">wield sword</code></p></li></ul></div></div></div><br class="example-break"/><p>Whenever a line that contains the phrase "<code class="literal">has attacked
you!</code>" is received, the command "<strong class="userinput"><code>wield
sword</code></strong>" will be automatically be sent. Note that in this
case the received line will probably be something like "<code class="literal">An
orc has attacked you!</code>", but the trigger matches because that
line contains the <em class="replaceable"><code>pattern</code></em>. This is a
feature of regular expressions. If you want to match the entire line
and not only part of it, you must use the <code class="literal">^</code> and
<code class="literal">$</code> anchors in the beginning and end,
respectively.</p><p>By default, case is considered when matching: if the server sent
a line saying "<code class="literal">Has Attacked</code>" then there would be no
match. To make case be ignored when matching, check
the <span class="guilabel">Ignore case when matching</span> option.</p><p>It is also possible for the action to be executed to depend on
what was received from the server. This is better explained by an
example:</p><div class="example" id="ex_trigger_regex_grouping"><div class="example-title">Example 8.2. A trigger which captures part of the received line and uses
it in the action</div><div class="example-contents"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Pattern: <code class="literal">^(.*) has attacked you!$</code></p></li><li class="listitem"><p>Action: <code class="literal">cast missile $1</code></p></li></ul></div></div></div><br class="example-break"/><p>There are two new things in the pattern. The first one is that
is surrounded by <code class="literal">^</code> and <code class="literal">$</code> which
means that the entire line must match, as described previously. The
other new thing (and the one that concerns us at this moment) is
the <code class="literal">(.*)</code> part. In regular expressions, the dot
means to match any character. The asterisk means zero or more of the
previous element. So the combination <code class="literal">.*</code> means zero
or more of any characters. Essentially, it matches anything. The
brackets <code class="literal">()</code> around any part of a regular expression
captures part of the string to be used afterwards. So the whole
regular expression means: look for a line that contains something
followed by <code class="literal">has attacked you!</code>. What comes
before <code class="literal">has attacked you!</code> is stored for later
use.</p><p>This stored string is then used in the action by means of
the <code class="literal">$1</code> construct. This special placeholder is
substituted by what was captured in the matched string. So if the
line <code class="literal">Orc has attacked you!</code> is
received, <code class="literal">cast missile Orc</code> is send.
If <code class="literal">Smaug has attacked you!</code> is received,
then <code class="literal">cast missile Smaug</code> is sent to the World, and
so on.</p><p>It is possible to have more than one captured string in the
pattern. In this case, <code class="literal">$1</code> is replaced by what was
captured in the first group, <code class="literal">$2</code> by the second
group, and so on.</p><p>Sending commands to the World is useful, but the real power is
the fact that you can also run Perl commands in response to triggers.
Just enter them as you would in the command box: prefixed
by <code class="literal">/</code>. If the action is simple you can enter the
statements there directly, if not, you can define a function in your
script file and call it from the trigger.</p><p>Let us rewrite <a class="xref" href="ch08s02.xhtml#ex_trigger_regex_grouping" title="Example 8.2. A trigger which captures part of the received line and uses it in the action">Example 8.2, “A trigger which captures part of the received line and uses
it in the action”</a> to use
Perl in the action:</p><div class="example" id="ex_trigger_perl"><div class="example-title">Example 8.3. A trigger with an action in Perl</div><div class="example-contents"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Pattern: <code class="literal">^(.*) has attacked you!$</code></p></li><li class="listitem"><p>Action: <code class="literal">/$world->send("cast missile $_[1]")</code></p></li></ul></div></div></div><br class="example-break"/><p>This time, when a line consisting of some arbitrary text
followed by "<code class="literal">has attacked you!</code>" is received, the
<code class="function">$world->send</code> will be called to send some text
to the World.</p><p>You may have noticed that here <code class="literal">$_[1]</code> was used
instead of <code class="literal">$1</code> in the action to represent the first
captured bracketed group. The reason for this is complex, and if you
do not want to worry about the inner workings, just use the following
rule: in commands sent to the mud,
use <code class="literal">$1</code>, <code class="literal">$2</code>, etc., and in actions
that are Perl commands,
use <code class="literal">$_[1]</code>, <code class="literal">$_[2]</code> and so
on.</p><p>Here are the details for the different syntaxes. Feel free to
skip the next two paragraphs:</p><p>When a trigger matches, KildClient substitutes
<code class="literal">$1</code> (and the other placeholders) by the captured
expressions from the received line. However, <code class="literal">$_[1]</code>
(and the other similar tokens) are not replaced by KildClient. If the
action is just a string sent to the mud, they would not be replaced,
so the only possibility to use the captured groups is with
the <code class="literal">$1</code> syntax. But Perl commands can access the
captured groups in another way: the strings are stored in
the <code class="varname">@_</code> array. The first
position, <code class="varname">$_[0]</code> contains the whole matched line.
Subsequent positions contain each matched grouped expression,
so <code class="varname">$_[1]</code> is the first bracketed
substring, <code class="varname">$_[2]</code> is the second, and so on. This
way, when a Perl command is executed the values are replaced by the
Perl interpreter itself.</p><p>It is also possible to use <code class="literal">$1</code> in commands to
be passed to the Perl interpreter. Most of the time it will work, but
in some specific circumstances you may get unexpected results. So it's
preferable to let Perl do the substitution when commands are to be
run by the Perl interpreter.</p><p>If you call a sub-routine as the trigger action, the matched
arguments are not automatically passed, so you need to pass them
manually. Since they are in the array <code class="varname">@_</code>, just pass
that whole array as the argument to the sub-routine. Inside the
sub-routine, they will be available as the sub-routine's arguments,
which incidentally means that they will be accessed in the exact same
way: with <code class="varname">$_[1]</code>, <code class="varname">$_[2]</code> and so
on. Alternatively, you can only pass the parameters that you need
instead of the whole array.</p><p>Here's an example of a trigger that calls a sub-routine:</p><div class="example" id="idm1183"><div class="example-title">Example 8.4. A trigger that calls a sub-routine</div><div class="example-contents"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Pattern: <code class="literal">^(.*) has attacked you!$</code></p></li><li class="listitem"><p>Action: <code class="literal">/myGreatAttackSequence(@_)</code></p></li></ul></div></div></div><br class="example-break"/><p>Naturally, you need to define the
<code class="function">myGreatAttackSequence</code> sub-routine in your script
file. It will be called as the result of the trigger. The
<code class="varname">@_</code> array, containing the whole matched line and the
matched bracketed expressions is passed to the sub-routine as argument,
and its contents will be available to the sub-routine as its
parameters.</p></section><footer><div class="navfooter"><hr/><table style="width: 100%; "><tr><td style="width: 40%; text-align: left; "><a accesskey="p" href="ch08s01.xhtml">Prev</a> </td><td style="width: 20%; text-align: center; "><a accesskey="u" href="chap_triggers.xhtml">Up</a></td><td style="width: 40%; text-align: right; "> <a accesskey="n" href="sec_trigger_highlight.xhtml">Next</a></td></tr><tr><td style="width: 40%; text-align: left; vertical-align: top; ">8.1. Creating and Editing Triggers </td><td style="width: 20%; text-align: center; "><a accesskey="h" href="index.xhtml">Home</a></td><td style="width: 40%; text-align: right; vertical-align: top; "> 8.3. Changing the Style of the Matched Text</td></tr></table></div></footer></body></html>
|