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.