Autoparse

Autoparse is a small project to make the automatizer file more human-readable and -writable. It consists of a replacement auto.lua file with

As a matter of historical interest, we also include the original autoparse.pl Perl script that was used to convert ATP automatizer files to XML before the replacement auto.lua was written.

Version

auto.lua: ca. 2007-01-07

Sample ATP automatizer file: ca. 2007-01-24

Perl conversion script: ca. 2007-01-01

Known bugs

Other bugs can be added here.

Using

To use ATP automatizer files, you have two options:

Rule tester

Ever been frustrated trying to figure out why your lovingly hand-crafted automatizer rule isn't matching items you think it should match? Well, now you can find out why. The replacement auto.lua file adds a new utility, accessible as a power under the 'U' menu ('O' if you're using the roguelike keyset), to test an automatizer rule against an item in your inventory.

The power will prompt you for an item and for a rule to test, and then will display a color-code listing of the selected rule, in English or XML (depending on what setting you set the last time you accessed the automatizer via the '=' menu). Subclauses that match the selected item will be listed in green, while subclauses that don't match will be displayed in red.

[Note that the automatizer is run as a matter of course after invoking any 'U'-menu power, so if your destroy rule lists as successfully matching your selected test item, the item will in fact be destroyed as soon as you exit the listing.]

New clauses

The replacement auto.lua supports two new matching clauses, inventory and equipment, which match if something in your inventory or equipment, respectively, matches the contained subclause. For instance, to destroy torches if you're wielding a brass lantern, you could say, in ATP: 

rule "destroy torches" destroy if
  name = "Wooden Torch" and equipment ( name = "Brass Lantern" );

or in XML: 

<rule name="destroy torches" type="destroy">
  <and>
    <name>Wooden Torch</name>
    <equipment>
      <name>Brass Lantern</name>
    </equipment>
  </and>
</rule>

The ATP language

The ATP language is intended to be human-readable, so its syntax is fairly English-like. The following example should demonstrate most of its intricacies: 

clean_ruleset()
add_atp_ruleset
[[
module "Fred";    # Rules after this should be used with the Fred module.

# Comments begin with a '#' and extend to end of line.
rule "example rule"            # Rule name is a string, and is required
  destroy if                   # Rule type is 'destroy' or 'pickup'
    not (race = "Elf" or class = Mage or subrace = "LostSoul")
    and (tval = TV_RING, TV_ROD, TV_BOOTS
          or name = "Scroll of Nothing"
          or contain = "potion of restore"
          or tval = 21          # = TV_HAFTED
            and sval = SV_CLUB-SV_MACE, 8, SV_FLAIL, 18-20)
    and skill "Hafted-mastery" = 25-50
    and level = 20-30;         # Rule ends with ';'.

module;          # Rules after this should be used with standard ToME.
]]

The first three lines and the last line are required to make the file usable with ToME's automatizer infrastructure, and must appear exactly as shown; the actual ATP rule descriptions are placed between these lines. The module command specifies that all subsequent rules should be used with the specified module. By default (or after the command "module;", with no module name specified), rules aren't associated with any module, and thus are only used with ToME itself. The special module name "all" specifies that the rules should be used with ToME and all modules.

There are three type of rules: destroy, pickup and inscribe, which do exactly what they sound like they do. For inscribing rules, the inscription to be added to the item is defined in a string after the inscribe token, as in: 

rule "inscribe oil" inscribe "@F1" if name = "Flask of oil";

The meat of the rule is a collection of clauses that describe conditions that must be satisfied for the rule to match:

race
Required character race. Value type is a string or token (a single "word" of alphanumeric characters, with no space or '-').
subrace
Required character subrace. Value type is a string or token.
class
Required character class. Value type is a string or token.
name
Exact name of the item to be matched. Value type is a string, case-insensitive.
contain
Text contained in the name of the item[s] to be matched. Value type is a string, case-insensitive.
symbol
On-screen symbol of the item[s] to be matched. Value type is a single-character string.
state
Whether or not the item has been identified. Value type is one of

identifed or unidentified.

status
Pseudo-ID-like status of the item. Value type is a string, one of the following:

  • "very bad": Corresponds to {worthless} pseudo-ID

  • "bad": Corresponds to {cursed} pseudo-ID

  • "average": Corresponds to {average} pseudo-ID

  • "good": Corresponds to {good} pseudo-ID

  • "very good": Corresponds to {excellent} pseudo-ID

  • "special": Corresponds to {special} pseudo-ID

  • "terrible": Corresponds to {terrible} pseudo-ID

  • "empty": Used for chests

tval
The internal tval, or object type, of the item. Value type is a

number or a TV_* symbol as listed in defines.h.

sval
The internal sval, or object subtype, of the item. Value type is a

number or a SV_* symbol as listed in defines.h, or a range of values specified in the form <min>-<max>.

level
Required character level. Value type is a numeric range specified

in the form <min>-<max>.

skill
Required skill level. This clause has two value types: the skill

name, specified as a string before the =, and a numeric range, specified in the form <min>-<max> after the =.

ability
Required ability. Value type is the ability name, specified as a string.
inscribed
Text contained in the inscription on the item[s] to be matched. Value type is a string, case-insensitive. Requires ToME 2.2.0 or higher.
discount
The item's discount. Value type is a numeric range specified

in the form <min>-<max>. Requires ToME 2.2.0 or higher.

For all clauses except level, skill and discount, a comma-separated list of values may be specified; this is equivalent to several separate clauses joined by or.

There are two additional clauses with different syntax; they must be followed by a parenthesized clause (or group of clauses combined with and and or in the usual way), and specifies that some other item or items must match the specified conditions:

inventory
Some item in the player's inventory must match the specified conditions.
equipment
Some item in the player's equipment must match the specified conditions.

See the example above.

Clauses can then be combined in the obvious way with and and or. Comma-separated lists have higher precedence for grouping purposes than and, which in turn has higher precedence than or; so, for instance, 

clean_ruleset()
add_atp_ruleset
[[
rule "yeeg" destroy if race=Orc and class=Mage or
                       race=Ent and class=Warrior;
]]

translates to: 

clean_ruleset()
add_ruleset
[[
<rule name="yeeg" type="destroy">
  <or>
    <and>
      <race>Orc</race>
      <class>Mage</class>
    </and>
    <and>
      <race>Ent</race>
      <class>Warrior</class>
    </and>
  </or>
</rule>
]]

and: 

clean_ruleset()
add_atp_ruleset
[[
rule "blarg" destroy if class=Mage or race=Ent, Orc and level=12-50;
]]

translates to: 

clean_ruleset()
add_ruleset
[[
<rule name="blarg" type="destroy">
  <or>
    <class>Mage</class>
    <and>
      <or>
        <race>Ent</race>
        <race>Orc</race>
      </or>
      <level min="12" max="50"></level>
    </and>
  </or>
</rule>
]]

If in doubt, you can use the Perl conversion script to convert your ATP to XML and back to ATP, which will be fully parenthesized as the parser grouped it.

Chatter

DarkGod: Hey looks kinda nice :)

ZizzoTheInfinite/Autoparse (last edited 2007-01-25 10:40:56 by DarkGod)