capability-skeleton-string 0.1.0

A robust library for managing skill tree skeletons using string-based nodes and bidirectional conversions between string and numeric formats.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

// ---------------- [ File: capability-skeleton-string/src/string_skeleton_node.rs ]
crate::ix!();

/// Set this object to configure a single node in the string skeleton, tagged by its role.
///
/// 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". 
///
/// 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. 
///
/// Categorizing into these three would be better than categorizing into "beginner skills", "intermediate skills", and "advanced skills", for example. This same concept applies everywhere. 
///
/// The essential idea is that the chosen names should refer to *concrete subcomponents* bearing *physical meaning*.
///
#[derive(AiJsonTemplateWithJustification,AiJsonTemplate,SaveLoad,Debug, Clone, PartialEq, Eq,Serialize, Deserialize)]
//#[serde(tag = "role")]
pub enum StringSkeletonNode {

    /// Select this variant at this position in the model to emit a `Dispatch` node in which each dispatch branch wraps a whole rooted subtree.
    /// Note that each Dispatch node should *always* have greater than one child.
    Dispatch {

        /// Set this field to indicate the *official-name* of this tree node. 
        ///
        /// IMPORTANT: All names should be UpperCamelCase and contain *no spaces and no punctuation*.
        ///
        /// MORE IMPORTANTLY: DO NOT NAME THIS FIELD ANY TEMPORARY OR ANY GENERIC NAME! 
        ///
        /// Do not use names like `SomethingDispatch`, `Dispatch1`, `DispatchNode1`, or anything like that!!! real names only! 
        ///
        /// Do not reveal the underlying structure of our tree growing algorithm by your choice of name!
        ///
        /// WE DO NOT want to have to keep on asking you! name the tree nodes properly!! 
        ///
        /// 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!!!!!!!!
        ///
        name: String,

        /// Set the `ordering` field to indicate an (optional) sub-branch ordering hint for our dispatch branch sequencing
        #[serde(default)]
        #[justify=false]
        ordering: Option<SubBranchOrdering>,

        /// Set the members of the `children` map to specify official names for each dispatch-branch-rooted child node and their associated auxiliary specifications. 
        ///
        /// Keys in this map are the official names of the child nodes. Values are their associated DispatchChildSpec aux specifications.
        ///
        #[serde(default)]
        children: HashMap<String, DispatchChildSpec>,
    },

    /// Select this variant to emit a `LeafHolder` node at this tree location. 
    ///
    /// A LeafHolder node is like the shell of an enum with unit variants only. 
    ///
    /// `LeafHolder` nodes are typically used as the "end-effectors" within the context of a domain model. 
    ///
    /// `LeafHolder` nodes each have an associated number of "leaves" representing the number of ways this end effector can manifest in practice.
    ///
    LeafHolder {

        /// Set this field to indicate the *official-name* of this tree node. 
        ///
        /// IMPORTANT: All names should be UpperCamelCase identifiers and contain *no spaces and no punctuation*.
        ///
        /// MORE IMPORTANTLY: DO NOT NAME THIS FIELD ANY TEMPORARY OR ANY GENERIC NAME! 
        ///
        /// Do not use names like `SomethingLeaf`, `Leaf1`, `Leaf1A`, `LeafBranch12`, `LeafHolder9B` or anything like that!!! real names only! 
        ///
        /// Do not reveal the underlying structure of our tree growing algorithm by your choice of name!
        ///
        /// THIS INSTRUCTION IS NOT OPTIONAL! We DO NOT WANT to ask again! 
        ///
        /// Correcting this problem after-the-fact is incredibly tedious! ***PLEASE*** PLEASE FOR THE LOVE OF GOD name the tree nodes properly!! 
        ///
        /// 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!!!!!!!!
        name: String,

        /// Set the `ordering` field to indicate an (optional) branch-ordering hint for the LeafHolder leaves
        #[serde(default)]
        #[justify=false]
        ordering: Option<SubBranchOrdering>,

        /// Set this number to the number of leaves to generate under this node. 
        ///
        /// In practice, we typically want this number to be at least ten, but 5-7 is standard.
        ///
        #[justify=false]
        #[serde(deserialize_with = "fuzzy_u8")]
        n_leaves: u8,

        /// Set this field to true to mark this LeafHolder node as a special *capstone* node within the tree.
        ///
        /// `capstone` nodes bear special significance within the model and will typically be targeted by downstream tree-consumers.
        #[justify=false]
        capstone: bool,
    },

    /// Select the `Aggregate` variant to emit a structure aggregating several downstream branches. 
    ///
    /// An Aggregate node should have at least 3 children. 3-7 is typical. More than 7 is possible where useful.
    ///
    /// 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*) 
    ///
    /// We model them as Aggregate nodes even if some of their branches may be temporarily deselected and are considered optional. 
    ///
    /// `Aggregate` nodes are analogous to *struct data*.
    ///
    /// Note that each Aggregate node should *always* have greater than one child.
    ///
    /// 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.
    Aggregate {

        /// Set this field to indicate the *official-name* of this Aggregate node. 
        ///
        /// IMPORTANT: All names should be UpperCamelCase and contain *no spaces and no punctuation*.
        ///
        /// MORE IMPORTANTLY: DO NOT NAME THIS FIELD ANY TEMPORARY OR ANY GENERIC NAME! 
        ///
        /// Do not use names like `SomethingAggregator`, `Agg1`, `AggNode1A`, `MyAgg` or anything like that!!! real names only! 
        ///
        /// Do not reveal the underlying structure of our tree growing algorithm by your choice of name!
        ///
        /// 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!! 
        ///
        /// 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!!!!!!!!
        name: String,

        /// Set the `ordering` field to indicate an (optional) branch-ordering hint for the Aggregate node fields
        ///
        #[serde(default)]
        #[justify=false]
        ordering: Option<SubBranchOrdering>,

        /// Set the members of the `children` map to specify official names for each aggregate-branch-rooted child node and their associated auxiliary specifications. 
        ///
        /// Keys in this map are the official names of the direct child nodes. Values in this map are their associated AggregateChildSpec aux specifications.
        ///
        #[serde(default)]
        children: HashMap<String, AggregateChildSpec>,
    },
}

impl Default for StringSkeletonNode {

    fn default() -> Self {
        StringSkeletonNode::Dispatch { name: "default".to_string(), ordering: None, children: HashMap::default() }
    }
}