collect_spec

syntax

collect_spec(spec, tree_item, selection domain unit, org_rel or condition)

definition

collect_spec(spec, …) collects the subitems of tree_item onto the selection domain unit, configured by the spec Argument instead of by the function name. It is the collect_attr_by_org_rel / collect_attr_by_cond pair with its choices made explicit, plus the collection scopes that have no named form.

The spec is a string of ;-separated words; order does not matter.

word	meaning
`by_org_rel`	the 4th argument is an org_rel relation, used in a Lookup
`by_cond`	the 4th argument is a condition, used in a collect_by_cond
`ref`	also collect through the referred-item chain
`sub`	also collect from sub-containers, mirroring them in the result

One of by_org_rel / by_cond is required: the last argument is read as one or the other, and guessing would silently produce a different result. An unknown word is reported where the item is defined.

equivalences

named function	collect_spec
collect_attr_by_org_rel	`collect_spec('by_org_rel', C, dom, org_rel)`
collect_attr_by_cond	`collect_spec('by_cond', C, dom, cond)`

Prefer the named function when one exists; reach for collect_spec when you need ref or sub.

example

unit<uint32> Stops := Network/Stops;          // a reference: no sub-items of its own

container attrs := collect_spec('by_org_rel;ref', Stops, Selection, Selection/org_rel);

Without ref, Stops has nothing to collect and the call only warns. ref reaches the attributes of Network/Stops through the reference — the same chain that makes Stops/name resolve.

With by_cond the last argument is a condition on the source domain instead, exactly as collect_attr_by_cond takes it:

container attrs := collect_spec('by_cond', City, ZHCities, City/RegionCode == 200);

sub

sub mirrors a sub-container into the collected result. For a City that keeps its coordinates in a sub-container:

unit<uint32> City
{
   attribute<string> name;
   container geo { attribute<point_rd> point (City); }
}

container attrs := collect_spec('by_org_rel;sub', City, ZHCities, ZHCities/org_rel);

gives attrs/name and attrs/geo/point. Note that an attribute in a sub-container needs its Domain unit spelled out — it is not a direct sub-item of the unit, so there is nothing to infer it from.

ref and sub mean exactly what they mean for select_spec; see that page for the shadowing rule and for the scopes in full.

applies to

spec a Parameter of Value type string; usually a literal
tree_item can be any Tree item, but usually a Unit or Container
selection domain unit a Unit with a Value type of the group CanbeDomainUnit
org_rel a relation from the selection domain unit toward the domain of the collected attributes; condition a boolean attribute on that domain

since version

20.17.0