Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

tree_def - Define a new tree array

CONTENTS

Synopsis
Description
Imploded Tree Arrays
Exploded Tree Arrays
Error Handling
Examples
See Also
Author

itree/def write, ![target], [name]
itree/local write, [name]
itree/static write, [name]
itree/global write, [name]

itree/bdef write, ![target], [name]
itree/blocal write, [name]
itree/bstatic write, [name]
itree/bglobal write, [name]

xtree/def write, ![target], [name]
xtree/def write, ![target], [name], ![root]
xtree/local write, [name]
xtree/local write, [name], ![root]
xtree/static write, [name]
xtree/static write, [name], ![root]
xtree/global write, [name]
xtree/global write, [name], ![root]

xtree/bdef write, ![target], [name]
xtree/bdef write, ![target], [name], ![root]
xtree/blocal write, [name]
xtree/blocal write, [name], ![root]
xtree/bstatic write, [name]
xtree/bstatic write, [name], ![root]
xtree/bglobal write, [name]
xtree/bglobal write, [name], ![root]

Defines a new tree array object. The itree family of instructions uses the class psTreeImp (imploded). The xtree family uses the class psTreeExp (exploded). The array will be called name, which for imploded tree arrays also serves as the name of the root node within the array. A reference to the resulting tree array object will be stored in the write register as a PSUNIT_TYPE_NODE.

The def, local, static and global variants will create objects that do not have the psTreeRoot attribute set to TRUE. The bdef, blocal, bstatic and bglobal variants create objects that have the psTreeRoot attribute set to TRUE. See IMPLODED TREE ARRAYS or EXPLODED TREE ARRAYS below for a further explanation of this attribute.

The def and bdef forms take a target argument, which is the object underneath which to create the new array.

The local, static and global instructions have the same scope as var/local, var/static and var/global. See the var_def(5) man page for details.

In all cases, if the object already exists the necessary classes and attributes will be added to the object to make it suitable for use as a tree array. If the target object was already an imploded tree array and one of the itree instructions are used, the original array will be replaced by a new array. Conversely, exploded tree arrays are not replaced in this manner. If the psTreeRoot attribute already existed on the target object, and this is not an itree/b or xtree/b variant, then this attribute will be removed.

The name may be a dot-separated path if the node is to be created underneath a subcontainer. If the path doesn’t already exist, it will be created. If a dot needs to be used in a name then prefix it with a backslash character (\).

Exploded tree arrays will be rooted at the new array object unless the optional alternative root argument is given. This provides the location in the nexus where the array should be rooted. If the psTreeRoot attribute is set to TRUE e.g. if one of the xtree/b variants were used, this root object may be modified as a member of the array. See EXPLODED TREE ARRAYS for a further discussion of this attribute and its effect on exploded tree arrays.

An imploded tree array is a tree structure identical in functionality to the nexus but that is detached from the nexus in that it has its own root node named after the tree array object itself. A pointer to the root node is stored in the psTreeImp attribute assigned to the tree array object.

An imploded tree array is manipulated using the itree family of instructions. It is distinct from an exploded tree array, see EXPLODED TREE ARRAYS.

An imploded tree array may be addressed using the itree/addr or itree/set instructions, both of which take an index argument to address the required node within the array. See itree_addr(5) and itree_set(5).

If the psTreeRoot attribute is set to FALSE on the psTreeImp object or is missing, then the index to itree/addr and itree/set must be relative to the root node, i.e. will not include the name of the root node itself. This is the default behaviour if the array is not created using the itree/b variant forms.

If the psTreeRoot attribute is set to TRUE on the psTreeImp object, then the index passed to itree/addr and itree/set must be absolute including the root node. This is the default behaviour if the array is created using the itree/b variant forms. In this mode the root node becomes index-addressable.

If a pointer to an object inside the imploded tree array is requested via itree/addr, then reg/dump will report the root node as local instead of global.

An exploded tree array is a tree structure identical in functionality to the nexus that is attached to the nexus either underneath the tree array object itself or at another location identified by the root argument. A pointer to the root node is stored in the psTreeExp attribute assigned to the tree array object.

An exploded tree array is manipulated using the xtree family of instructions. It is distinct from an imploded tree array, see IMPLODED TREE ARRAYS.

An exploded tree array may be addressed using the xtree/addr or xtree/set instructions, both of which take an index argument to address the required node within the array. See xtree_addr(5) and xtree_set(5). Because exploded tree arrays are attached to the nexus, nodes within the array are also addressable in exactly the same way as any other object on the nexus.

If the psTreeRoot attribute is set to FALSE on the psTreeExp object or is missing, then the index to xtree/addr and xtree/set must be relative to the root node, i.e. will not include the name of the root node itself. This is the default behaviour if the array is not created using the xtree/b variant forms.

If the psTreeRoot attribute is set to TRUE on the psTreeExp object, then the index passed to xtree/addr and xtree/set must be absolute including the root node. This is the default behaviour if the array is created using the xtree/b variant forms. In this mode the root node becomes index-addressable.

A runtime error is generated if an argument is of the wrong type, or if a referenced object does not exist in the nexus.

itree/local P0, [ia1]
	Defines a local imploded tree array called ia1 and stores a pointer to the new object in register P0. The psTreeRoot attribute will not be set.
itree/bglobal NULL, [ADFS]
	Defines a global imploded tree array called ADFS and discards the pointer to the new object. The psTreeRoot attribute will be set to TRUE so all array indices provided to itree/addr or itree/set must include the root node.
xtree/def PUSH, ![.prose.code.default.array], [a]
	Adds an exploded tree array to the object called a underneath .prose.code.default.array, pushing a pointer to this object onto the program stack. The psTreeRoot attribute will not be set, so index addresses passed to xtree/addr or xtree/set start at nodes underneath .prose.code.default.array.
xtree/blocal P5, [my.ea], ![.prose.error]
	Defines a local exploded tree array called my.ea whose contents are located underneath .prose.error, allowing existing nodes in the nexus to be addressed using indices passed to xtree/addr or xtree/set. The psTreeRoot attribute will be set to TRUE so all array indices must start with the error node.

For more complete examples see ps_tree(5).

pal_commands(5), pal_registers(5), pal_indices(5), ps_attributes(5), ps_tree(5), tree_addr(5), tree_set(5), tree_conv(5), var_addr(5), var_def(5), mtx_def(5), attr_add(5), reg_dump(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2017 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.