Trees vs Nodes

[jlumpe]

I haven't had much time to contribute to this package for quite a while, but this was a major issue I identified way back when I was thinking about expanding the interface. After it came up recently in #115 I'm adding this issue just to start the discussion. It is more of a problem for when/if the API gets expanded further and not something that needs to be fixed right now.

Basically, there is a subtle but important difference between a tree and a node. A node is just some type that implements children(), while a tree represents an entire collection of nodes with a single root and all their parent/child relationships. Part of the confusion is because any node implicitly represents a tree with itself as the root. This is just part of a tree's inherently recursive nature - any subtree is itself a tree in its own right. Several functions currently in this package conceptually work on full trees but take as an argument a node which is the root of that tree. However, this isn't necessarily the same as "the tree the node belongs to".

If a node implements parent links there is a well-defined "whole tree" that it belongs to (the root of which can be obtained by moving up the chain of parent links as far as possible). If there aren't explicit parent links then the "true" root could depend on context - e.g. in parsed JSON data made of nested arrays and dictionaries there is a node that corresponds to the root of the document. An API function that is just passed a plain array nested several layers deep in this document has no way of knowing that, and maybe should treat that node as possibly existing within a larger tree rather than assuming it is the root.

Currently there is just one type (IndexedTree) which represents a whole tree without also being a node itself, but I could definitely envision others. It would make sense to have the API be able to deal with these types in general.