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


Manual Reference Pages  - tree_set (5)

NAME

tree_set - Set variable object inside a tree array

CONTENTS

Synopsis
Description
Error Handling
Examples
See Also
Author

SYNOPSIS

itree/set ![tree], attribute, path, value
xtree/set ![tree], attribute, path, value

DESCRIPTION

Assigns a variable object in a given path within a pre-initialised tree array identified by the tree argument. Use the itree/set instruction with imploded tree arrays, and xtree/set with exploded tree arrays.

The variable is set in the same way as if var/def had been used to create it. See var_def(5).

The variable type is defined in the attribute argument and must be a variable type as defined in ps_attributes(5). It is either a text argument containing the name of the object attribute to add, or a PSUNIT_TYPE_ATTRDEF register returned by the attr/load instruction.

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 that will be created if missing, and whereupon the variable object will be created.

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.

The value is an argument containing the data to add to the attribute. If value is a register containing the type PSUNIT_TYPE_STRING or PSUNIT_TYPE_XVALUE and the instruction does not generate an error, then the register will be cleared as the data is now referenced elsewhere.

If value is encoded data (PSUNIT_TYPE_XVALUE) and the data encoding is not of an appropriate syntax to be stored directly in the selected attribute, then it will be re-encoded as a byte string before processing.

ERROR HANDLING

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.

EXAMPLES

itree/set P0, [psString], @[[concert], [hall]], [Albert Hall]
  Creates a psString variable in the element identified by the path concert.hall to the value Albert Hall in the imploded tree array pointed to in register P0.
xtree/set PULL, [psFloat], @[P4, P5, [volume]], [122.5]
  Creates a psFloat variable in the element identified by a path consisting of the values in registers P4 and P5 and ending with the leaf name volume to the value 122.5 in the exploded tree array pointed to in the topmost item on the program stack which is subsequently removed from the stack.
For more complete examples see ps_tree(5).

SEE ALSO

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

AUTHOR

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.


PAL 1.0 tree_set (5) 8 March 2013
Generated by manServer 1.07 from man5/tree_set.5 using man macros.