atr / addtrigger              Adds an independent trigger

   Format:
      ;atr <switches>         Adds a trigger

   Notes:
      Triggers are one of five types of Axmud interface (the others being
         aliases, macros, timers and hooks).
      Triggers allow you to react automatically to text received from the world.
         The reaction can have one of three forms: the trigger can execute an
         instruction (including world commands, client commands, Perl commands
         and echo commands), or it can split a line into two (a 'splitter'
         trigger), or it can change the way the received text is displayed in
         the 'main' window (a 'rewriter' trigger),
      This command creates a trigger interface that's 'inactive' - it's
         associated with a particular profile (actually, stored in a 'cage'
         object associated with that profile). When that profile becomes a
         current profile - and only if there isn't another trigger with the same
         name, attached to a higher-priority profile - then an 'active' trigger
         is created with the same attributes.
      The trigger created is also 'independent', meaning that it doesn't call
         some part of the Axmud code directly.

      A simple example. When a line containing the word 'troll' is received from
         the world, the character automatically goes north:

         ;addtrigger -s troll -p north

      All interfaces have four standard attributes:
         'name'      - A name for the trigger
         'stimulus'  - What causes the alias to 'fire'. The stimulus is a
                          pattern in the form of a Perl regular expression (or
                          'regex'). An example of a simple pattern would be
                          'The orc kills you', which causes the trigger to fire
                          whenever a line is received from the world which
                          contains that text.
         'response'  - The instruction to execute when the trigger fires.
                          Includes world commands, forced world commands
                          (starting with ',,'), client commands (starting ';'),
                          echo commands (starting '"'), Perl commands (starting
                          '/'), script commands (starting '&') and multi
                          commands (starting ':'). A Perl command is evaluated
                          before the received text is displayed in the 'main'
                          window, but the resulting world command (if any),
                          along with all other instructions, are executed after
                          the text is displayed (in the order in which the
                          triggers fired). 'Rewriter' triggers use the response
                          in a different way (see below).
         'enabled'   - A flag set to 1 (default) or 0. When set to 1, the active
                          trigger is enabled (does something). When set to 0, it
                          is disabled (temporarily does nothing)
      Triggers also have the following non-standard attributes:
         'ignore_response'
                     - A flag set to 1 or 0 (default). If set to 1, when the
                          trigger fires because of a stimulus, the response is
                          ignored. This is useful if you just want to apply a
                          trigger style to some text, without modifying it and
                          without executing a command. If set to 0, the trigger
                          response is used
         'splitter'  - A flag set to 1 or 0 (default). If set to 1, the trigger
                          is a 'splitter' trigger. If the 'stimulus' matches the
                          line, the line is split into two lines just before the
                          portion of the line matching the 'response'. Splitter
                          triggers are tested before non-splitter triggers,
                          which act on the two split lines. If set to 0, the
                          'response' attribute is an instruction (as described
                          above).
         'split_after'
                     - A flag set to 1 or 0 (default). If set to 0, splitter
                          triggers which match a line split the line just before
                          the portion which matches the 'response'. If set to 1,
                          the line is split just after the portion which matches
                          the response. Non-splitter triggers are not affected
                          by this flag.
         'keep_splitting'
                     - A flag set to 1 or 0 (default). If set to 1, splitter
                          triggers whose 'response' pattern matches the line
                          more than once, split the line into more than two new
                          lines. If set to 0, the line is split at the first
                          portion which matches the 'response'. Non-splitter
                          triggers are not affected by this flag.
         'rewriter'  - A flag set to 1 or 0 (default). If set to 1, the trigger
                          is a 'rewriter' trigger. The 'stimulus' and 'response'
                          attributes are used in a substitution which modifies
                          the received line. Any later triggers act on the
                          modified line, and it is the modified line which is
                          displayed in the 'main' window. If set to 0, the
                          'response' attribute is an instruction (as described
                          above).
         'rewrite_global'
                     - A flag set to 1 or 0 (default). If set to 0, rewriter
                          triggers which match a line only rewrite the first
                          matching part of the line. If set to 1, rewriter
                          triggers rewrite every matching part of the line. Non-
                          rewriter triggers are not affected by this flag.
         'ignore_case'
                     - A flag set to 1 (default) or 0. - If set to 1, the
                          pattern is case-insensitive (so the text 'THE ORC
                          KILLS YOU' would match the pattern 'The orc kills
                          you'). If set to 0, patterns are case-sensitive.
         'gag'       - A flag set to 1 or 0 (default). If 1, the received line
                          that caused the trigger to fire is not displayed in
                          the 'main' window. If set to 0, it is displayed (in a
                          modified form for 'rewriter' triggers). If the
                          received line causes several triggers to fire, only
                          the last trigger's 'gag' attribute is used.
         'gag_log'   - A flag set to 1 or 0 (default). If 1, the received line
                          that caused the trigger to fire is not written to any
                          logfiles (if logging is enabled). If set to 0, the
                          normal rules for writing to logfiles are used. If the
                          received line causes several triggers to fire, only
                          the last trigger's 'gag_log' attribute is used.
         'need_prompt'
                     - A flag set to 1 or 0 (default). If 1, the trigger will
                          only fire on a line that doesn't end with a newline
                          character (probably a prompt). If 0, the trigger can
                          fire on a line, regardless of how it ends.
         'need_login'
                     - A flag set to 1 or 0 (default). If 1, the trigger will
                          only fire when the character has logged in. If 0, the
                          trigger can fire at any time.
         'keep_checking'
                     - A flag set to 1 (default) or 0. If set to 0, after the
                          first trigger fires, the instruction is executed
                          immediately and no more triggers are checked. If set
                          to 1, Axmud continues to check the line against other
                          triggers.
         'default_pane'
                     - A flag set to 1 (default) or 0. If 1, the trigger is only
                          checked against text displayed in the default pane. If
                          0, the trigger is checked against text displayed in
                          all panes.
         'pane_name' - If specified, the trigger is only checked against text
                          displayed in the pane with this name (and the
                          'default_pane' attribute is ignored)
         'temporary' - A flag set to 1 or 0 (default). When set to 1, the active
                          interface is destroyed after the trigger fires for the
                          first time. When set to 0, the interface can fire
                          indefinitely
         'cooldown'  - A number, in seconds; 0 (default) or above (can be
                          fractional). If 0, no cooldown period applies after
                          the trigger fires. If above 0, the trigger can't fire
                          again until the cooldown period has expired
         'style_mode'
                     - A style mode. Styles change the way the matching line is
                          displayed. If set to 0, styles are turned off. If set
                          to -1, the style is applied to the whole line. If set
                          to -2, the style is applied only to the portion of the
                          line that matches the 'stimulus' attribute. If set to
                          a positive integer, the style is applied to the
                          matched substring. When a style is applied, the
                          following attributes are used.
         'style_text'
                     - The text colour; an Axmud standard colour tag like 'red'
                          or 'BLUE', an xterm colour tag like 'x255' or an RGB
                          colour tag like '#FFFFFF' (use the value 0 to specify
                          the default text colour)
         'style_underlay'
                     - The underlay colour; an Axmud standard colour tag like
                          'ul_red' or 'UL_BLUE', an xterm colour tag like
                          'ux255' or an RGB colour tag like 'u#FFFFFF' (use the
                          value 0 to specify the default underlay colour)
         'style_italics'
                     - Show text in italics. Set to 1 (yes), 2 (no) or 0 (don't
                          change anything)
         'style_underline'
                     - Show text underlined. Set to 1 (yes), 2 (no) or 0 (don't
                          change anything)
         'style_blink_slow'
                     - Show text in slow-blinking mode. Set to 1 (yes), 2 (no)
                          or 0 (don't change anything)
         'style_blink_fast'
                     - Show text in fast-blinking mode. Set to 1 (yes), 2 (no)
                          or 0 (don't change anything)
         'style_strike'
                     - Show text in strike-through mode. Set to 1 (yes), 2 (no)
                          or 0 (don't change anything)
         'style_link'
                     - Show text as a clickable link. Set to 1 (yes), 2 (no) or
                          0 (don't change anything)

      <switches> allows you to define which attributes the trigger will have and
         with which profile it will be associated.

      Group 1 switch options: one of the following options must be used:
         -no option-          - Adds a trigger belonging to the current world
         -w                   - Adds a trigger belonging to the current world
         -g                   - Adds a trigger belonging to the current guild
         -r                   - Adds a trigger belonging to the current race
         -c                   - Adds a trigger belonging to the current char
         -x <category>        - Adds a trigger belonging to the current custom
                                   profile <category>
         -d <prof>            - Adds a trigger belonging to profile <prof>

      Group 2 switch options: both of the following options must be used:
         -s <pattern>         - Sets the 'stimulus' attribute (a regex)
         -p <instruction> / -p <substitution>
                              - Sets the 'response' attribute (an instruction,
                                   or a Perl substitution for 'rewriter'
                                   triggers)
      Group 3 switch options: 0, 1 or more of the following options can be used:
         -n <string>          - Sets the 'name' attribute (a string). If not
                                   specified, a name is generated for you
         -e <boolean>         - Sets the 'enabled' attribute (1 or 0; default is
                                   1)
         -ir <boolean>        - Sets the 'ignore_response' attribute (1 or 0;
                                   default is 0)
         -sp <boolean>        - Sets the 'splitter' attribute (1 or 0; default
                                   is 0)
         -sa <boolean>        - Sets the 'split_after' attribute (1 or 0;
                                   default is 0)
         -ks <boolean>        - Sets the 'keep_splitting' attribute (1 or 0;
                                   default is 0)
         -rw <boolean>        - Sets the 'rewriter' attribute (1 or 0; default
                                   is 0)
         -rg <boolean>        - Sets the 'rewrite_global' attribute (1 or 0;
                                   default is 0)
         -o <boolean>         - Sets the 'ignore_case' attribute (1 or 0,
                                   default is 1)
         -a <boolean>         - Sets the 'gag' attribute (1 or 0, default is 0)
         -l <boolean>         - Sets the 'gag_log' attribute (1 or 0, default is
                                   0)
         -pr <boolean>        - Sets the 'need_prompt' attribute (1 or 0,
                                   default is 0)
         -lg <boolean>        - Sets the 'need_login' attribute (1 or 0, default
                                   is 0)
         -k <boolean>         - Sets the 'keep_checking' attribute (1 or 0;
                                   default is 1)
         -dp <boolean>        - Sets the 'default_pane' attribute (1 or 0;
                                   default is 0)
         -pn <string>         - Sets the 'pane_name' attribute. If not
                                   specified, an empty string is used
         -t <boolean>         - Sets the 'temporary' attribute (1 or 0; default
                                   is 0)
         -cd <number>         - Sets the 'cooldown' attribute (0 or above;
                                   default is 0)
         -m <mode>            - Sets the 'style_mode' attribute (-2, -1, 0 or
                                   1+; default is 0)
         -h <colour>          - Sets the 'style_text' attribute (0 or an Axmud
                                   text colour tag; default is 0)
         -j <underlay>        - Sets the 'style_underlay' attribute (0 or an
                                   Axmud underlay colour tag; default is 0)
         -it <style>          - Sets the 'style_italics' attribute (0, 1 or 2;
                                   default is 0)
         -u <style>           - Sets the 'style_underline' attribute (0, 1 or 2;
                                   default is 0)
         -bs <style>          - Sets the 'style_blink_slow' attribute (0, 1 or
                                   2; default is 0)
         -bf <style>          - Sets the 'style_blink_fast' attribute (0, 1 or
                                   2; default is 0)
         -q <style>           - Sets the 'style_strike' attribute (0, 1 or 2;
                                   default is 0)
         -lk <style>          - Sets the 'style_link' attribute (0, 1 or 2;
                                   default is 0)

      Group 4 switch options: 0, 1 or more of the following options can be used:
         -b <name>            - This trigger is checked before triggers called
                                   <name> (when they both become active)
         -f <name>            - This trigger is checked after triggers called
                                   <name> (when they both become active)

   General interface notes:
      If <instruction>, <pattern>, <string> or <substitution> contain
         whitespace, they must be enclosed by diamond brackets

            e.g. <You see (.*) exits>

      <boolean> can be typed as 1 or 0, or any word beginning with t, T, f or F

   User commands:
      atr / addtrig / addtrigger
