- Index
- »
- docHaystack
- »
- Protos
Protos
Overview
Prototypes, or simply protos, are dict templates. A proto is just a normal dict of name/value pairs along with a special tag expansion mechanism.
Protos are primarily used to declare typical sub-parts of an entity via the children
tag. For example, we use protos to answer questions such as "what points might be contained by a chiller?" Protos are generated into Project Haystack documentation. They are also used to power menu options in vendor tools.
Format
The children
tag for an entity is a list of prototype dicts:
def: ^pipe children: [ {valve actuator equip}, {flow sensor point}, {temp sensor point}, ]
You can see these children protos in the docs for pipe
.
Flattening
Entities with children protos can specify that specific tags are flattened into their children. For example, Haystack convention dictates that points within a specific pipe include tags to indicate the pipe section and the fluid being sensed:
// parent pipe steam leaving pipe equip // child points steam leaving valve actuator equip steam leaving temp sensor point steam leaving flow sensor point
This convention makes it easy to query points using tag combinations without regard to if or how parent pipes are modeled.
We use the childrenFlatten
tag to indicate that these tags should be flattened into their children. In our pipe example:
def: ^pipe conveys: ^fluid childrenFlatten: [^fluid, ^pipeSection] children: [ {valve actuator equip}, {flow point}, {temp point}, ]
Flattening occurs when we are given an instance of a parent pipe and want to generate the children protos. We walk each symbol in the childrenFlattens list and, if the parent implements the def, then it is flattened into each child proto. Lets look at some concrete examples:
First, lets look at a parent pipe that implements neither a fluid
term nor a pipeSection
term:
// parent pipe pipe equip // children protos, no tags to flatten valve actuator equip flow point temp point
In the following example, the parent pipe implements the fluid
subtype of hot-water
// parent pipe hot water pipe equip // children protos include hot-water conjunct hot water valve actuator equip hot water flow point hot water temp point
In the following example, the parent pipe implements both fluid
via the subtype naturalGas
and also pipeSection
via the subtype entering
:
// parent pipe leaving naturalGas pipe equip // children protos include both leaving and naturalGas leaving naturalGas valve actuator equip leaving naturalGas flow point leaving naturalGas temp point
This technique becomes a powerful tool to auto-expand tag combinations when used with equipment containing known children:
def: ^chiller children: [ {chilled water leaving pipe equip}, {chilled water entering pipe equip}, {condenser water leaving pipe equip}, {condenser water entering pipe equip}, ]
In the chiller
example above, it is not necessary to enumerate every possible combination of chiller point. Rather, we declare that chillers have four specific pipes. Using indirection, we can then derive the various points by flattening the generic pipe
definition.