Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors
pal_indices - Introduction to PAL indices
An index is used to address a specific data item within PAL. Indices are normally supplied in the PAL source file as a read argument to an assembly instruction. They are converted into numeric index values at compile time.
An index may be transferred directly in a register by means of the reg/load instruction. See reg_load(5).
There are several types of index:
Indices may be substituted for registers at any time, provided that the register contains the same data type. This is discussed in pal_registers(5).
PAL_IDESCTYPE_LABEL A code label index is used to obtain a pointer to a section of code in the local source file. This is generally used as a means of branching to subroutines within the local file, or transferring program execution to a new section (jumping). A code label index is created using the syntax &[.code_label], where code_label is the name of the code label to which you are referring.
PAL_IDESCTYPE_DLABEL A data label index is used to obtain a pointer to a data segment in the local source file. It is created using the syntax &[~data_label], where data_label is the name of the data segment label to which you are referring. PAL_IDESCTYPE_OBJREF An object reference is used to obtain a pointer to a node in the nexus. It is created using the syntax ![object_address] where object_address is the address of a node in the nexus in dot-notation. An absolute object address begins with a single dot, and is anchored to the top of the tree. A relative address does not begin with a single dot, and is anchored to the node in the current context (PCTX).
Addresses beginning with a minus symbol (-) will be made relative to the module root. Addresses beginning with a plus symbol (+) will be made relative to the instance container.
If the node does not exist, a runtime error will be generated. The exception to this rule is if the address consists of a plus symbol (+) and nothing else, in which case the instance container will be created if it doesn’t yet exist.
Note that every time an object reference is encountered, the node is looked up within the nexus and a new pointer is obtained at that time. For this reason it is more efficient to load the pointer into a register (or the stack) if the same object is to be referenced in multiple loop iterations, as long as you are sure that no other process will be deleting or re-creating that node independently.
If a node name contains a dot, prefix the dot with the backslash character \ to prevent it from being interpreted as a node delimiter.
PAL_IDESCTYPE_TEXT A text reference is used to pass in arbitrary text from the source file. It is created using the syntax [text], where text is a string of ASCII characters. The backslash character \ is used to protect the next character from special interpretation. Therefore, use \] for a close square bracket in the text string, and \\ for a backslash. PAL_IDESCTYPE_RAW A raw index is a user defined index value. It is created using the syntax #index, where index is a 32-bit unsigned integer. If index begins 0b, the value is interpreted as binary (base 2). If index begins 0x, the value is interpreted as hexadecimal (base 16). If index begins 0, the value is interpreted as octal (base 8). Otherwise, the value is interpreted as decimal (base 10). PAL_IFLAG_PTRPOS An internal representation of a code label index, used if the code address can be given as a positive reference from the program pointer position, rather than using an absolute address. This is calculated automatically when a code label index is used. PAL_IFLAG_PTRNEG An internal representation of a code label index, used if the code address can be given as a negative reference from the program pointer position, rather than using an absolute address. This is calculated automatically when a code label index is used.
A list sequence is a list of one or more arguments to include inside a single list structure. List sequences are normally supplied in the PAL source file using the syntax @[list_arguments], where list_arguments is a list of one or more comma-separated arguments to include within the list. Any argument valid for a PAL instruction is valid in a list sequence, except that a list sequence may not contain another list sequence. A list sequence can be provided as a read or write argument to an assembly instruction. Those instructions that accept a list as a write argument will expect all members of the list to be named registers.
Lists are used by a limited number of instructions that require an arbitrary number of arguments. Lists may be stored in a register using the type PSUNIT_TYPE_LIST by means of the list/def instruction. See list_def(5).
The following additional codes are valid within a list sequence:
PAL_LXFLAG_STATE A state change byte used to indicate the start or end of a list sequence. PAL_LISTIDX_POS Positive integer used in a list sequence, created using the syntax #index as an argument within enclosing @[ ... ] sequence brackets, where index is a 32-bit unsigned integer. PAL_LISTIDX_NEG Negative integer used in a list sequence, created using the syntax #-index as an argument within enclosing @[ ... ] sequence brackets, where index is a 32-bit unsigned integer. PAL_LISTIDX_MPOS Positive GMP integer used in a list sequence, created using the syntax integer as an argument within enclosing @[ ... ] sequence brackets, where integer is a multiple precision GMP integer. PAL_LISTIDX_MNEG Negative GMP integer used in a list sequence, created using the syntax -integer as an argument within enclosing @[ ... ] sequence brackets, where integer is a multiple precision GMP integer.
pal_intro(5), pal_commands(5), pal_registers(5), reg_load(5), list_def(5),
PROSE Assembly Language at prose.sourceforge.net.
Copyright (c) 2002-2011 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 | pal_indices (5) | 11 August 2011 |