trivet 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 816c724387a4e6931697972dc59868bce4032a3cc7df3064e84f9cf9d6dc9b87
+  data.tar.gz: 33e2980a16a1e6575816635ee34c2273935bf185330c7ef2a190b399bc3a53ef
+SHA512:
+  metadata.gz: 15ad703f9a3977dad38e21b0e12159048fb348dc52beeeb79e03ce5bbd835b76bcaf887ee24e4ba18c1f846fac17fa027b643ce1cf1ea4553edf285f57dc442c
+  data.tar.gz: 1fad0c2a2c2ca47839e48ced488964b5a13ac3474b6207f985b0d2a7de68b30f0320f63428709da92f01d6cb670e356854359a38b8eebdd8d9c5ca00d73c3f43

data/README.md

@@ -0,0 +1,79 @@
+# Trivet
+
+Trivet is a generic class for organizing a hierarchy.
+
+## Basic usage
+
+     1.  food = Trivet::Node.new('food')
+     2.  
+     3.  food.node('spices') do |spices|
+     4.      spices.node 'paprika'
+     5.  
+     6.      spices.node('pepper') do |pepper|
+     7.          pepper.node 'java'
+     8.          pepper.node 'matico'
+     9.          pepper.node 'cubeb'
+    10.      end
+    11.  end
+    12.  
+    13.  food.node('fruit') do |fruit|
+    14.      fruit.node('red') do |red|
+    15.          red.node 'cherry'
+    16.          red.node 'apple'
+    17.      end
+    18.  end
+    19.  
+    20.  puts food.to_tree
+
+Line 1 creates a `Trivet::Node` object and assigns it the id "food".
+Lines 3 to 18 use the `node()` method to create child nodes.
+
+Line 20 uses the `to_tree()` method to display the tree as text, which
+looks like this:
+
+    food
+        spices
+            paprika
+                pepper
+                    java
+                    matico
+                    cubeb
+        fruit
+            red
+                cherry
+                apple
+
+The tree can include non Trivet::Node objects.
+
+    food = Trivet::Node.new('food')
+    
+    food.node('spices') do |spices|
+        spices.node('paprika') do |paprika|
+            paprika.children.push 'By from Fred'
+        end
+    end
+
+See documentation for `Trivet::Node`, `Trivet::Document`, and `Trivet::ChildSet`
+for more documentation.
+
+## Install
+
+```
+gem install codeblock
+```
+
+## Name
+
+The name "Trivet" doesn't have any particular significance. My friend has a cat
+named "Trivet". Meow.
+
+## Author
+
+Mike O'Sullivan
+mike@idocs.com
+
+## History
+
+| version | date          | notes                                                 |
+|---------|---------------|-------------------------------------------------------|
+| 1.0     | June 18, 2020 | Initial upload.                                       |

data/lib/trivet.rb

@@ -0,0 +1,1418 @@
+require 'forwardable'
+
+
+#===============================================================================
+# Trivet
+#
+
+# The Trivet module itself doesn't do much. It holds the version and a few
+# constants that are used in queries. You probably want to start with
+# Trivet::Node to learn about this package.
+module Trivet
+	# Version
+	VERSION = '1.0'
+	
+	#---------------------------------------------------------------------------
+	# query control constants
+	#
+	
+	# Always recurse in query.
+	ALWAYS = 0
+	
+	# Don't recurse into matched nodes.
+	UNTIL_MATCH = 1
+	
+	# Stop entire query when a match is found.
+	STOP_ON_FIRST = 2
+	
+	#
+	# query control constants
+	#---------------------------------------------------------------------------
+end
+#
+# Trivet
+#===============================================================================
+
+
+#===============================================================================
+# Trivet::Querier
+#
+
+# This module provides the query_first() method for Trivet::Node and
+# Trivet::Document.
+module Trivet::Querier
+	# Works like query(), but only returns/yields the first find.
+	def query_first(qobj, opts={})
+		# run a query
+		query(qobj, opts) do |node|
+			# yield
+			if block_given?
+				yield node
+			end
+			
+			# return
+			return node
+		end
+		
+		# didn't find any such node
+		return nil
+	end
+end
+#
+# Trivet::Querier
+#===============================================================================
+
+
+#===============================================================================
+# Trivet::Node
+#
+
+# Objects of this class represent a single node in a hierarchy.
+class Trivet::Node
+	# delegate
+	extend Forwardable
+	delegate %w(remove_child) => :@children
+	
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	# Creates a new Trivet::Node object. The first param can be a parent node,
+	# the id of the new node, or nil.
+	def initialize(pod=nil)
+		@id = nil
+		@parent = nil
+		@children = Trivet::Childset.new(self)
+		@misc = {}
+		
+		# if parent object send
+		if pod.is_a?(Trivet::Node) or pod.is_a?(Trivet::Document)
+			self.parent = pod
+		elsif pod.is_a?(String)
+			self.id = pod
+		end
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# readers
+	#
+	
+	# Returns the parent object of the node, or nil if there is no parent.
+	attr_reader :parent
+	
+	# A Trivet::ChildSet object containing the children. This property can
+	# generally be treated like an array, but it has a few other features as
+	# well.
+	attr_reader :children
+	
+	# A hash of any miscellaneous information you want to attach to the node.
+	attr_reader :misc
+	
+	# Returns the id of the node, or nil if it does not have an id.
+	attr_reader :id
+	
+	#
+	# readers
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# can_have_children?
+	#
+	
+	# This method indicates if the node can have any children. By default this
+	# method always return true. Override this method in your own class to
+	# set more fine grained rules.
+	def can_have_children?
+		return true
+	end
+	#
+	# can_have_children?
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# parent=
+	#
+	
+	# This method is a shortcut for Trivet::Node#set_parent() without any
+	# options.
+	def parent=(new_parent)
+		return set_parent(new_parent)
+	end
+	#
+	# parent=
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# set_parent
+	#
+	
+	# Sets a new parent for the node. The new parent can be either a
+	# Trivet::Node object or a Trivet::Document object.
+	#
+	# For example, we'll start with the standard tree we've been using:
+	#
+	#    food
+	#       spices
+	#          paprika
+	#          pepper
+	#             java
+	#             matico
+	#             cubeb
+	#       fruit
+	#          red
+	#             cherry
+	#             apple
+	#
+	# Now we'll set fruit's parent to the pepper node:
+	#
+	#    fruit = food.node_by_id('fruit')
+	#    pepper = food.node_by_id('pepper')
+	#    fruit.set_parent pepper
+	#
+	# That moves the fruit node and all its descendents into pepper:
+	#
+	#    food
+	#       spices
+	#          paprika
+	#          pepper
+	#             java
+	#             matico
+	#             cubeb
+	#             fruit
+	#                red
+	#                   cherry
+	#                   apple
+	#
+	# option: index
+	#
+	# The index option indicates which position within the parent the node
+	# should be moved to. This option has no meaning if the new parent is a
+	# Trivet::Document object.
+	# 
+	# Set index to 'first' to move it to the first position:
+	#
+	#    fruit = food.node_by_id('fruit')
+	#    pepper = food.node_by_id('pepper')
+	#    fruit.set_parent pepper, 'index'=>'first'
+	#
+	# Set index to an integer to move the node to that index within the parent.
+	#
+	#    fruit = food.node_by_id('fruit')
+	#    pepper = food.node_by_id('pepper')
+	#    fruit.set_parent pepper, 'index'=>1
+	#
+	# nil
+	#
+	# If the parent param is nil then the object is unlinked from its parent.
+	def set_parent(new_parent, opts={})
+		# $tm.hrm @id
+		opts = {'recurse'=>true}.merge(opts)
+		index = opts['index'] || 'last'
+		
+		# add to new_parent
+		if new_parent
+			# add to another node
+			if new_parent.is_a?(Trivet::Node)
+				new_parent.trace(self)
+				unlink()
+				@parent = new_parent
+				
+				# add to parent's children
+				if opts['recurse']
+					if index == 'last'
+						@parent.children.push self, 'recurse'=>false
+					elsif index == 'first'
+						@parent.children.unshift self, 'recurse'=>false
+					elsif index.is_a?(Integer)
+						@parent.children.insert index, self, 'recurse'=>false
+					else
+						raise 'set-parent-unknown-index: ' + index.to_s
+					end
+				end
+			
+			# new parent is a document
+			elsif new_parent.is_a?(Trivet::Document)
+				unlink()
+				@parent = new_parent
+				
+				# set as document's root
+				if opts['recurse']
+					new_parent.set_root self, 'recurse'=>false
+				end
+			
+			# else raise exception
+			else
+				raise 'unknown-class-for-parent: ' + new_parent.class.to_s
+			end
+		
+		# unlink node because it does not have a parent anymore.
+		else
+			unlink()
+		end
+	end
+	#
+	# set_parent
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# node
+	#
+	
+	# Values for positioning a node within its parent. These values are used
+	# internally only.
+	INDEX_WITHIN = %w{first last}
+	
+	# Values for positioning a node before or after a sibling. These values are
+	# used internally only.
+	INDEX_WITHOUT = %w{before after}
+	
+	##
+	# Create a node and positions the new node either within the calling node,
+	# before it, after it, or replaces it. By default, the new node is
+	# positioned as the last child node of the caller.
+	#
+	# In its simplest use, node() creates a new node, yields it if given a
+	# block, and returns it. You can build structures by calling node() within
+	# node blocks. If a single string is given as a param, that string is used
+	# for the `id` for the new node.
+	#
+	#    food = Trivet::Node.new()
+	#    food.id = 'food'
+	#    
+	#    food.node('spices') do |spices|
+	#        spices.node 'paprika'
+	#    
+	#        spices.node('pepper') do |pepper|
+	#            pepper.node 'java'
+	#            pepper.node 'matico'
+	#            pepper.node 'cubeb'
+	#        end
+	#    end
+	#
+	# option: index
+	#
+	# The index option indicates where the new node should be positioned. This
+	# option can have one of the following values:
+	#
+	# - first: The new node becomes the first child of the caller object.
+	# - last: The new node becomes the last child of the caller object. This is the default behavior.
+	# - before: The new node is placed before the caller object.
+	# - after: The new node is placed after the caller object.
+	# - replace: The node node replaces the caller object and the caller is removed from the tree.
+	# - [integer]: The new node is placed at the index of the given integer.
+	#
+	def node(opts={})
+		# normalize opts
+		if opts.is_a?(String)
+			opts = {'id'=>opts}
+		end
+		
+		# $tm.hrm
+		idx = opts['index'] || 'last'
+		
+		# create child object
+		new_node = child_class(opts).new()
+		
+		# id if sent
+		if opts['id']
+			new_node.id = opts['id']
+		end
+		
+		# add to this node
+		if INDEX_WITHIN.include?(idx) or idx.is_a?(Integer)
+			new_node.set_parent self, 'index'=>idx
+		
+		# add to parent
+		elsif INDEX_WITHOUT.include?(idx)
+			if @parent
+				if idx == 'before'
+					new_node.set_parent @parent, 'index'=>self.index
+				elsif idx == 'after'
+					new_node.set_parent @parent, 'index'=>self.index + 1
+				else
+					raise 'unrecognized-without-index: ' + idx.to_s
+				end
+			else
+				raise 'cannot-set-before-or-after-if-no-parent'
+			end
+		
+		# replace
+		elsif idx == 'replace'
+			new_node.set_parent @parent, 'index'=>self.index
+			
+			@children.to_a.each do |child|
+				child.parent = new_node
+			end
+			
+			unlink()
+		else
+			raise 'node-unknown-index: ' + idx.to_s
+		end
+		
+		# yield if necessary
+		if block_given?
+			yield new_node
+		end
+		
+		# return
+		return new_node
+	end
+	#
+	# node
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# id=
+	#
+	
+	# Sets the id property of the node. If any other node already has that id
+	# then an exception is raised.
+	def id=(new_id)
+		# $tm.hrm
+		
+		# look for another node with this id
+		if new_id
+			root.traverse('self'=>true) do |tag|
+				if (tag.id == new_id) and (tag != self)
+					raise 'redundant-id: ' + new_id.to_s
+				end
+			end
+		end
+		
+		# set id
+		@id = new_id
+	end
+	#
+	# id=
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# index
+	#
+	
+	# Returns the index of the node within the parent. Returns nil if the node
+	# has no parent.
+	def index
+		if @parent
+			return @parent.children.find_index(self)
+		else
+			return nil
+		end
+	end
+	#
+	# index
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# traverse
+	#
+	
+	# Traverses the tree starting with the children of the node. Each node in
+	# the tree is yielded to the block if there is one. Returns and array of
+	# descendents.
+	#
+	#    food.traverse() do |node|
+	#        puts ('  ' * node.depth) +  node.id
+	#    end
+	#
+	# That gives us output similar to that of the to_tree() method.
+	#
+	#    spices
+	#      paprika
+	#      pepper
+	#        java
+	#        matico
+	#        cubeb
+	#    fruit
+	#      red
+	#        cherry
+	#        apple
+	#
+	# By default, the node on which you call this method itself is not
+	# traversed. You can include that node with the 'self' option:
+	#
+	#    food.traverse('self'=>true) do |node|
+	#        puts ('  ' * node.depth) +  node.id
+	#    end
+	#
+	# The first parameter for the yield block is the node, as in the examples
+	# above. The second param is a Trivet::TraverseControl object which can be
+	# used to control the recursion.
+	#
+	# Prune recursion
+	#
+	# You can indicate that the traversal should not recurse into a node's
+	# children with Trivet::TraverseControl.prune. For example, the following
+	# code doesn't traverse into the spices node:
+	#    food.traverse('self'=>true) do |node, ctl|
+	#        puts ('  ' * node.depth) +  node.id
+	#    
+	#        if node.id == 'spices'
+	#            ctl.prune
+	#        end
+	#    end
+	#
+	# Giving us this output:
+	# 
+	#    food
+	#      spices
+	#      fruit
+	#        red
+	#          cherry
+	#          apple
+	#
+	# Stop recursion
+	#
+	# You can stop the recursion by calling Trivet::TraverseControl.stop. For
+	# example, suppose you want to stop the traversal completely when you get to
+	# the "java" node. You could do that like this:
+	#
+	#    food.traverse('self'=>true) do |node, ctl|
+	#        puts ('  ' * node.depth) +  node.id
+	#    
+	#        if node.id == 'java'
+	#            ctl.stop
+	#        end
+	#    end
+	#
+	# That gives us output like this:
+	#
+	#    food
+	#      spices
+	#        paprika
+	#        pepper
+	#          java
+	def traverse(opts={}, &block)
+		ctrl = opts['ctrl'] || Trivet::TraverseControl.new()
+		rv = []
+		
+		# yield self
+		if opts['self']
+			# yield
+			if block_given?
+				yield self, ctrl
+			end
+			
+			# add to return array
+			rv.push self
+			
+			# return if stopped
+			ctrl.stopped and return rv
+		end
+		
+		# if pruned, don't recurse into children, but continue to next sibling node
+		if ctrl.pruned
+			ctrl.pruned = false
+		
+		# recurse into children
+		else
+			# puts "--- #{self}"
+			
+			@children.to_a.each do |child|
+				if child.is_a?(Trivet::Node)
+					rv += child.traverse('self'=>true, 'ctrl'=>ctrl, &block)
+					ctrl.stopped and return rv
+					ctrl.pruned = false
+				end
+			end
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# traverse
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# child_class
+	#
+	
+	# Returns the class to use for new nodes in Trivet::Node.node(). By default,
+	# this method returns the same class as the calling node. Override this
+	# method to create different rules for the class to use.
+	def child_class(*opts)
+		return self.class
+	end
+	#
+	# child_class
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# root
+	#
+	
+	# Returns the root node of the tree. Returns self if the node has no
+	# parent.
+	def root
+		if @parent
+			return @parent.root
+		else
+			return self
+		end
+	end
+	#
+	# root
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# unlink
+	#
+	
+	# Removes the node from the tree.
+	def unlink(opts={})
+		# $tm.hrm
+		opts = {'recurse'=>true}.merge(opts)
+		
+		# remove from parent
+		if @parent and opts['recurse']
+			if @parent.is_a?(Trivet::Document)
+				@parent.set_root nil, 'recurse'=>false
+			elsif @parent.is_a?(Trivet::Node)
+				@parent.remove_child self
+			else
+				raise 'unlink-unknown-parent-class: ' + @parent.class.to_
+			end
+		end
+		
+		# set parent to nil
+		@parent = nil
+	end
+	#
+	# unlink
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# ancestors
+	#
+	
+	# Returns an array of the node's ancestors.
+	def ancestors
+		if @parent.is_a?(Trivet::Node)
+			return @parent.heritage()
+		else
+			return []
+		end
+	end
+	#
+	# ancestors
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# heritage
+	#
+	
+	# Returns an array of the node's ancestors plus the node itself.
+	def heritage
+		if @parent.is_a?(Trivet::Node)
+			return @parent.heritage() + [self]
+		else
+			return [self]
+		end
+	end
+	#
+	# heritage
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# trace
+	#
+	
+	# Checks if a node is about to become nested within itself. This method is
+	# used by Trivet::Node.set_parent to prevent circular references. Generally
+	# you don't need to call this method.
+	def trace(new_node)
+		if new_node == self
+			raise 'circular-reference'
+		end
+		
+		# trace to parent
+		if @parent and not(@parent.is_a?(Trivet::Document))
+			@parent.trace(new_node)
+		end
+	end
+	#
+	# trace
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# query
+	#
+	
+	# Runs a query on the tree, yielding and returning nodes that match the
+	# given query. This method is really only useful if you subclass
+	# Trivet::Node and override Trivet::Node.match?(). By default, match? always
+	# returns true. The query param can be any kind of object you want it to be.
+	# That param will be passed to match? for each node. If match? returns true
+	# then the query yields/returns that node.
+	# 
+	# In these examples, we'll assume a tree like this:
+	#
+	#    food
+	#       spices
+	#          paprika
+	#          pepper
+	#             java
+	#             matico
+	#             cubeb
+	#       fruit
+	#          red
+	#             cherry
+	#             apple
+	#
+	# For example, you could override match? so that it returns true if a given
+	# string is within a node's id.
+	#
+	#    class MyNode < Trivet::Node
+	#        def match?(qobj)
+	#            if @id
+	#                return @id.match(/#{qobj}/mu)
+	#            else
+	#                return false
+	#            end
+	#        end
+	#    end
+	#
+	#
+	# You could then query for nodes that have 'o' in their id:
+	#
+	#    food = MyNode.new('food')
+	#    
+	#    # ... add a bunch of child nodes
+	#    
+	#    food.query('o') do |node|
+	#        puts node.id
+	#    end
+	#
+	# That query returns one node, 'matico'
+	#
+	# option: self
+	#
+	# By default, the query does not include the node itself, only its
+	# descendents. To include the node itself, use the 'self' option.
+	#
+	#    food.query('o', 'self'=>true) do |node|
+	#        puts node.id
+	#    end
+	#
+	# That query will return 'food' and 'matico'.
+	#
+	# option: recurse
+	#
+	# The recurse option indicates how far into the tree the query should
+	# recurse. The default is Trivet::ALWAYS, which means to recurse all the way
+	# down.
+	#
+	# Trivet::UNTIL_MATCH means to not recurse into nodes that match the query.
+	# So if a node matches, its children are not included in the query.
+	#
+	# Trivet::STOP_ON_FIRST means that the query is stopped completely after the
+	# first match is found. Using this option means that the query always
+	# returns either zero or one matches.
+	#
+	def query(qobj, opts={})
+		ctl = opts['recurse'] || Trivet::ALWAYS
+		rv = []
+		
+		# traverse
+		self.traverse(opts) do |node, recurse|
+			if node.match?(qobj)
+				# add to return array
+				rv.push node
+				
+				if ctl == Trivet::UNTIL_MATCH
+					recurse.prune
+				elsif ctl == Trivet::STOP_ON_FIRST
+					recurse.stop
+				end
+			end
+		end
+		
+		# yield
+		if block_given?
+			rv.each do |node|
+				yield node
+			end
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# query
+	#---------------------------------------------------------------------------
+	
+	
+	# include method from querier
+	include Trivet::Querier
+	
+	
+	#---------------------------------------------------------------------------
+	# match?
+	#
+	
+	# This method is called for each node in a query. If this method return true
+	# then the node is yielded/returned in the query. By default, this method
+	# always returns true. See Trivet::Node#query() for more details.
+	def match?(qobj)
+		return true
+	end
+	#
+	# match?
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_s
+	#
+	
+	# Returns the id if there is one. Otherwise returns Object#to_s.
+	def to_s
+		if @id
+			return @id
+		else
+			return super()
+		end
+	end
+	#
+	# to_s
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_tree
+	#
+	
+	# This method is mainly for development and debugging. Returns a string
+	# consisting of the node and all its descending arranged as an indented
+	# tree. Each node's Trivet::Node#to_s method is used to display the node.
+	# Descendents that are not Trivet::Node objects are not displayed.
+	def to_tree(opts={})
+		opts = {'depth'=>0}.merge(opts)
+		rv = '   ' * opts['depth'] + self.to_s
+		
+		# indent
+		if opts['indent']
+			rv = opts['indent'] + rv
+		end
+		
+		# send_opts
+		send_opts = opts.clone
+		send_opts['depth'] += 1
+		
+		# recurse
+		@children.each do |child|
+			if child.is_a?(Trivet::Node)
+				rv += "\n" + child.to_tree(send_opts)
+			end
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# to_tree
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# node_by_id
+	#
+	
+	# Searches for a node by its id.
+	def node_by_id(qid)
+		if @id == qid
+			return self
+		end
+		
+		# check children
+		@children.each do |child|
+			if child.is_a?(Trivet::Node)
+				if node = child.node_by_id(qid)
+					return node
+				end
+			end
+		end
+		
+		# didn't find the node
+		return nil
+	end
+	#
+	# node_by_id
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# can_have_child?
+	#
+	
+	# This methd is called when a node or other object is to be set as the child
+	# of the current node. By default, always returns true. Override this method
+	# to create custom rules.
+	def can_have_child?(child)
+		return true
+	end
+	#
+	# can_have_child?
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# document
+	#
+	
+	# Returns the Trivet::Document object that holds the tree. Returns nil if
+	# there is no document.
+	def document()
+		# $tm.hrm
+		return root.parent
+	end
+	#
+	# document
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# unwrap
+	#
+	
+	# Moves the child nodes into the node's parent and deletes self.
+	def unwrap()
+		# $tm.hrm
+		pchildren = @parent.children
+		
+		# move children
+		@children.to_a.each do |child|
+			pchildren.insert self.index, child
+		end
+		
+		# unlink self
+		unlink()
+	end
+	#
+	# unwrap
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# depth
+	#
+	
+	# Returns the depth of the node. The root note returns 0, its children
+	# return 1, etc.
+	def depth
+		return ancestors.length
+	end
+	#
+	# depth
+	#---------------------------------------------------------------------------
+end
+#
+# Trivet::Node
+#===============================================================================
+
+
+#===============================================================================
+# Trivet::Childset
+#
+
+# Objects of this class act like an array of the children of a node. However,
+# unlike an array, attempts to add children result in calling
+# Trivet::Node#can_have_children? and Trivet::Node#can_have_child?
+# to check if the child is allowed.
+class Trivet::Childset
+	#---------------------------------------------------------------------------
+	# delegate
+	#
+	extend Forwardable
+	
+	delegate %w(
+		[] each each_with_index length include? find_index reverse
+		all? at any? empty? reject + - collect cycle) => :@children;
+	#
+	# delegate
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	# Accepts a Trivet::Node object to which this object will be attached.
+	def initialize(node)
+		@node = node
+		@children = []
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# reader
+	#
+	
+	# Returns the Trivet::Node object that this object is attached to.
+	attr_reader :node
+	
+	#
+	# reader
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# method_missing
+	# I was going to delegate all missing methods to the @children array.
+	# However, I need to go through all of Array's methods to check if they need
+	# to be overridden to accomodate the rules for this class.
+	#
+	# Delegates all of an array's methods to @children, except those defined in
+	# this class.
+	# def method_missing(method, *args, &block)
+	#	if @children.respond_to?(method)
+	#		return @children.send(method, *args, &block)
+	#	else
+	#		return super(*args, &block)
+	#	end
+	# end
+	#
+	# method_missing
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# methods for adding a child to the array
+	#
+	
+	# Adds a child to the end of the array. Calls
+	# Trivet::Node#can_have_children? and Trivet::Node#can_have_child? to
+	# check if the child can be added. Does nothing if the node is already a
+	# child.
+	def push(new_child, opts={})
+		return add_child new_child, 'last', opts
+	end
+	
+	# Adds a child to the end of the array. Calls
+	# Trivet::Node#can_have_children? and Trivet::Node#can_have_child? to
+	# check if the child can be added. Does nothing if the node is already a
+	# child.
+	def append(new_child, opts={})
+		return add_child new_child, 'last', opts
+	end
+	
+	# Shortcut for append without any options.
+	def <<(new_child)
+		return append(new_child)
+	end
+	
+	# Adds a child to the beginning of the array. Calls
+	# Trivet::Node#can_have_children? and Trivet::Node#can_have_child? to
+	# check if the child can be added. Does nothing if the node is already a
+	# child.
+	def unshift(new_child, opts={})
+		return add_child new_child, 'first', opts
+	end
+	
+	# Inserts the child at the position indicated by index. Calls
+	# Trivet::Node#can_have_children? and Trivet::Node#can_have_child? to
+	# check if the child can be added. Does nothing if the node is already a
+	# child.
+	def insert(index, new_child, opts={})
+		return add_child new_child, index, opts
+	end
+	#
+	# methods for adding a child to the array
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# remove_child
+	#
+	
+	# Removes the given child from the array of children. Does nothing if the
+	# child isn't present.
+	def remove_child(child, opts={})
+		opts = {'recurse'=>true}.merge(opts)
+		
+		@children.reject!() do |el|
+			el == child
+		end
+	end
+	
+	# Removes all children.
+	def clear()
+		@children.clone.each do |child|
+			child.unlink
+		end
+	end
+	#
+	# remove_child
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# shift
+	#
+	
+	# Unlinks and returns the first child. Returns nil if there are no children.
+	def shift()
+		# remove first element
+		removed = @children.shift
+		
+		# if a node was removed, unlink it
+		if removed.is_a?(Trivet::Node)
+			removed.unlink 'recurse'=>false
+		end
+		
+		# return
+		return removed
+	end
+	#
+	# shift
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# pop
+	#
+	
+	# Unlinks and returns the last child. Returns nil if there are no children.
+	def pop()
+		# remove first element
+		removed = @children.pop
+		
+		# if a node was removed, unlink it
+		if removed.is_a?(Trivet::Node)
+			removed.unlink 'recurse'=>false
+		end
+		
+		# return
+		return removed
+	end
+	#
+	# pop
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# reject!
+	#
+	
+	# Acts like Array#reject!. Rejected children are unlinked.
+	def reject!()
+		# If no block, just return an enumerator. This mimics the behavior of
+		# Array#reject!.
+		if not block_given?
+			return enum_for(:each)
+		end
+		
+		# $tm.hrm
+		all = @children.clone
+		
+		# loop through all
+		all.each do |child|
+			bool = yield(child)
+			bool or remove_child(child)
+		end
+		
+		# return
+		return self
+	end
+	#
+	# reject!
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_a
+	#
+	
+	# Returns an array of the children.
+	def to_a
+		return @children.clone
+	end
+	#
+	# to_a
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	
+	#---------------------------------------------------------------------------
+	# add_child
+	#
+	def add_child(new_child, index, opts)
+		opts = {'recurse'=>true}.merge(opts)
+		
+		# check if this parent is allowed to have this child
+		if not @node.can_have_children?
+			raise 'parent-cannot-have-children: ' + @node.to_s + ' / ' + new_child.to_s
+		end
+		
+		# check if this parent is allowed to have this child
+		if not @node.can_have_child?(new_child)
+			raise 'parent-cannot-have-this-child: ' + @node.to_s + ' / ' + new_child.to_s
+		end
+		
+		# dup_ok
+		if new_child.is_a?(Trivet::Node)
+			dup_ok = false
+		else
+			dup_ok = true
+		end
+		
+		# add to children if not already there
+		if dup_ok or (not @children.include?(new_child))
+			# add to start of array
+			if index == 'first'
+				@children.unshift new_child
+			
+			# add to end of array
+			elsif index == 'last'
+				@children.push new_child
+			
+			# insert at specific index
+			elsif index.is_a?(Integer)
+				# don't allow insert past end of array
+				if index > @children.length
+					raise 'add-child-cannot-insert-past-end'
+				end
+				
+				# insert
+				@children.insert index, new_child
+			
+			# else unknown index
+			else
+				puts 'add-child-invalid-index: ' + index.to_s
+			end
+			
+			# set node's parent if necessary
+			if opts['recurse'] and new_child.is_a?(Trivet::Node)
+				new_child.set_parent @node, 'recurse'=>false
+			end
+		end
+		
+		# always return self
+		return self
+	end
+	#
+	# add_child
+	#---------------------------------------------------------------------------
+end
+#
+# Trivet::Childset
+#===============================================================================
+
+
+#===============================================================================
+# Trivet::Document
+#
+
+# A Trivet::Document object holds the root of a tree. It is not necessary to
+# have a Trivet::Document object to create a tree, but it can be handy to have
+# an object that holds the tree but is not part of the tree itself.
+class Trivet::Document
+	# delegate
+	extend Forwardable
+	delegate %w(node_by_id to_tree) => :@root
+	
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	# Accepts an optional root node.
+	def initialize(new_root=nil)
+		# init
+		@root = nil
+		
+		# set new root
+		if new_root
+			if new_root.is_a?(Class)
+				new_root = new_root.new()
+			end
+			
+			new_root.parent = self
+		end
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# reader
+	#
+	
+	# Returns the root node. Returns nil if the document does not have a root.
+	attr_reader :root
+	
+	#
+	# reader
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# root=
+	#
+	
+	# Sets a new root for the tree. This method is a shortcut for set_root().
+	def root=(new_root)
+		set_root new_root
+	end
+	#
+	# root=
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# set_root
+	#
+	
+	# Sets the root node. The given object must be a Trivet::Node object or nil.
+	def set_root(new_root, opts={})
+		# $tm.hrm
+		opts = {'recurse'=>true}.merge(opts)
+		
+		# must be node
+		unless new_root.is_a?(Trivet::Node) or new_root.nil?
+			raise 'root-not-trivet-node-or-nil'
+		end
+		
+		# unlink old root
+		if @root and opts['recurse']
+			@root.unlink('recurse'=>false)
+		end
+		
+		# set root
+		@root = new_root
+		
+		# set parent
+		if new_root and opts['recurse']
+			new_root.parent = self
+		end
+	end
+	#
+	# set_root
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# traverse
+	#
+	
+	# Traverses the tree starting with the root node. See Trivet::Node#traverse
+	# for details.
+	def traverse(&block)
+		# if no root
+		if not @root
+			raise 'cannot-traverse-without-root'
+		end
+		
+		# traverse
+		@root.traverse 'self'=>true, &block
+	end
+	#
+	# traverse
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# query
+	#
+	
+	# Runs a query starting with, and including, the root node. See
+	# Trivet::Node#query for details.
+	def query(qobj, opts={}, &block)
+		opts = {'self'=>true}.merge(opts)
+		return @root.query(qobj, opts, &block)
+	end
+	#
+	# query
+	#---------------------------------------------------------------------------
+	
+	
+	# include method from querier
+	include Trivet::Querier
+end
+#
+# Trivet::Document
+#===============================================================================
+
+
+#===============================================================================
+# Trivet::TraverseControl
+#
+
+# Objects of this class control the Trivet::Node#traverse method. You generally
+# will not need to instantiate this object yourself. See
+# Trivet::Node#traverse for details.
+class Trivet::TraverseControl
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize
+		@pruned = false
+		@stopped = false
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# accessor, reader
+	#
+	
+	# Returns true if the traversal is being pruned.
+	attr_accessor :pruned
+	
+	# Returns true if the traversal has been stopped.
+	attr_reader :stopped
+	
+	#
+	# accessor, reader
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# prune and stop
+	#
+	
+	# Prunes the traversal so that the process does not recurse into children.
+	def prune
+		@pruned = true
+	end
+	
+	# Stops the traversal completely.
+	def stop
+		@stopped = true
+	end
+	#
+	# stop
+	#---------------------------------------------------------------------------
+end
+#
+# Trivet::TraverseControl
+#===============================================================================