New text about instances and type aliases.

docs/instances.rst

@@ -37,8 +37,18 @@ The following classes and their method implement all this functionality.
 
 __ https://en.wikipedia.org/wiki/Persistent_data_structure
 
+This module defines a type alias representing an union of possible
+types of instance values.
+
++-----+--------------------------------------------------------------+
+|Alias|Type                                                          |
++=====+==============================================================+
+|Value| Union[ScalarValue, :class:`ArrayValue`, :class:`ObjectValue`]|
++-----+--------------------------------------------------------------+
+
+
 Instance Values
-===============
+***************
 
 .. class:: StructuredValue(ts:datetime.datetime=None)
 
@@ -92,34 +102,111 @@ Instance Values
       and applying the :func:`hash` function.
 
 Persistent Instances
-====================
+********************
 
 .. class:: Instance(value: Value, crumb: Crumb)
 
+   This class implements a *zipper* interface for JSON-like values
+   pretty much along the lines of Gérard Huet's original
+   paper [Hue97]_. Every :class:`Instance` contains
+
+   * a *value*, as defined by the ``Value`` type alias;
+
+   * a *crumb* that describes the neighborhood of the *value*.
+
+   Inside a larger data structure, an :class:Instance represents
+   “focus” on a particular element of the structure, where the *value*
+   contains the element and its subtree, and *crumb* contains the rest
+   of the structure: all ancestors and siblings of the focused
+   element.
+
+   The focus can be moved and values added, deleted and updated around
+   the current focus by using the methods described below. Each of the
+   methods returns a new :class:`Instance` that shares as much as
+   possible of the entire data tree with other instances, but any
+   modifications of an :class:`Instance` – if performed via the
+   methods of this class – don't affect any other instances.
+
+   Due to the heterogeneity of JSON-like values, the zipper interface is not
+   as elegant as for trees: some operations are intended to work only
+   with certain :class:`Instance` types. In the following subsections,
+   the methods are classified according to the context for which they
+   are designed.
+
+   Section :ref:`sec-example` illustrates the zipper interface with
+   several examples.
+
+Methods for All Types of Instances
+----------------------------------
+
    .. method:: goto(ii: InstanceIdentifier) -> Instance
 
+      Return the instance inside the receiver's subtree identified by
+      the instance identifier *ii* (see TODO). The path specified in
+      *ii* is interpreted relative to the receiver.
+
    .. method:: peek(ii: InstanceIdentifier) -> Value
 
+      Return the value inside the receiver's value subtree identified by
+      the instance identifier *ii* (see TODO). This
+      method doesn't create a new instance, so the access to the
+      returned value should in general be read-only, because
+      modifications would destroy persistence properties.
+
    .. method:: update(newval: Value) -> Instance
 
+      Return a new instance that is identical to the receiver, only
+      its value is replaced with *newval*. The receiver's value
+      remains the same.
+
    .. method:: up() -> Instance
 
    .. method:: top() -> Instance
 
-   .. method:: is_top() -> Instance
+   .. method:: is_top() -> bool
+
+Methods for :class:`ObjectValue` Instances
+------------------------------------------
 
    .. method:: member(name: QName) -> Instance
 
    .. method:: new_member(name: QName, value: Value) -> Instance
 
-   .. method:: () -> Instance
+   .. method:: remove_member(name: QName) -> Instance
+
+Methods for Object Member Instances
+-----------------------------------
+
+   .. method:: sibling(name: QName) -> Instance
+
+Methods for :class:`ArrayValue` Instances
+------------------------------------------
+
+   .. method:: entry(index: int) -> Instance
+
+   .. method:: remove_entry(index: int) -> Instance
+
+   .. method:: first_entry() -> Instance
+
+   .. method:: last_entry() -> Instance
+
+   .. method:: look_up(keys: Dict[QName, ScalarValue]) -> Instance
+
+Methods for Array Entry Instances
+-----------------------------------
+
+   .. method:: next() -> Instance
+
+   .. method:: previous() -> Instance
+
+   .. method:: insert_before(value: Value) -> Instance
 
-   .. method:: () -> Instance
+   .. method:: insert_after(value: Value) -> Instance
 
-   .. method:: () -> Instance
 
-   .. method:: () -> Instance
+.. _sec-example:
 
-   .. method:: () -> Instance
+Example
+*******
 
-   .. method:: () -> Instance
+TODO.

docs/references.rst

@@ -2,6 +2,17 @@
 References
 **********
 
+.. [Bjo16] Bjorklund, M. (ed.). *The YANG 1.1 Data Modeling Language.*
+	   `draft-ietf-netmod-rfc6020bis`__, Internet Engineering Task
+	   Force, 2016.
+
+__ https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis
+
+.. [Hue97] Huet, G. The Zipper. *J. Functional Programming* **7** (5):
+	   549–554, 1997. Available online__.
+
+__ https://www.st.cs.uni-saarland.de/edu/seminare/2005/advanced-fp/docs/huet-zipper.pdf
+
 .. [Lho16] Lhotka, L. *JSON Encoding of Data Modeled with YANG.*
 	   `draft-ietf-netmod-yang-json`__, Internet Engineering Task
 	   Force, 2016.

docs/typealiases.rst

@@ -6,17 +6,57 @@ Type Aliases
    :synopsis: Type aliases
 .. moduleauthor:: Ladislav Lhotka <lhotka@nic.cz>
 
-We define several type aliases shown in the following table to give more meaning to type hints [PEP484].
-
-+----------------+--------------------------------------------------------------+--------+
-| Alias          | Type                                                         | Remark |
-+================+==============================================================+========+
-| Uri            | :class:`str`                                                 | (1)    |
-+----------------+--------------------------------------------------------------+--------+
-| YangIdentifier | :class:`str`                                                 | (2)    |
-+----------------+--------------------------------------------------------------+--------+
-| RevisionDate   | ``Optional[``:class:`str```]``                               | (3)    |
-+----------------+--------------------------------------------------------------+--------+
-| Value          | Union[:class:`int`, :class:`str`, :class:`decimal.Decimal`,	|        |
-|                | List["Value"], Dict[QName, "Value"]]				|        |
-+----------------+--------------------------------------------------------------+--------+
+We define several type aliases shown in the following table to give
+more meaning to type hints [PEP484]_. The types ``List``,
+``Optional``, ``Tuple`` and ``Union`` are defined in the :mod:`typing`
+module.
+
++--------------+-------------------------+------+
+|Alias         |Type                     |Remark|
++==============+=========================+======+
+|RevisionDate  |Optional[:class:`str`]   | \(1) |
++--------------+-------------------------+------+
+|Uri           |:class:`str`             | \(2) |
++--------------+-------------------------+------+
+|YangIdentifier|:class:`str`             | \(3) |
++--------------+-------------------------+------+
+|QName         |:class:`str`             | \(4) |
++--------------+-------------------------+------+
+|ScalarValue   |Union[:class:`int`,      | \(5) |
+|              |:class:`decimal.Decimal`,|      |
+|              |:class:`str`]            |      |
++--------------+-------------------------+------+
+|NodeName      |Tuple[YangIdentifier,    | \(6) |
+|              |YangIdentifier]          |      |
++--------------+-------------------------+------+
+|SchemaAddress |List[NodeName]           | \(7) |
++--------------+-------------------------+------+
+|ModuleId      |Tuple[YangIdentifier,    | \(8) |
+|              |Optional[RevisionDate]]  |      |
++--------------+-------------------------+------+
+
+
+**Remarks:**
+
+1. Revision date, defined in [Bjo16]_, sec. `7.1.9`_.
+
+2. Uniform resource identifier [RFC3986]_.
+
+3. YANG identifier, defined in [Bjo16]_, sec. `6.2`_.
+
+4. Qualified name of an instance object member in the form
+   [*module_name*``:``]*local_name*.
+
+5. Scalar value of a **leaf** or **leaf-list** instance.
+
+6. Node name identifying a *schema node*. The first component of the
+   tuple is the namespace (i.e. name of the module in which the node
+   is defined), and the second component is the node identifier.
+
+7. Schema address in the form of a sequence of node names.
+
+8. Module identifier: module name and optional revision date. If the
+   revision date is ``None``, the revision is unspecified.
+
+.. _7.1.9: https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis-11#section-7.1.9
+.. _6.2: https://tools.ietf.org/html/draft-ietf-netmod-rfc6020bis-11#section-6.2