Eval Element (Data): Difference between revisions

From HLKitWiki
Jump to navigationJump to search
No edit summary
No edit summary
Line 4: Line 4:


A major facet of data file authoring it defining scripts on components and things for [[Scripting Basics|execution during the evaluation cycle]]. These scripts are referred to as [[Eval Script|Eval scripts]] and are invoked on each individual pick within the actor. Each separate script is specified through the use of an "eval" element. The complete list of attributes for this element is below.
A major facet of data file authoring it defining scripts on components and things for [[Scripting Basics|execution during the evaluation cycle]]. These scripts are referred to as [[Eval Script|Eval scripts]] and are invoked on each individual pick within the actor. Each separate script is specified through the use of an "eval" element. The complete list of attributes for this element is below.
{{note}}For more information on limits and sorting, please see [[Advanced Script Handling]].


:{| class="infotable"
:{| class="infotable"
Line 16: Line 18:
|-
|-
|runlimit
|runlimit
|(Optional) Integer – Specifies the maximum number of times this script will be invoked during the evaluation cycle for each container. For example, you may have a situation where a script needs to be invoked only if a particular thing is added to a container, but you only want the script invoked a single time, regardless of how many times the thing is added. To solve this, you can specify the "runlimit" as one. A value of zero indicates no limit. Default: "0".
|(Optional) Integer – Specifies the maximum number of times this script will be invoked during the evaluation cycle for each container. A value of zero indicates no limit. Default: "0".
{{note}}The limit is imposed separately within each container, so no the script will always be invoked for picks within different containers.
{{note}}The limit is imposed separately within each container, so the script will always be invoked for picks within different containers.
|-
|-
|iseach
|iseach
|(Optional) Boolean – Indicates whether the "runlimit" applies individually to each thing or collectively to all things derived from the component. If the latter, the script will be treated as a script that is invoked a limited number of times, regardless of how many different picks exist that are derived from the component. If the former, picks derived from each different thing have their own limit. Obviously, this attribute is only applicable to script defined for a component. Default: "yes".
|(Optional) Boolean – Indicates whether the "runlimit" applies individually to each thing or collectively to all things derived from the component. This attribute is only applicable component scripts. Default: "yes".
|-
|-
|sortas
|sortas
|(Optional) Id – Specifies the unique id of a component for which the script will be sorted when establishing the task evaluation sequence. During task scheduling, if multiple eval scripts are associated with the same component, the corresponding tasks will be sorted using the sorting sequence assigned to the component. This ensures that tasks are always scheduled in a consistent fashion when things are added multiple times to a container. In rare situations, you'll want to ensure that scripts are sorted based on the rules for a different component, in which case this attribute allows to you specify the component to use for that purpose. Obviously, this attribute is only applicable to scripts defined for a component. If empty, the script uses the sequencing for the component it is defined within. Default: Empty.
|(Optional) Id – Specifies the unique id of a different component for which the script will be sorted when establishing the task evaluation sequence. This attribute is only applicable to component scripts. If empty, the script uses the sequencing for the component it is defined within. Default: Empty.
|-
|-
|name
|name
|(Optional) Text – Specifies the name assigned to this script for the purpose of establishing timing dependencies. If empty, no timing dependencies may be defined elsewhere that depend upon this script. Default: Empty.
|(Optional) Text – Specifies the name assigned to this script for the purpose of establishing timing dependencies. If empty, no timing dependencies may be defined elsewhere that depend upon this script. Default: Empty.
|-
|isprimary
|(Optional) Boolean – Indicates whether this task should be considered the "primary" task when multiple tasks are assigned the same name. Default: "no".
|-
|-
|PCDATA
|PCDATA
Line 37: Line 42:
:{| class="infotable"
:{| class="infotable"
|class="leftnormal"|[[#match|match]]
|class="leftnormal"|[[#match|match]]
|An optional "match" element may appear as defined by the given link. This element defines the [[Match Tag Expression]]. If omitted, all things are assumed to match and the container requirement test is applied to them all.
|An optional "match" element may appear as defined by the given link. This element defines a [[Match Tag Expression]] that must be satisfied in order for the script to be assigned to each thing. If omitted, the script is applied to all derived things.
{{important}}This element is only applicable when the container requirement is defined within a component. In all other cases, this element may not be specified.
{{important}}This element is only applicable when the condition test is defined within a component. In all other cases, this element may not be specified.
|-
|-
|[[Before/After Element (Data)|before]]
|[[Before/After Element (Data)|before]]
|Zero or more "before" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the container requirement.
|Zero or more "before" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the script.
|-
|-
|[[Before/After Element (Data)|after]]
|[[Before/After Element (Data)|after]]
|Zero or more "after" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the container requirement.
|Zero or more "after" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the script.
|-
|-
|}
|}
Line 50: Line 55:
==The "match" Element{{anchor|match}}==
==The "match" Element{{anchor|match}}==


The "match" element defines the [[Match Tag Expression|Match tag expression]] that determines whether a particular thing is subject to the container requirement. The tag expression is applied against each thing derived from the component, and the requirement is only assigned to things that satisfy the tag expression. The complete list of attributes for this element is below.  
The "match" element defines the [[Match Tag Expression|Match tag expression]] that determines whether a particular thing is assigned the eval script. The tag expression is applied against each thing derived from the component, and the script is only assigned to things that satisfy the tag expression. The complete list of attributes for this element is below.  


:{| class="infotable"
:{| class="infotable"
Line 60: Line 65:
==Example==
==Example==


The following example demonstrates what a "containerreq" element might look like. All default values are assumed for optional attributes.
The following example demonstrates what an "eval" element might look like. All default values are assumed for optional attributes.


<pre>
<pre>
<containerreq phase="Setup" priority="500" name="MyTest>
<eval index="1" phase="Setup" priority="500">
   <before name="BeforeTest"/>
   <before name="BeforeTest"/>
   <after name="AfterTest"/>
   <after name="AfterTest"/>
   val:Level.? >= 4
   debug "Script Executing"
   </containerreq>
   </eval>
</pre>
</pre>

Revision as of 02:04, 29 November 2008

Context: HL Kit &#133; Kit Reference  &#133; Multiple Sources

The "eval" Element

A major facet of data file authoring it defining scripts on components and things for execution during the evaluation cycle. These scripts are referred to as Eval scripts and are invoked on each individual pick within the actor. Each separate script is specified through the use of an "eval" element. The complete list of attributes for this element is below.

NOTE! For more information on limits and sorting, please see Advanced Script Handling.

phase Id – Specifies the unique id of the evaluation phase during which the script is invoked.
priority Integer – Specifies the evaluation priority during which the script is invoked.
index (Optional) Integer – Assigns an arbitrary, but unique, value to this script. This index is used within error messages to identify the script where the problem occurs. If the script is assigned a name (below), no index is necessary. Default: "1".
runlimit (Optional) Integer – Specifies the maximum number of times this script will be invoked during the evaluation cycle for each container. A value of zero indicates no limit. Default: "0".

NOTE! The limit is imposed separately within each container, so the script will always be invoked for picks within different containers.

iseach (Optional) Boolean – Indicates whether the "runlimit" applies individually to each thing or collectively to all things derived from the component. This attribute is only applicable component scripts. Default: "yes".
sortas (Optional) Id – Specifies the unique id of a different component for which the script will be sorted when establishing the task evaluation sequence. This attribute is only applicable to component scripts. If empty, the script uses the sequencing for the component it is defined within. Default: Empty.
name (Optional) Text – Specifies the name assigned to this script for the purpose of establishing timing dependencies. If empty, no timing dependencies may be defined elsewhere that depend upon this script. Default: Empty.
isprimary (Optional) Boolean – Indicates whether this task should be considered the "primary" task when multiple tasks are assigned the same name. Default: "no".
PCDATA Script – Specifies the code comprising the Eval script.

The "eval" element also possesses child elements that pertain to the handling of the script. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

match An optional "match" element may appear as defined by the given link. This element defines a Match Tag Expression that must be satisfied in order for the script to be assigned to each thing. If omitted, the script is applied to all derived things.

IMPORTANT! This element is only applicable when the condition test is defined within a component. In all other cases, this element may not be specified.

before Zero or more "before" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the script.
after Zero or more "after" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the script.

The "match" Element

The "match" element defines the Match tag expression that determines whether a particular thing is assigned the eval script. The tag expression is applied against each thing derived from the component, and the script is only assigned to things that satisfy the tag expression. The complete list of attributes for this element is below.

PCDATA TagExpr – Specifies the code comprising the Match tag expression.

Example

The following example demonstrates what an "eval" element might look like. All default values are assumed for optional attributes.

<eval index="1" phase="Setup" priority="500">
  <before name="BeforeTest"/>
  <after name="AfterTest"/>
  debug "Script Executing"
  </eval>