## C.97. `$world->trigger`

Abstract

$world->trigger function: creates a TRIGGER

`void $world->trigger(` | `pattern` ,
| `action` ,
| [`attributes`] `)`;

`void $world->trigger(` | `number` ,
| [`pattern` ,
| [`action`]] ,
| [`attributes`] `)`;

Creates a new trigger, or edits the trigger identified by `number`, matching `pattern` (a Perl regular expression), that will execute `action` when a line is matched by `pattern`. `action` is interpreted as if it were typed in the command box. Simple strings get sent to the world, Perl code can be run by prefixing it with '`/`', etc.

`atributes` is a reference to a hash defining attributes for the trigger. Generally the call works like this:

    $world->trigger("pattern", "action", { attribute1 => value1,
                                           attribute2 => value2, ... })

Possible attributes:

- `pattern`: The pattern to match.

- `action`: The action to be executed.

- `enabled`: If value evaluates to true, the trigger is enabled. If it evaluates to false, the trigger is disbled and lines are not matched against it.

- `name`: Assigns a name to the trigger, so that it can be referenced by name.

- `ignorecase`: If value evaluates to true, ignore case when matching the pattern.

- `gag`: If value evaluates to true, the line that triggered it is not printed.

- `gaglog`: If value evaluates to true, the line that triggered it is not written to the log file.

- `keepexecuting`: If the value evaluates to true, when a line matches the trigger, the actions for the trigger are executed, and matching of the line continues against other triggers. If this is false (the default), when this trigger matches no other triggers are matched.

- `rewriter`: This trigger is a rewriter trigger. It is run before other triggers, does not prevent any other trigger from running (even if keepexecuting is false), and can alter the input line for further processing by changing the `$colorline` variable. For more details, see Section 8.5.1, “Rewriter Triggers”.

- `style`: Used to control the changing of styles (color, attributes, etc.) of a matched part of the line. The value of this attribute is an anonymous hash that specifies everything that is to be changed.

  Here's an example:

  Example C.1. Changing styles with triggers

      $world->trigger('Joe', { name => 'joe', style => { enabled => 1,
                                                         fg => 16 } });

  These are the valid attributes:

  - `enabled`: Set this to 1 to enable changing the style.

  - `target`: What to highlight. Possible values are:

          -1 - The whole matched line
           0 - The whole substring that matched
           1 - The first captured substring
           2 - The second captured substring
           3 - etc.

  - `fg`: What to do with the foreground colour. -1 means not to change it. Other values change to the given color, as follows:

          0 - black                  9 - black (bold)
          1 - red                   10 - red (bold)
          2 - green                 11 - green (bold)
          3 - yellow                12 - yellow (bold)
          4 - blue                  13 - blue (bold)
          5 - magenta               14 - magenta (bold)
          6 - cyan                  15 - cyan (bold)
          7 - white                 16 - white (bold)
          8 - the default color     17 - default bold color

  - `bg`: What to do with the background color. The values are the same as for the foreground color.

  - `italics`: Italics setting. -1 means do not change. 0 means to not use italics, and 1 means to use it.

  - `strike`: Strike-thru setting. -1 means do not change. 0 means disable it, and 1 means enable it.

  - `underline`: Underline setting. -1 means no change. 0 means no underline. 1 means single underline, and 2 means double underline.