Methods

Each rule may consist of following operations, that will be compiled into methods.

Where

where element is compiled into a method that has a single parameter Source and returns true or false. Source parameter represents the form that is being evaluated.

The where element value consists only of the expression without a return keyword and without ; at the end, for example:

<where>
  Source.HasKeyword("LightArmor")
</where>

The expression is evaluated and the result is passed back to the engine indicating whether the form meets the criteria of the rule. Only if the returned value is true the operations associated with this rule will be applied to the form.

The expression may consist of several operands and logical operators such as !, && and || but remember that in an XML file you cannot use & (and <) directly:

<where>
  Source.Name.Contains("Iron") &amp;&amp; Source.Armatures.Count &lt; 5
</where>

An alternative is to use CDATA like this:

<where><![CDATA[
  Source.Name.Contains("Iron") && Source.Armatures.Count < 5
]]></where>

TIP: Performance cost of where methods should be considered because it will be called for each form of the queried type. The engine will try to optimize expressions when it can, such as when a single indexed property is being compared, such as Source.EditorId == "SomeEditorID", however.

Select

select element is compiled into a method that has a single parameter Source and returns no value. Source parameter represents the form that has met the criteria of the rule.

It is not possible to changes any form in this operation, i.e. the operation does not override or copy the source form. The following example demonstrates a select element that adds a tag to the form:

<select>
  Source.Tag("ProcessMeLater");
</select>

A select operation may also assist during rule development because it allows printing information about the form without overriding or copying:

<select>
  Debug.Message("Found form: " + Source.EditorId);
</select>

When select elements that are part of a non-query rule (meaning a rule that lacks the from element) the Source parameter will not be available. One can still retrieve forms via Forms.Find() and similar methods and tag them for later.

Update

update element is compiled into a method that has two parameters, Source and Target and returns true or false. Source parameter represents the form that has met the criteria of the rule and Target parameter represents a copy of that form that will accept changes made inside the method. If the method returns true the copy will replace the original form.

It is not necessary to add an explicit return true; statement at the end because it will be added automatically. Using a return statement in an update operation is only useful in case, based on some condition, the update operation needs to be cancelled and the modified copy thrown away.

<update>
  if (Source.Type != 'i')
    return false; // Cancel update if not integer type
  Target.Value = Source.Value + 10;
</update>

Insert

insert elements are compiled into methods that have two parameters, Source and Target and return true or false. Source parameter represents the form that has met the criteria of the rule and Target parameter represents a new form that will accept changes made inside the method. If the method returns true the new form will be accepted as a new form.

As with the update operation it is not necessary to add an explicit return true; statement at the end.

When insert elements that are part of a non-query rule (meaning a rule that lacks the from element) the Source parameter will not be available.

There is no limit how many insert operations one rule can do.

Each insert element must specify the kind of form that will be created with attribute into, e.g. GLOB:

<insert into="GLOB">
  Target.EditorID = "NewGlobal";
  Target.Type = `f`;
  Target.Value = 0.3f;
</insert>

At the beginning of an insert operation the form represented by parameter Target is empty and all properties that are supposed to be set must be assigned a value.

An insert element may define two additional attributes:

• copy - Copies all data from the Source form to the Target form before the rule is run. This attribute is only allowed when the Source form is the same kind as the Target form. Expected values are true or false. Data are not copied by default.
• as - Explicitly specifies the Form ID of the new form, up to 6 hexadecimal digits, e.g. 00AB34. This feature can be also used to create forms that will inject into other plugins by specifying the full Form ID including the plugin index, e.g. 0100AB34.