Tag Terms - Revision history

Colen: /* Field Value Tests */

2013-12-20T05:46:50Z

Field Value Tests

← Older revision		Revision as of 05:46, 20 December 2013
Line 83:		Line 83:
	*In addition to a variety of standard tag expressions within a thing/pick context, access to field values can also be utilized from within most scripts. Any time that a pick target context is accessed from within a script, the "tagexpr[...]" target reference can safely utilize a field value references against the fields within that context.		*In addition to a variety of standard tag expressions within a thing/pick context, access to field values can also be utilized from within most scripts. Any time that a pick target context is accessed from within a script, the "tagexpr[...]" target reference can safely utilize a field value references against the fields within that context.
	*Do NOT use field value access as a crutch within tag expressions. Field value access from tag expressions is significantly more expensive to process than testing a tag, so use tags whenever possible and only use field values when absolutely necessary.		*Do NOT use field value access as a crutch within tag expressions. Field value access from tag expressions is significantly more expensive to process than testing a tag, so use tags whenever possible and only use field values when absolutely necessary.

			As well as testing values of numeric fields, you can also test whether text fields are empty by using "fieldisempty:". You can use this to, for example, display all picks in a table who have a certain text field set.

			<pre>
			!fieldisempty:foo
			</pre>

	==Explicit Scope Restrictions==		==Explicit Scope Restrictions==

Mathias: /* Explicit Scope Restrictions */

2008-12-17T20:32:47Z

Explicit Scope Restrictions

← Older revision		Revision as of 20:32, 17 December 2008
Line 100:		Line 100:
	</pre>		</pre>

	{{note}}Unlike with ~~script~~, you '''cannot''' transition through the hierarchy within the tag terms. You can test tags on the current context or directly on the hero. Those are the only options, and they will be all you need 99.9% of the time.		{{note}}Unlike with scripts, you '''cannot''' transition through the hierarchy within the tag terms. You can test tags on the current context or directly on the hero. Those are the only options, and they will be all you need 99.9% of the time.

Rob: /* Explicit Scope Restrictions */

2008-12-17T10:05:09Z

Explicit Scope Restrictions

← Older revision		Revision as of 10:05, 17 December 2008
Line 99:		Line 99:
	val:hero#group.tag		val:hero#group.tag
	</pre>		</pre>

			{{note}}Unlike with script, you '''cannot''' transition through the hierarchy within the tag terms. You can test tags on the current context or directly on the hero. Those are the only options, and they will be all you need 99.9% of the time.

Rob at 08:29, 22 November 2008

2008-11-22T08:29:05Z

← Older revision		Revision as of 08:29, 22 November 2008
Line 1:		Line 1:
	~~[[Category:~~Basic Concepts and Terminology]]		{{context\|Basic Concepts and Terminology\|Tags and Tag Expressions}}
	~~[Context: [[Home~~\|~~HL Kit]] [[Basic Concepts and Terminology]] [[~~Tags and Tag Expressions~~]]]~~

	==Overview==		==Overview==

Rob: /* Tag Value Extraction */

2008-11-21T14:03:00Z

Tag Value Extraction

← Older revision		Revision as of 14:03, 21 November 2008
Line 59:		Line 59:
	If a tag does not end in any digits, then the tag will yield "no" value, which will be treated as a value of zero when an integer value is required for the tag. For example, the tag "blue567xyz" would yield no value, since only the trailing digits are used and all earlier digits are ignored.		If a tag does not end in any digits, then the tag will yield "no" value, which will be treated as a value of zero when an integer value is required for the tag. For example, the tag "blue567xyz" would yield no value, since only the trailing digits are used and all earlier digits are ignored.

	~~'''NOTE!'''~~ Depending on the situation, there may be a critical distinction between a tag with "no" value and a tag with a "zero" value.		{{note}}Depending on the situation, there may be a critical distinction between a tag with "no" value and a tag with a "zero" value.

	Be sure to keep the following issues in mind when dealing with tag values:		Be sure to keep the following issues in mind when dealing with tag values:
Line 65:		Line 65:
	*Negative values are never extracted from tags, since only digits are considered when extracting the value.		*Negative values are never extracted from tags, since only digits are considered when extracting the value.
	*Under some circumstances, a tag will have no value and be referenced as if it has a value. Tags with "no" value are ignored in those situations (e.g. within summations and averages), while a tag with a "zero" value is processed with that value.		*Under some circumstances, a tag will have no value and be referenced as if it has a value. Tags with "no" value are ignored in those situations (e.g. within summations and averages), while a tag with a "zero" value is processed with that value.
	*An object that does not have any tags matching the specified template and for which a value is referenced will '''never''' satisfy an arithmetic comparison under any circumstances. For example, the comparison "val:attack.? < 3" will always fail for any object that has '''no''' tag from the "attack" group. Similarly, the comparison "val:attack.? >= 3" will also fail for those same objects. If an object has no value, it can never be compliant with a value-based comparison.		*An object that does not have any tags matching the specified template and for which a value is referenced will '''never''' satisfy an arithmetic comparison under any circumstances. For example, the comparison "val:attack.? < 3" will always fail for any object that has '''no''' tag from the "attack" group. Similarly, the comparison "val:attack.? >= 3" will also fail for those same objects. If an object has no value, it can never be compliant with a value-based comparison.

	==Field Value Tests==		==Field Value Tests==

Rob: /* Arithmetic Comparison Terms */

2008-11-21T14:02:42Z

Arithmetic Comparison Terms

← Older revision		Revision as of 14:02, 21 November 2008
Line 47:		Line 47:
	\|}		\|}

	~~'''NOTE!'''~~ The prefix may optionally be omitted from a tag term within an arithmetic expression. If no prefix is specified, then the default prefix of "count" is assumed. Therefore, the term "color.blue" is equivalent to "count:color.blue" within an arithmetic comparison term, such as below.		{{note}}The prefix may optionally be omitted from a tag term within an arithmetic expression. If no prefix is specified, then the default prefix of "count" is assumed. Therefore, the term "color.blue" is equivalent to "count:color.blue" within an arithmetic comparison term, such as below.

	<pre>		<pre>

Rob: /* Arithmetic Comparison Terms */

2008-11-21T14:02:26Z

Arithmetic Comparison Terms

← Older revision		Revision as of 14:02, 21 November 2008
Line 43:		Line 43:
	\|val:template		\|val:template
	\|The first tag that matches the specified template is identified, and an integer value is extracted from that tag and returned. Integer value extraction is described below. Example: "val:cost.gold?".		\|The first tag that matches the specified template is identified, and an integer value is extracted from that tag and returned. Integer value extraction is described below. Example: "val:cost.gold?".
	~~NOTE!~~ If the template matches multiple tags, there is no guarantee which tag will be retrieved, so this form should only be used when you know there is a single tag matching the template assigned to the object. Using this form is much more efficient that the "low" and "high" forms, so make use of it whenever it is safe to do so.		{{note}}If the template matches multiple tags, there is no guarantee which tag will be retrieved, so this form should only be used when you know there is a single tag matching the template assigned to the object. Using this form is much more efficient that the "low" and "high" forms, so make use of it whenever it is safe to do so.
	\|-		\|-
	\|}		\|}

Rob: /* Explicit Scope Restrictions */

2008-11-17T11:47:25Z

Explicit Scope Restrictions

← Older revision		Revision as of 11:47, 17 November 2008
Line 95:		Line 95:
	</pre>		</pre>

	OR		OR

	<pre>		<pre>
	val:hero#group.tag		val:hero#group.tag
	</pre>		</pre>

Rob at 11:46, 17 November 2008

2008-11-17T11:46:41Z

← Older revision		Revision as of 11:46, 17 November 2008
Line 55:		Line 55:
	==Tag Value Extraction==		==Tag Value Extraction==

	Every tag can be converted to an integer value. Extracting an integer value from a tag utilizes the unique id of the tag. Starting at the end of the tag’s id, all digits are extracted until a non-digit is encountered. Those digits are then converted to an integer value. For example, integer value extraction from the tag ~~“blue1234”~~ would yield the value ~~“1234”~~. Similarly, the tag ~~“blue5x123”~~ would yield the value ~~“123”~~.		Every tag can be converted to an integer value. Extracting an integer value from a tag utilizes the unique id of the tag and not its name. Starting at the '''end''' of the tag’s unique id, all digits are extracted until a non-digit is encountered. Those digits are then converted to an integer value. For example, integer value extraction from the tag "blue1234" would yield the value "1234". Similarly, the tag "blue5x123" would yield the value "123".

	If a tag does not end in any digits, then the tag will yield "no" value, which will be treated as a value of zero when an integer value is required for the tag. For example, the tag ~~“blue567xyz”~~ would yield no value, since only the trailing digits are used and all earlier digits are ignored~~. Depending on the situation, there may be a critical distinction between a tag with “no” value and a tag with a “zero” value~~.		If a tag does not end in any digits, then the tag will yield "no" value, which will be treated as a value of zero when an integer value is required for the tag. For example, the tag "blue567xyz" would yield no value, since only the trailing digits are used and all earlier digits are ignored.

	~~Keep~~ the ~~following issues in mind when dealing~~ with tag ~~values:~~		'''NOTE!''' Depending on the situation, there may be a critical distinction between a tag with "no" value and a tag with a "zero" value.

	* Negative values are never extracted from tags, since only digits are considered when extracting the ~~value.~~		Be sure to keep the following issues in mind when dealing with tag values:
	* Under some circumstances, a tag will have no value and be referenced as if it has a value. Tags with “no” value are ignored in ~~those situations (i.e. within summations and averages), while a tag with a “zero” value is processed~~ with ~~that value.~~
	* An object that does not have any tags matching the specified template and for which a value is referenced will never satisfy an arithmetic comparison under any circumstances. For example, the comparison “val:attack.? < 3” will always fail for any object that has no tag ~~from the “attack” group. Similarly, the comparison “val~~:~~attack.? >= 3” will also fail for those same objects. If an object has no value, it can never be compliant with a value-based comparison.~~

	~~Field Value Tests~~		*Negative values are never extracted from tags, since only digits are considered when extracting the value.
			*Under some circumstances, a tag will have no value and be referenced as if it has a value. Tags with "no" value are ignored in those situations (e.g. within summations and averages), while a tag with a "zero" value is processed with that value.
			*An object that does not have any tags matching the specified template and for which a value is referenced will '''never''' satisfy an arithmetic comparison under any circumstances. For example, the comparison "val:attack.? < 3" will always fail for any object that has '''no''' tag from the "attack" group. Similarly, the comparison "val:attack.? >= 3" will also fail for those same objects. If an object has no value, it can never be compliant with a value-based comparison.

	There are times when tracking a piece of information for an object really needs to be handled via a field value, yet you still need to test that state within tag expressions. One option would be to maintain both the field value and a corresponding tag that can be tested in a tag expression, but that approach quickly becomes difficult to maintain. To alleviate this, ~~Hero Lab~~ allows direct access to field values from within tag expressions.		==Field Value Tests==

			There are times when tracking a piece of information for an object really needs to be handled via a field value, yet you still need to test that state within tag expressions. One option would be to maintain both the field value and a corresponding tag that can be tested in a tag expression, but that approach quickly becomes difficult to maintain. To alleviate this, the Kit allows direct access to field values from within tag expressions.

	You can reference field values using the syntax "fieldval:fieldid", where "fieldid" is replaced by the unique id of the field to access. Other than that, you can utilize field references just like any other arithmetic comparison term within the tag expression. For example, the tag expression "fieldval:strength < 10" would be satisfied if the object possesses a "strength" field and that field has a value of less than 10.		You can reference field values using the syntax "fieldval:fieldid", where "fieldid" is replaced by the unique id of the field to access. Other than that, you can utilize field references just like any other arithmetic comparison term within the tag expression. For example, the tag expression "fieldval:strength < 10" would be satisfied if the object possesses a "strength" field and that field has a value of less than 10.
Line 73:		Line 75:
	Only the fields for the appropriate object context can be referenced via tag expressions. Consequently, if the tag expression is being applied to a pick, only the fields defined for that pick can be referenced. If a field reference is used within a tag expression that either is not a pick/thing context or does not contain the specified field, a run-time error is reported to the user. If a tag expression will be used against things/picks that derive from different component sets and may not all possess a particular field, the author can include a test for the needed component within the tag expression to verify the presence of the field before accessing it. For example, if the field "foo" is defined within the "compid" component, the following syntax can be used to safely test the field value:		Only the fields for the appropriate object context can be referenced via tag expressions. Consequently, if the tag expression is being applied to a pick, only the fields defined for that pick can be referenced. If a field reference is used within a tag expression that either is not a pick/thing context or does not contain the specified field, a run-time error is reported to the user. If a tag expression will be used against things/picks that derive from different component sets and may not all possess a particular field, the author can include a test for the needed component within the tag expression to verify the presence of the field before accessing it. For example, if the field "foo" is defined within the "compid" component, the following syntax can be used to safely test the field value:

			<pre>
	(component.compid & (fieldval:foo >= 1))		(component.compid & (fieldval:foo >= 1))
			</pre>

	~~Keep~~ the following important issues in mind when utilizing field values via tag expressions:		Be sure to keep the following important issues in mind when utilizing field values via tag expressions:

	* Since only things and picks possess fields, access to field values will only work when the target object is a thing or a pick. There are times this might not be immediately obvious. For example, you might assume that field values can be referenced within a thing "condition" tag expression, except that the "condition" test is applied against the tags of the container, which means there is no thing/pick context to retrieve any fields from.		*Since only things and picks possess fields, access to field values will only work when the target object is a thing or a pick. There are times this might not be immediately obvious. For example, you might assume that field values can be referenced within a thing "condition" tag expression, except that the "condition" test is applied against the tags of the container, which means there is no thing/pick context to retrieve any fields from.
	* In addition to a variety of standard tag expressions within a thing/pick context, access to field values can also be utilized from within ~~certain~~ scripts. Any time that a pick target context is accessed from within a script, the "tagexpr[...]" ~~syntax~~ can utilize a field value references against the fields within that context.		*In addition to a variety of standard tag expressions within a thing/pick context, access to field values can also be utilized from within most scripts. Any time that a pick target context is accessed from within a script, the "tagexpr[...]" target reference can safely utilize a field value references against the fields within that context.
	* Do NOT use field value access as a crutch within tag expressions. Field value access from tag expressions is significantly more expensive to process than testing a tag, so use tags whenever possible and only use field values when absolutely necessary.		*Do NOT use field value access as a crutch within tag expressions. Field value access from tag expressions is significantly more expensive to process than testing a tag, so use tags whenever possible and only use field values when absolutely necessary.

	Explicit Scope Restrictions		==Explicit Scope Restrictions==

	While not common, situations will arise where you'll want to test the tags of a thing/pick and the tags of the hero to determine whether a tag expression should be satisfied. ~~This~~ is ~~extremely important when~~ the ~~user-selection~~ of ~~various options enables or disables access to other options~~. ~~The user-selected options can simply~~ assign ~~tags~~ to the ~~hero to convey their selection~~, and ~~those tags can then be tested within~~ tag ~~expressions that normally focus~~ on ~~a thing/pick as their context~~.		While not common, situations will arise where you'll want to test the tags of a thing/pick and the tags of the hero to determine whether a tag expression should be satisfied. For example, consider a situation where an assortment of things is only available if the actor belongs to a particular group of classes. Assuming those classes assign an identifiable tag to the actor, you could filter the things displayed based on the presence of appropriate tags on the things and the tag on the actor.

	To support ~~this~~, any tag template used within a tag expression can specify a prefix of "hero#" on the template. When this prefix is assigned, the tag template is compared directly against the tags of the containing hero context, even if a pick or a child container is the established context. For this to work, the prefix must appear immediately prior to the tag template, such as in the examples below.		To support these situations, any tag template used within a tag expression can specify a prefix of "hero#" on the template. When this prefix is assigned, the tag template is compared directly against the tags of the containing hero context, even if a pick or a child container is the established context. For this to work, the prefix must appear immediately prior to the tag template, such as in the examples below.

			<pre>
	group.tag & hero#group.tag		group.tag & hero#group.tag
			</pre>

	OR		OR

			<pre>
	val:hero#group.tag		val:hero#group.tag
			</pre>

Rob at 11:33, 17 November 2008

2008-11-17T11:33:03Z

← Older revision		Revision as of 11:33, 17 November 2008
Line 49:		Line 49:
	'''NOTE!''' The prefix may optionally be omitted from a tag term within an arithmetic expression. If no prefix is specified, then the default prefix of "count" is assumed. Therefore, the term "color.blue" is equivalent to "count:color.blue" within an arithmetic comparison term, such as below.		'''NOTE!''' The prefix may optionally be omitted from a tag term within an arithmetic expression. If no prefix is specified, then the default prefix of "count" is assumed. Therefore, the term "color.blue" is equivalent to "count:color.blue" within an arithmetic comparison term, such as below.

			<pre>
	(color.blue >= 1)		(color.blue >= 1)
			</pre>

	==Tag Value Extraction==		==Tag Value Extraction==