doc/source/data_model.rst

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