- Add support for node inheritance and document it.

- Update examples/startup.lua to properly detect inherited nodes
- Fix makefile to build YDBDoc against the current directory's docs.

Docs:
- Document `yottadb.inherit()`
- Update documentation with new node methods: `kill`, `grab`, `release`, and `__repr`.
- Other minor documentation improvements.

Makefile

@@ -62,11 +62,17 @@ docs/lua-yottadb-ydbdocs.rst: $(DOC_DEPS)
 	@echo
 
 # Test that YDBDoc can use the docs -- requires you to clone YDBDoc into YDBDOC_PATH
-YDBDOC_PATH:=~/projects/anet/YDBDoc
+YDBDOC_PATH:=$(work_dir)/YDBDoc
 ydbdocs: docs/lua-yottadb-ydbdocs.rst
-	@test -d $(YDBDOC_PATH) || { echo "Could not find a clone of YDBDoc. Run 'make ydbdocs YDBDOC_PATH=<path_to_YDBDoc_clone>'"; exit 1; }
-	cp $< $(YDBDOC_PATH)
-	make -C $(YDBDOC_PATH) html
+	@test -d "$(YDBDOC_PATH)" || { echo "Could not find a clone of YDBDoc. Run 'make ydbdocs YDBDOC_PATH=<path_to_YDBDoc_clone>'"; exit 1; }
+	@# YDBDoc looks for a lua-yottadb directory in its parent, pulls it, and builds against doc files there, so symlink that to here.
+	@if [[ `readlink -f .` != `readlink -f "$(YDBDOC_PATH)/../lua-yottadb"` ]]; then \
+		echo "For YDBDocs to build against this lua-yottadb directory, YDBDoc/lua-yottadb must point here. Do:" && \
+		echo "  ln -st \"$(YDBDOC_PATH)/..\" `readlink -f .`"; \
+		exit 1; \
+	fi
+	make -C "$(YDBDOC_PATH)" html
+	echo "Open $(YDBDOC_PATH)/MultiLangProgGuide/_build/html/MultiLangProgGuide.html to check the new YottaDB documentation."
 
 
 # ~~~ Release a new version and create luarock

README.md

@@ -116,7 +116,7 @@ for index, oaktree in pairs(trees) do
 -- Oak 3 is 15.0m high
 ```
 
-You may also wish to look at **`node:gettree()`** which has multiple uses. On first appearances, it just loads a database tree into a Lua table (opposite of `settree` above), but it also allows you to iterate over a whole database tree and process each node through a filter function. For example, to use `print` as a filter function, do `node:gettree(nil, print)` from the [API docs](https://htmlpreview.github.io/?https://github.com/anet-be/lua-yottadb/blob/master/docs/yottadb.html#node:gettree). Incidentally, lua-yottadb itself uses `gettree` to implement `node:dump()`.
+You may also wish to look at **`node:gettree()`** which has multiple uses. On first appearances, it just loads a database tree into a Lua table (opposite of `settree` above), but it also allows you to iterate over a whole database tree and process each node through a filter function. For example, to use `print` as a [filter function](https://htmlpreview.github.io/?https://github.com/anet-be/lua-yottadb/blob/master/docs/yottadb.html#node:gettree), do `node:gettree(nil, print)`. Incidentally, lua-yottadb itself uses `gettree` to implement `node:dump()`.
 
 ### Database transactions are also available:
 

docs/lua-yottadb-ydbdocs.rst

@@ -1174,9 +1174,79 @@ and matching M file `arithmetic.m <https://github.com/anet-be/lua-yottadb/blob/m
 
 
 
-++++++++++++
-Class node
-++++++++++++
++++++++++++++++++++++++
+Node class operations
++++++++++++++++++++++++
+
+
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+inherit (node_func[, metatable])
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a new node class that inherits from the yottadb.node superclass.
+The returned function will generate nodes of a new class (a new metatable). You may add or
+override class methods by adding them to ``new_metatable`` either before or after calling inherit.
+Any class method the user does not define in ``new_metatable`` will default to the class method of the superclass.
+If desired, the new class may be further subclassed, also using ``inherit``.
+
+
+
+* ``node_func``:
+  ``yottadb.node`` or a descendent that inherits from it using ``inherit``
+
+* ``metatable``:
+  (*optional*)
+  to use for the new node class. Defaults to ``{}``.
+
+
+:Returns:
+  #. function that generates node of the new type
+
+  #. subclass metatable (modified)
+
+  #. superclass metatable used by the original node_func
+
+
+
+
+:Example:
+
+  .. code-block:: lua
+    :dedent: 2
+    :force:
+
+      -- To average all data stored in a particular database node:
+      averaged_node, class, superclass = ydb.inherit(ydb.node)
+      function class:set(value)  sum=sum+value  writes=writes+1  return superclass.set(self, value)  end
+
+      -- Now use the new class
+      sum, writes = 0, 0
+      shoesize = averaged_node('shoesize')
+      shoesize:set(5)
+      shoesize:set(10)
+      shoesize.__ = 15  -- overriding set() also changes the behaviour of: .__ =
+      print('Average', sum/writes)
+      -- Average 10.0
+
+
+
+~~~~~~~~~~~~~~~~~
+isnode (object)
+~~~~~~~~~~~~~~~~~
+
+Tests whether object is a node object or inherits from a node object.
+
+
+
+* ``object``:
+  to test
+
+
+:Returns:
+    boolean true or false
+
 
 
 
@@ -1195,11 +1265,11 @@ Calling this on an existing node ``yottadb.node(node)`` creates an (immutable) c
  * Several standard Lua operators work on nodes. These are: ``+`` ``-`` ``=`` ``pairs()`` ``tostring()``
  * Although the syntax ``node:method()`` is pretty, be aware that it is slow. If you need speed, prefix the node method
    with two underscores, ``node:__method()``, which is equivalent, but 15x faster.
-   The former is slow because in Lua, ``node:method()`` is syntactic sugar which expands to ``node.method(node)``,
+   The former is slow because in Lua, ``node:method(...)`` is syntactic sugar which expands to ``node.method(node, ...)``,
    causing lua-yottadb to create an intermediate node object ``node.method``. It is only when this new object gets called
-   with ``()``, and the first parameter is of type ``node``, that lua-yottadb detects it was supposed to be a method access
-   and invokes ``node.__method()``, discarding the intermediate subnode object it created.
- * Because the ``__`` prefix accesses *methods* names (as above), it cannot access *node* names.
+   with ``(node, ...)``, and the first parameter is of type ``node``, that the ``__call`` metamethod detects it was supposed to
+   be a method access and invokes ``node.__method()``, discarding the intermediate subnode object it created.
+ * Because the ``__`` prefix accesses *method* names (as above), it cannot access database subnode names starting with ``__``.
    Instead, use mynode('__nodename') to access a database node named ``__nodename``.
  * This ``__`` prefix handling also means that object method names that start with two underscores, like ``__tostring``,
    are only accessible with an *additional* ``__`` prefix; for example, ``node:____tostring()``.
@@ -1243,6 +1313,13 @@ Calling this on an existing node ``yottadb.node(node)`` creates an (immutable) c
 
 
 
+++++++++++++
+Node class
+++++++++++++
+
+
+
+
 ~~~~~~~~~~~~~~~~~~
 node:__ipairs ()
 ~~~~~~~~~~~~~~~~~~
@@ -1331,6 +1408,21 @@ Mutability can be tested for using ``node:ismutable()``
 
 
 
+~~~~~~~~~~~~~~~~
+node:__repr ()
+~~~~~~~~~~~~~~~~
+
+Return raw representation of node's unique memory address.
+
+
+
+:Returns:
+    string in hexadecimal format, starting with ``0x``.
+
+
+
+
+
 ~~~~~~~~~~~~~~~~~~~~~
 node:delete_tree ()
 ~~~~~~~~~~~~~~~~~~~~~
@@ -1369,6 +1461,7 @@ node:get ([default])
 
 Get ``node``'s value.
 Equivalent to ``node.__``, but 2.5x slower.
+If node is subclassed, then ``node.__`` invokes the subclass's ``node:__get()`` if it exists.
 
 
 
@@ -1569,13 +1662,17 @@ node:set (value)
 
 Set ``node``'s value.
 Equivalent to ``node.__ = x``, but 4x slower.
+If node is subclassed, then ``node.__ = x`` invokes the subclass's ``node:__set(x)`` if it exists.
 
 
 
 * ``value``:
   New value or ``nil`` to delete node
 
 
+:Returns:
+    value
+
 
 
 
@@ -1679,9 +1776,9 @@ Note that ``subscripts()`` order is guaranteed to equal the M collation sequence
 
 
 
-+++++++++++++++++
-Node properties
-+++++++++++++++++
++++++++++++++++++++++++
+Node class properties
++++++++++++++++++++++++
 
 
 
@@ -1793,12 +1890,50 @@ Fetch the varname of the node: the leftmost subscript.
 
 
 +++++++++++
-Class key
+Key class
 +++++++++++
 
 
 
 
+~~~~~~~~~~~~
+_property_
+~~~~~~~~~~~~
+
+Properties of key object that are accessed with a dot.
+These properties, listed below, are unlike object methods, which are accessed with a colon.
+This kind of property access is for backward compatibility.
+
+For example, access data property with: ``key.data``
+
+
+
+* ``name``:
+  equivalent to ``node:name()``
+
+* ``data``:
+  equivalent to ``node:data()``
+
+* ``has_value``:
+  equivalent to ``node:has_value()``
+
+* ``has_tree``:
+  equivalent to ``node:has_tree()``
+
+* ``value``:
+  equivalent to ``node.__``
+
+* ``__varname``:
+  database variable name string -- for compatibility with a previous version
+
+* ``__subsarray``:
+  table array of database subscript name strings -- for compatibility with a previous version
+
+
+
+
+
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 key (varname[, subsarray])
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1835,44 +1970,6 @@ property names for backward compatibility, as follows:
 
 
 
-~~~~~~~~~~~~~~~~
-key._property_
-~~~~~~~~~~~~~~~~
-
-Properties of key object that are accessed with a dot.
-These properties, listed below, are unlike object methods, which are accessed with a colon.
-This kind of property access is for backward compatibility.
-
-For example, access data property with: ``key.data``
-
-
-
-* ``name``:
-  equivalent to ``node:name()``
-
-* ``data``:
-  equivalent to ``node:data()``
-
-* ``has_value``:
-  equivalent to ``node:has_value()``
-
-* ``has_tree``:
-  equivalent to ``node:has_tree()``
-
-* ``value``:
-  equivalent to ``node.__``
-
-* ``__varname``:
-  database variable name string -- for compatibility with a previous version
-
-* ``__subsarray``:
-  table array of database subscript name strings -- for compatibility with a previous version
-
-
-
-
-
-
 ~~~~~~~~~~~~~~~~~~~~
 key:delete_node ()
 ~~~~~~~~~~~~~~~~~~~~