doc/source/data_model.rst

   1 ============
   2  data model
   3 ============
   4
   5 .. Copyright (c) 2004-2018 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 storage
 131 -------
 132
 133 Long-term storage is accomplished with YAML format files, consisting
 134 of an associative array of keys mapped to values of various data
 135 types. The keys can be either absolute (beginning with a ``.``
 136 character) or relative to the anchor specified by the parent file
 137 which loaded it. Special records can also exist to describe a data
 138 file's properties, and always begin with an underscore (``_``).
 139 These are stored in the universe under the ``.mudpy.file`` group
 140 with elements named for escaped versions of the file path (``.`` and
 141 ``:`` replaced by ``\.`` and ``\:``) and the underscore stripped
 142 from the beginning of each facet.
 143
 144 _copy
 145 ~~~~~
 146
 147 Arbitrary string providing copyright notice and license information.
 148
 149 _desc
 150 ~~~~~
 151
 152 Arbitrary string containing a description of the file or any other
 153 useful information worth noting.
 154
 155 _load
 156 ~~~~~
 157
 158 List of additional data sources to load and where to anchor their
 159 elements in the universe. The value is prefaced by the storage
 160 medium separated from the remainder by an optional parenthetical
 161 parameter and a colon. The only type implemented so far is ``file``
 162 and the optional parameter is ``p`` to indicate a private file which
 163 should only be readable by the account under which the process is
 164 running rather than created with the default umask (ignored on
 165 unsupported platforms).
 166
 167 _lock
 168 ~~~~~
 169
 170 Boolean value indicating read-only status. Any file not protected
 171 with a _lock record will be regenerated and rewritten by mudpy if
 172 its records are changed, so record format will be normalized,
 173 records arbitrarily reordered and YAML comments lost in the process.