Referencing Objects in Commands

Most of Stella's commands operate on one or more objects. The
specification of these objects is called an object reference.
Object references normally occupy the first command argument:

	LIST {objects}
	SET {objects} {slot expr}+
	ADD {objects} {position}
	RETROGRADE {ranges}

An argument described as {object}, {objects}, {position},
{positions}, {ranges}, etc in command help texts expects
some form of object reference, generally a name, index or
range. If an argument is plural, such as {objects} or
{positions} then that argument is capable of accepting more
than one reference, provided commas are placed between each
of the individual references:

	list foo,bar
	list foo,4:8,bar[6],baz[34:*]

It does not matter if there are spaces before or after a comma,
it is the comma itself that is important.  So:

	list foo,bar, baz , buz

are all correct, but:

	list foo bar

is an error because LIST only accepts one argument
and two have been specified.

Absolute and Relative References

Objects can be referenced in one of two ways, by name or
by position in a container. A reference by name is "absolute"
because there can only be one object with a given name. A
reference by position is "relative" because the position must
be "resolved" relative to some particular container.  
Positional references are notated using an array like syntax:

	container[index]

where "index" is a numeric index and "container" is either an
absolute name or an index:

	Foo[2]		the second object in Foo
	1[256]		the 256th object in the first object

The Focus Container

Stella uses a "current focus container" as the absolute
starting point for resolving relative references.  When
referencing objects inside the focus container itself, only
the index portion of the reference needs to to be specified.
When Stella starts up, the focus container is automatically
set to a system container called Top-Level, which holds all the 
containers currently loaded.  Whenever positioning commands like
GO, NEXT, UP, or PREVIOUS are used, the system  updates
the current focus container to the new location so subsequent
positional references will be
resolved with respect to the new focus container. 


Subobject Notation

The typical case for referencing multiple objects occurs when
referencing subobjects of a container.  An array-like syntax 
is used in which the container reference (absolute or relative) 
is qualified with a subobject specification denoted inside []  
following the container.  For example partA[1]is a reference to 
the first object in a container named partA, and 2[1:10,54] is 
a reference to the first ten objects and the fifty-fourth object 
in the second object of the current focus container.  The 
full-blown notation of a subobject reference is four fields in 
length with fields delimited by colons: low:high:step:width, 
where low is the low bound of the subobject reference, high is 
the inclusive upper bound, step is the stepping increment 
between objects in the reference and width is the number of 
objects to reference in parallel.  The entire reference itself 
is delimited by space or comma if there are more than one of 
them.  It is only necessary to specify enough of the fields to 
adequately describe the reference.  The editor currently 
distinguishes between five basic types of subobject reference: 
index, a single object.; range, all the objects between a low 
and high bound; iteration, all the objects spaced a step>1 apart 
between a low and high bound (a range is really an iteration 
with a stepping increment of 1); grouping, all the width>1 
clusters of objects spaced some step increment apart between 
a low and high bound (an iteration is really a grouping with a 
width of 1); sequence, combinations of all the above delimited 
by comma or space.

Wildcard and shorthand notations

Since subobject referencing inside a [] can get quite complex, 
the editor supports a few notation shortcuts.  There are several 
wildcard characters that can be used to designate part or all of 
the first two fields in a subobject reference.  The wildcard 
token * has two meanings.  If * is used by itself, it stands for 
all the subobjects, no matter how many there are.  If * appears 
as the upper bound it stands for the last element, no matter what 
its position is.  Alternately,  the token end may be used to 
refer to the last element in a container.  End also supports 
"subtraction" ie. the token end-4 would mean the element four 
positions before the end position.  Field specification in a 
reference can be abbreviated if the default value for a field 
applies.  In this case only the delimiter for that field need 
appear in the notation.  The default values for the four fields 
are 1:*:1:1.  For example, ::2 would stand for 1:*:2 and defines 
an iteration over every other subobject, and the notation :56::4 
is slightly better than 1:56:1:4 and defines a four element group 
ranging over every position between the first and the fifty-sixth 
subobject.