| Command References | [Topic] |
Most of Stella's commands operate on a set of objects specified as the first argument to a command:
Stella [Top-Level]: mix foo,bar 0,1 Stella [Top-Level]: run 1:5,7 0 Stella [Top-Level]: list foo,4:8,bar[6],baz[34:*]Use commas to specify an argument containing more than one reference:
Stella [Top-Level]: list foo,1:5
Referencing by Name or Position
Containers can be referenced by name and all types of objects can be referenced by their position (1 based) in a container. If no container is specified the current focus container is assumed.
The Focus Container
The focus container provides the starting point for resolving positional references. To reference objects inside the focus container 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, previous, or up are used, the system updates the current focus container to the new location.
Sub-object Notation
Sub-objects (objects that are held in a container) are referenced using an array like syntax:
container[reference]where container is the name or position of the container and referece is the position (one based), range, iteration or grouping of sub-objects, as defined below. For example Foo[1] is a reference to the first object in a container named Foo, and 2[1:10,54] is a reference to the first ten objects and the fifty-fourth object in the second object in the current focus container. The full-blown notation of a reference is four fields in length with fields delimited by colons:
low:high:step:widthwhere low is the lower bound of the reference, high is an inclusive upper bound, step is a stepping increment between low and high and width is the number of "clustered" objects to reference in parallel. It is only necessary to specify enough of the fields to adequately describe the reference and the entire reference may delimited by comma if there are more than one of them.
Wildcard and Shorthand Notations
Since positional referencing can get complex, the editor supports a few notation shortcuts. Several wildcard characters can be used to designate part or all of the first two fields in a subobject reference. The 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. end-4 would mean the element four positions before the end.
Field specification 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 object, and :56::4 is slightly better than 1:56:1:4 and defines a four element cluster over every position between the first and the fifty-sixth object.