From 23c7262d6f302e91941bc9f502ed0d60bfdf4331 Mon Sep 17 00:00:00 2001 From: Jeremy Stanley Date: Mon, 30 Apr 2018 17:48:50 +0000 Subject: [PATCH] Document the data model Add some prose documenting the terminology for the mudpy data model. Include brief descriptions of element groups within the .mudpy top-level namespace, as well as _prefixed local variables in the individual storage units (currently YAML format files). --- doc/source/data_model.rst | 174 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 doc/source/data_model.rst diff --git a/doc/source/data_model.rst b/doc/source/data_model.rst new file mode 100644 index 0000000..13b44ae --- /dev/null +++ b/doc/source/data_model.rst @@ -0,0 +1,174 @@ +============ + data model +============ + +.. Copyright (c) 2004-2018 Jeremy Stanley . + Permission to use, copy, modify, and distribute this software is + granted under terms provided in the LICENSE file distributed with + this software. + +One of the primary goals for mudpy is to apply a consistent data +model for all information, from configuration and preferences to +user accounts and world data. Individual pieces of information are +called *facets*, and are grouped together into entities called +*elements*. Elements are meant to be treated as loosely-typed +objects (if it walks like a duck and talks like a duck...), while +facets within them have predefined names and are strictly typed. +This combination provides the ability to have facet inheritance +among elements as a layered sieve. + +The mudpy data model consists of a mix of persistent data (stored +externally but cached in memory), and ephemeral data +(cross-reference indexes which can be regenerated from it). For now, +persistent data is stored externally in a tree-like hierarchy of +text files starting from a main configuration usually named +mudpy.yaml and cached in memory as a single python dict known as the +*universe*. This default implementation, while memory-hungry, is +planned so as to reduce the number of dict lookup operations +performed to retrieve an individual piece of information, when +compared with a more deeply-nested dict model. + +groups +------ + +The universe is organized with a hierarchical namespace using the +period (``.``) symbol as a separator. It is rooted at ``.`` and +grows to the right with successive nodes. The right-most node must +always be a facet, and the remainder of the series thus denotes the +absolute name of an element within the universe (the second node +from the right being the relative element name and the remaining +nodes to the left are called the *group*). Near the root of the +universal namespace are a number of special elements anchored within +the ``.mudpy`` branch which provide necessary configuration +information and keeps some basic elements from cluttering the rest +of the tree. + +.mudpy.actor +~~~~~~~~~~~~ + +Where new actor elements with no specified storage destination are +kept by default. + + +.mudpy.archetype +~~~~~~~~~~~~~~~~ + +Where the default archetype definitions are grouped together. + +.mudpy.command +~~~~~~~~~~~~~~ + +Where the default command definitions are grouped together. + +.mudpy.data +~~~~~~~~~~~ + +Defines default long-term storage locations for various element +groups. + +.mudpy.facet +~~~~~~~~~~~~ + +Defines default values and validation checks for every facet. + +.mudpy.filing +~~~~~~~~~~~~~ + +Defines filesystem-based backend storage meta data. + +.mudpy.linguistic +~~~~~~~~~~~~~~~~~ + +Language specific configuration. + +.mudpy.limit +~~~~~~~~~~~~ + +Various aspects determining mudpy performance. + +.mudpy.log +~~~~~~~~~~ + +Configuration for logging. + +.mudpy.menu +~~~~~~~~~~~ + +Where the default menu definitions are grouped together. + +.mudpy.movement +~~~~~~~~~~~~~~~ + +Defines movement directions. + +.mudpy.network +~~~~~~~~~~~~~~ + +Network socket configuration. + +.mudpy.process +~~~~~~~~~~~~~~ + +Process-specific configuration. + +.mudpy.prop +~~~~~~~~~~~ + +Where new prop elements with no specified storage destination are +kept by default. + +.mudpy.room +~~~~~~~~~~~ + +Where new room elements with no specified storage destination are +kept by default. + +.mudpy.timing +~~~~~~~~~~~~~ + +Timing-specific settings and scheduling for the main loop. + +storage +------- + +Long-term storage is accomplished with YAML format files, consisting +of an associative array of keys mapped to values of various data +types. The keys can be either absolute (beginning with a ``.`` +character) or relative to the anchor specified by the parent file +which loaded it. Special records can also exist to describe a data +file's properties, and always begin with an underscore (``_``). +These are stored in the universe under the ``.mudpy.file`` group +with elements named for escaped versions of the file path (``.`` and +``:`` replaced by ``\.`` and ``\:``) and the underscore stripped +from the beginning of each facet. + +_copy +~~~~~ + +Arbitrary string providing copyright notice and license information. + +_desc +~~~~~ + +Arbitrary string containing a description of the file or any other +useful information worth noting. + +_load +~~~~~ + +List of additional data sources to load and where to anchor their +elements in the universe. The value is prefaced by the storage +medium separated from the remainder by an optional parenthetical +parameter and a colon. The only type implemented so far is ``file`` +and the optional parameter is ``p`` to indicate a private file which +should only be readable by the account under which the process is +running rather than created with the default umask (ignored on +unsupported platforms). + +_lock +~~~~~ + +Boolean value indicating read-only status. Any file not protected +with a _lock record will be regenerated and rewritten by mudpy if +its records are changed, so record format will be normalized, +records arbitrarily reordered and YAML comments lost in the process. -- 2.11.0