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).

diff --git a/doc/source/data_model.rst b/doc/source/data_model.rst
new file mode 100644 (file)
index 0000000..13b44ae
--- /dev/null
+++ b/doc/source/data_model.rst
@@ -0,0 +1,174 @@
+============
+ data model
+============
+
+.. Copyright (c) 2004-2018 Jeremy Stanley <fungi@yuggoth.org>.
+   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.