capability_skeleton_string/string_skeleton_node.rs
1// ---------------- [ File: capability-skeleton-string/src/string_skeleton_node.rs ]
2crate::ix!();
3
4/// Set this object to configure a single node in the string skeleton, tagged by its role.
5///
6/// Note that we do not want the names of our nodes to be trivial or vague categories like "foundations", or to use arbitrary separations like "beginner", "intermediate", "advanced".
7///
8/// It is always better for us to slice the chosen topic into *concrete subcomponents* that bear physical meaning. In the case of lockpicking, for example, we could write categories for types of locks, types of equipment, and techniques for entry.
9///
10/// Categorizing into these three would be better than categorizing into "beginner skills", "intermediate skills", and "advanced skills", for example. This same concept applies everywhere.
11///
12/// The essential idea is that the chosen names should refer to *concrete subcomponents* bearing *physical meaning*.
13///
14#[derive(AiJsonTemplateWithJustification,AiJsonTemplate,SaveLoad,Debug, Clone, PartialEq, Eq,Serialize, Deserialize)]
15//#[serde(tag = "role")]
16pub enum StringSkeletonNode {
17
18 /// Select this variant at this position in the model to emit a `Dispatch` node in which each dispatch branch wraps a whole rooted subtree.
19 /// Note that each Dispatch node should *always* have greater than one child.
20 Dispatch {
21
22 /// Set this field to indicate the *official-name* of this tree node.
23 ///
24 /// IMPORTANT: All names should be UpperCamelCase and contain *no spaces and no punctuation*.
25 ///
26 /// MORE IMPORTANTLY: DO NOT NAME THIS FIELD ANY TEMPORARY OR ANY GENERIC NAME!
27 ///
28 /// Do not use names like `SomethingDispatch`, `Dispatch1`, `DispatchNode1`, or anything like that!!! real names only!
29 ///
30 /// Do not reveal the underlying structure of our tree growing algorithm by your choice of name!
31 ///
32 /// WE DO NOT want to have to keep on asking you! name the tree nodes properly!!
33 ///
34 /// Each name should have concrete physical value and stand on its own, independently of our tree and retain technical and structural significance OUTSIDE THE CONTEXT OF THE TREE GROWING PROCESS!!!!!!!!
35 ///
36 name: String,
37
38 /// Set the `ordering` field to indicate an (optional) sub-branch ordering hint for our dispatch branch sequencing
39 #[serde(default)]
40 #[justify=false]
41 ordering: Option<SubBranchOrdering>,
42
43 /// Set the members of the `children` map to specify official names for each dispatch-branch-rooted child node and their associated auxiliary specifications.
44 ///
45 /// Keys in this map are the official names of the child nodes. Values are their associated DispatchChildSpec aux specifications.
46 ///
47 #[serde(default)]
48 children: HashMap<String, DispatchChildSpec>,
49 },
50
51 /// Select this variant to emit a `LeafHolder` node at this tree location.
52 ///
53 /// A LeafHolder node is like the shell of an enum with unit variants only.
54 ///
55 /// `LeafHolder` nodes are typically used as the "end-effectors" within the context of a domain model.
56 ///
57 /// `LeafHolder` nodes each have an associated number of "leaves" representing the number of ways this end effector can manifest in practice.
58 ///
59 LeafHolder {
60
61 /// Set this field to indicate the *official-name* of this tree node.
62 ///
63 /// IMPORTANT: All names should be UpperCamelCase identifiers and contain *no spaces and no punctuation*.
64 ///
65 /// MORE IMPORTANTLY: DO NOT NAME THIS FIELD ANY TEMPORARY OR ANY GENERIC NAME!
66 ///
67 /// Do not use names like `SomethingLeaf`, `Leaf1`, `Leaf1A`, `LeafBranch12`, `LeafHolder9B` or anything like that!!! real names only!
68 ///
69 /// Do not reveal the underlying structure of our tree growing algorithm by your choice of name!
70 ///
71 /// THIS INSTRUCTION IS NOT OPTIONAL! We DO NOT WANT to ask again!
72 ///
73 /// Correcting this problem after-the-fact is incredibly tedious! ***PLEASE*** PLEASE FOR THE LOVE OF GOD name the tree nodes properly!!
74 ///
75 /// Each name should have concrete physical value and stand on its own, independently of our tree and retain technical and structural significance OUTSIDE THE CONTEXT OF THE TREE GROWING PROCESS!!!!!!!!
76 name: String,
77
78 /// Set the `ordering` field to indicate an (optional) branch-ordering hint for the LeafHolder leaves
79 #[serde(default)]
80 #[justify=false]
81 ordering: Option<SubBranchOrdering>,
82
83 /// Set this number to the number of leaves to generate under this node.
84 ///
85 /// In practice, we typically want this number to be at least ten, but 5-7 is standard.
86 ///
87 #[justify=false]
88 #[serde(deserialize_with = "fuzzy_u8")]
89 n_leaves: u8,
90
91 /// Set this field to true to mark this LeafHolder node as a special *capstone* node within the tree.
92 ///
93 /// `capstone` nodes bear special significance within the model and will typically be targeted by downstream tree-consumers.
94 #[justify=false]
95 capstone: bool,
96 },
97
98 /// Select the `Aggregate` variant to emit a structure aggregating several downstream branches.
99 ///
100 /// An Aggregate node should have at least 3 children. 3-7 is typical. More than 7 is possible where useful.
101 ///
102 /// We use `Aggregate` nodes to model components having children that always activate together (ie *branches that are always taken simultaneously within the domain model path flow*)
103 ///
104 /// We model them as Aggregate nodes even if some of their branches may be temporarily deselected and are considered optional.
105 ///
106 /// `Aggregate` nodes are analogous to *struct data*.
107 ///
108 /// Note that each Aggregate node should *always* have greater than one child.
109 ///
110 /// We use `Aggregate` for nodes whose children temporally or structurally *overlap* during simulation and `Dispatch` for nodes whose children are more akin to mutually exclusive variations or alternatives.
111 Aggregate {
112
113 /// Set this field to indicate the *official-name* of this Aggregate node.
114 ///
115 /// IMPORTANT: All names should be UpperCamelCase and contain *no spaces and no punctuation*.
116 ///
117 /// MORE IMPORTANTLY: DO NOT NAME THIS FIELD ANY TEMPORARY OR ANY GENERIC NAME!
118 ///
119 /// Do not use names like `SomethingAggregator`, `Agg1`, `AggNode1A`, `MyAgg` or anything like that!!! real names only!
120 ///
121 /// Do not reveal the underlying structure of our tree growing algorithm by your choice of name!
122 ///
123 /// THIS INSTRUCTION IS NOT OPTIONAL! We DO NOT WANT to ask again! correcting this problem after-the-fact is incredibly tedious! ***PLEASE*** name the tree nodes properly!!
124 ///
125 /// Each name should have concrete physical value and stand on its own, independently of our tree and retain technical and structural significance OUTSIDE THE CONTEXT OF THE TREE GROWING PROCESS!!!!!!!!
126 name: String,
127
128 /// Set the `ordering` field to indicate an (optional) branch-ordering hint for the Aggregate node fields
129 ///
130 #[serde(default)]
131 #[justify=false]
132 ordering: Option<SubBranchOrdering>,
133
134 /// Set the members of the `children` map to specify official names for each aggregate-branch-rooted child node and their associated auxiliary specifications.
135 ///
136 /// Keys in this map are the official names of the direct child nodes. Values in this map are their associated AggregateChildSpec aux specifications.
137 ///
138 #[serde(default)]
139 children: HashMap<String, AggregateChildSpec>,
140 },
141}
142
143impl Default for StringSkeletonNode {
144
145 fn default() -> Self {
146 StringSkeletonNode::Dispatch { name: "default".to_string(), ordering: None, children: HashMap::default() }
147 }
148}