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

tree_addr - Address an object inside a tree array

CONTENTS

Synopsis
Description
Error Handling
Examples
See Also
Author

itree/addr write, ![tree], path
itree/addr write, ![tree]

xtree/addr write, ![tree], path
xtree/addr write, ![tree]

Looks up an object of a given path within a pre-initialised tree array identified by the tree argument. Use the itree/addr instruction with imploded tree arrays, and xtree/addr with exploded tree arrays.

The path can be either a single read argument or register containing text, a raw index, an object reference, a PSUNIT_TYPE_STRING or PSUNIT_TYPE_XVALUE, it may be a list sequence in the format @[list_arguments], or it may be a register containing the type PSUNIT_TYPE_LIST. The path defines the name or path to the target node inside the tree array.

If the tree array object has the psTreeRoot attribute set to TRUE then the path is absolute beginning with the root node of the array, otherwise the path is relative to the root node. See tree_def(5).

Any single component within a path may contain subpaths itself by dot-separating each subpath. If a dot needs to be used in a path component then prefix it with a backslash character (\).

If the path is or contains an object reference, then the full path to that object is used in the newly derived path. This is particularly useful if you have many objects to address underneath a common branch, i.e. you can obtain a pointer to the common branch first and then keep re-using this reference in subsequent calls to itree/addr or xtree/addr.

The path may also be omitted, in which case a pointer to the root node of the tree array is returned.

A runtime error is generated if an argument is of the wrong type, or if a referenced object does not exist in the nexus or does not point to a tree array of the correct type, or if the given path does not exist in the tree array.

itree/addr P0, P1, @[[concert], [hall]]
	Looks up the path concert.hall in the imploded tree array pointed to in register P1, returning the result as a PSUNIT_TYPE_NODE in register P0.
xtree/addr PUSH, PULL, @[P4, P5, [volume]]
	Looks up the path consisting of the values in registers P4 and P5 and ending with the leaf name volume in the exploded tree array pointed to in the topmost item on the program stack which is subsequently replaced by the result.

For more complete examples see ps_tree(5).

pal_commands(5), pal_registers(5), pal_indices(5), ps_attributes(5), ps_tree(5), tree_def(5), tree_set(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2013 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.