$tags

Get or set annotations for a Struct.

Struct->$tags

Return Values

The value returned by $tags depends on whether Struct refers to a single Struct or to multiple Structs.

Return Values
Return Value	When
Struct containing annotations	Struct refers to exactly one Struct.
Collection of references to the $tags of multiple Structs	Struct is a collection of references to multiple Structs
`NULL`	Struct does not refer to a Struct.

Values of $procerror Commonly Returned Following Struct Functions
Value	Error Constant	Meaning
`-84`	`UACTERR_NO_OBJECT`	Struct refers to zero Structs
`-1151`	`USTRUCTERR_NO_COMMON_CHARACTERISTICS`	Collection of Structs that do not share a common parent or the specified characteristic
`-1157`	`USTRUCTERR_ILLEGAL_MEMBER_TYPE`	Not a valid Struct member type

Description

When a new Struct is created, a special child Struct is also created to hold annotations. In the string representation of the Struct returned by the $dbgstring, the $tags struct is visible as [$tags] beneath its parent Struct. For example:

[]
  [div]
    [$tags]
      [xmlClass] = element
    [class] = note
      [$tags]
        [xmlClass] = attribute
    Text can be bold

The annotation in the $tags Struct can be accessed using the $tags Struct function. For example:

vClass = MyStruct->div->$tags->xmlClass

Unlike normal Struct members, annotations have no specific position inside the Struct, and are therefore not counted, or treated as members of the Struct. This is in contrast to, for example, XML process instructions, which are treated as normal Struct members because their position in an XML document is relevant, even if they are not part of the document contents.

Annotations are specific to the format, so componentToStruct has different annotations than xmlToStruct.

When preparing Structs for conversion to another format, you can set the values of $tags to guide the conversion.

For more information, see Struct Annotations.

Setting a Tag

The following code sets the xmlClass tag for a Struct to element:

vStruct->$tags->xmlClass="element"

History
Version	Change
9.5.01	Introduced