Revert "No longer run setup.py in docs builds"
[mudpy.git] / doc / source / data_model.rst
1 ============
2  data model
3 ============
4
5 .. Copyright (c) 2004-2019 mudpy authors. Permission to use, copy,
6    modify, and distribute this software is granted under terms
7    provided in the LICENSE file distributed with this software.
8
9 One of the primary goals for mudpy is to apply a consistent data
10 model for all information, from configuration and preferences to
11 user accounts and world data. Individual pieces of information are
12 called *facets*, and are grouped together into entities called
13 *elements*. Elements are meant to be treated as loosely-typed
14 objects (if it walks like a duck and talks like a duck...), while
15 facets within them have predefined names and are strictly typed.
16 This combination provides the ability to have facet inheritance
17 among elements as a layered sieve.
18
19 The mudpy data model consists of a mix of persistent data (stored
20 externally but cached in memory), and ephemeral data
21 (cross-reference indexes which can be regenerated from it). For now,
22 persistent data is stored externally in a tree-like hierarchy of
23 text files starting from a main configuration usually named
24 mudpy.yaml and cached in memory as a single python dict known as the
25 *universe*. This default implementation, while memory-hungry, is
26 planned so as to reduce the number of dict lookup operations
27 performed to retrieve an individual piece of information, when
28 compared with a more deeply-nested dict model.
29
30 groups
31 ------
32
33 The universe is organized with a hierarchical namespace using the
34 period (``.``) symbol as a separator. It is rooted at ``.`` and
35 grows to the right with successive nodes. The right-most node must
36 always be a facet, and the remainder of the series thus denotes the
37 absolute name of an element within the universe (the second node
38 from the right being the relative element name and the remaining
39 nodes to the left are called the *group*). Near the root of the
40 universal namespace are a number of special elements anchored within
41 the ``.mudpy`` branch which provide necessary configuration
42 information and keeps some basic elements from cluttering the rest
43 of the tree.
44
45 .mudpy.actor
46 ~~~~~~~~~~~~
47
48 Where new actor elements with no specified storage destination are
49 kept by default.
50
51
52 .mudpy.archetype
53 ~~~~~~~~~~~~~~~~
54
55 Where the default archetype definitions are grouped together.
56
57 .mudpy.command
58 ~~~~~~~~~~~~~~
59
60 Where the default command definitions are grouped together.
61
62 .mudpy.data
63 ~~~~~~~~~~~
64
65 Defines default long-term storage locations for various element
66 groups.
67
68 .mudpy.facet
69 ~~~~~~~~~~~~
70
71 Defines default values and validation checks for every facet.
72
73 .mudpy.filing
74 ~~~~~~~~~~~~~
75
76 Defines filesystem-based backend storage meta data.
77
78 .mudpy.linguistic
79 ~~~~~~~~~~~~~~~~~
80
81 Language specific configuration.
82
83 .mudpy.limit
84 ~~~~~~~~~~~~
85
86 Various aspects determining mudpy performance.
87
88 .mudpy.log
89 ~~~~~~~~~~
90
91 Configuration for logging.
92
93 .mudpy.menu
94 ~~~~~~~~~~~
95
96 Where the default menu definitions are grouped together.
97
98 .mudpy.movement
99 ~~~~~~~~~~~~~~~
100
101 Defines movement directions.
102
103 .mudpy.network
104 ~~~~~~~~~~~~~~
105
106 Network socket configuration.
107
108 .mudpy.process
109 ~~~~~~~~~~~~~~
110
111 Process-specific configuration.
112
113 .mudpy.prop
114 ~~~~~~~~~~~
115
116 Where new prop elements with no specified storage destination are
117 kept by default.
118
119 .mudpy.room
120 ~~~~~~~~~~~
121
122 Where new room elements with no specified storage destination are
123 kept by default.
124
125 .mudpy.timing
126 ~~~~~~~~~~~~~
127
128 Timing-specific settings and scheduling for the main loop.
129
130 .mudpy.user
131 ~~~~~~~~~~~
132
133 User-focused settings such as access controls.
134
135 storage
136 -------
137
138 Long-term storage is accomplished with YAML format files, consisting
139 of an associative array of keys mapped to values of various data
140 types. The keys can be either absolute (beginning with a ``.``
141 character) or relative to the anchor specified by the parent file
142 which loaded it. Special records can also exist to describe a data
143 file's properties, and always begin with an underscore (``_``).
144 These are stored in the universe under the ``.mudpy.file`` group
145 with elements named for escaped versions of the file path (``.`` and
146 ``:`` replaced by ``\.`` and ``\:``) and the underscore stripped
147 from the beginning of each facet.
148
149 _copy
150 ~~~~~
151
152 Arbitrary string providing copyright notice and license information.
153
154 _desc
155 ~~~~~
156
157 Arbitrary string containing a description of the file or any other
158 useful information worth noting.
159
160 _load
161 ~~~~~
162
163 List of additional data sources to load and where to anchor their
164 elements in the universe. The value is prefaced by the storage
165 medium separated from the remainder by an optional parenthetical
166 parameter and a colon. The only type implemented so far is ``file``
167 and the optional parameter is ``p`` to indicate a private file which
168 should only be readable by the account under which the process is
169 running rather than created with the default umask (ignored on
170 unsupported platforms).
171
172 _lock
173 ~~~~~
174
175 Boolean value indicating read-only status. Any file not protected
176 with a _lock record will be regenerated and rewritten by mudpy if
177 its records are changed, so record format will be normalized,
178 records arbitrarily reordered and YAML comments lost in the process.