Returns a create-spec specifying the creation of the root
of a result grove.
sg is a subgrove-spec for the root of the result grove.
obj is an identifier for the result grove.
(create-sub snl sg #!key property: label: result-path: optional:
unique:)
(create-preced snl sg #!key label: result-path: optional: unique:)
(create-follow snl sg #!key label: result-path: optional: unique:)
create-sub, create-preced, and create-follow return
a create-spec specifying that for each arrow labeled
label: with a start-point of snl the subgrove specified by
sg shall be created in the result grove.
The evaluation of
the create-sub, create-preced, or create-follow
procedures does not of itself cause the creation of nodes in the
result grove; a create-spec that is not returned by a
transform-expression shall be ignored.
label: can be any expression language object; it defaults to
#f.
If optional: is #f, then it shall be an error if there never
is any such arrow; optional: defaults to #f.
result-path: is a procedure that for each arrow is applied to a
result-node-list whose only member is the end-point of the arrow.
result-path: may be applied to this result-node-list at various
points in the construction of the grove. At some point in the
construction of the grove, it shall return a result-node-list that
contains exactly one member. This is the creation origin. At
no point shall it return a result-node-list that contains more than
one member. If result-path: is not specified, it defaults to
the identity procedure.
For create-sub, property: is a symbol or string specifying a
property name. This property shall be a subnode property of the
creation origin, and the subgrove shall be created as a member of that
property of the creation origin.
If the property: argument is omitted, it defaults to the children
property
of the creation origin; it shall not be omitted if the creation origin
has no children property.
For create-preced, the
subgrove shall be created as a preceding sibling of the creation
origin. For create-follow, the subgrove shall be created as a
following sibling of the creation origin.
Two subgroves are said to have the same creation method if and
only if the roots of the subgroves were created with the same creation
origin and same creation procedure and, if the creation procedure was
create-sub, the same propname.
If unique: is not #f, then this subgrove shall be the only
one that is ever created with the same creation method
as this one. unique: defaults to #f.
When unique: is #f, the relative order of subgroves
created with the same creation method is
determined in a way that is independent of the order in which the
subgroves are created. Let the immediately dependent siblings of
a node be those siblings of the node that were created with a creation
origin of that node using the create-follow or create-preced
procedures. Let the dependent siblings of a node be the
immediately dependent siblings of the node together with the dependent
siblings of the immediately dependent siblings. Let the creation
siblings of a subgrove to be inserted be those nodes that were created
with the same creation procedure and with the same creation origin. In
addition, if a subgrove is to be inserted using create-sub, then any
nodes that will be siblings of the inserted subgrove and
were created as part of the same subgrove as the origin
node shall be treated as creation siblings. The position of a subgrove
to be inserted is first determined relative to its creation siblings. It
is then inserted in such a way that it follows all the dependent
siblings of all those creation siblings that it is to follow and
precedes all the dependent siblings of all those creation siblings
that it is to precede so that there is no node between it and its
creation origin that is neither a creation sibling nor a dependent
sibling of a creation sibling.
When the node at the root of the subgrove is a child of the node
that will be the origin of the subgrove,
the position of the subgrove
among its creation siblings is determined by the ordering predicate of
the origin node. The ordering predicate is the procedure specified by
the sort-children: argument to the subgrove-spec
procedure. The ordering predicate is passed the
transformation origins of two nodes in the result grove that are to be
compared. It shall return true if the first is before the second. If
no ordering predicate was specified, then the tree-before? procedure
shall be used as an ordering predicate. In this case, it shall be an
error if
the transformation origins of the subgrove and its creation siblings are
not all in the same tree.
When the node at the root of the subgrove is not a child of the
origin node, then the position of the subgrove among its creation
siblings is determined in the same way as for the children
of a node with an ordering predicate of grove-before?.
An arrow triggers another arrow if the second arrow was created
by a call to a create procedure that specified the start-point of the
first arrow as the first argument and specified the label of the first
arrow as the label: argument. It shall be an error if there is a
sequence of arrows where each arrow triggers the next arrow and where
the last arrow has the same start-point and label as the first arrow.
| This requirement avoids the possibility of an infinite loop. |
|