trivet 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b09cc26cad8b1fbc420bb6868a184dbd29d51816ad584deb8196c97d8a69b396
-  data.tar.gz: a70bbc909538386b6dc2e3fb18a7de6cb1d8c2220a40b961c8bba8c5ef7bda4f
+  metadata.gz: '08e89a9e0bf927395b3957b685542a8e9ce4971f455b1214f6fd14dc25d0c15e'
+  data.tar.gz: 7f50bf59dbaa328abfc4dcdd1f2500a342b44430cfdfe758614917ff7ccf84c7
 SHA512:
-  metadata.gz: 91990c0931cf9a24efc58ea659e78a29080b7cf66acd82677f79a6329e0debeb4483d9dcdaf45731e6bcbf3baa624eedecc09d31249d1911abfadb32fe4bdbc9
-  data.tar.gz: 3a2842b26cee8dfb2f2777220c03224274f37bf21e0412312efdddc2c15ad3aa8f22fc5e351bc10fe974dc756c7fdd6079a389a0a28a5f75dd327365db5289ec
+  metadata.gz: 46ecd9c3584757faec3db79f6ceee686299b597fe6666336858d03820166ce5962d36ce4c36e69808147d96f66eda01865489ea8c24336ee1770917f5b3a3ce3
+  data.tar.gz: a1060b86507afb34f49f26f96f22e9a884e4cc6c828d92ca06162d4e15dad0c4b7b6a55e27100aaded5d5c0e85225633e508f7731e8f098aed94d56f594b48a2

data/README.md

@@ -25,10 +25,10 @@ Trivet is a generic class for organizing a hierarchy.
     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 {#start#} creates a `Trivet::Node` object and assigns it the id "food".
+Lines {#spices#} to {#fruit-end#} use the `node()` method to create child nodes.
 
-Line 20 uses the `to_tree()` method to display the tree as text, which
+Line {#end#} uses the `to_tree()` method to display the tree as text, which
 looks like this:
 
     food
@@ -74,7 +74,32 @@ mike@idocs.com
 
 ## History
 
-| version | date          | notes                                                 |
-|---------|---------------|-------------------------------------------------------|
-| 1.0     | June 18, 2020 | Initial upload.                                       |
-| 1.1     | June 22, 2020 | Consolidated can_have_children? and can_have_child? into allow_child?. |
+<table>
+
+	<tr>
+		<th>version</th>
+		<th>date</th>
+		<th>notes</th>
+	</tr>
+
+	<tr>
+		<td>1.0</td>
+		<td>June 18, 2020</td>
+		<td>Initial upload.</td>
+	</tr>
+
+	<tr>
+		<td>1.1</td>
+		<td>June 22, 2020</td>
+		<td>Consolidated can_have_children? and can_have_child? into allow_child?.</td>
+	</tr>
+
+	<tr>
+		<td>1.2</td>
+		<td>January 3, 2021</td>
+		<td>
+			Added several methods to Trivet::Node: next_sibling, previous_sibling, have_child?, and move_child.
+		</td>
+	</tr>
+
+</table>

data/lib/trivet.rb

@@ -1,4 +1,5 @@
 require 'forwardable'
+require 'lx'
 
 
 #===============================================================================
@@ -10,7 +11,7 @@ require 'forwardable'
 # Trivet::Node to learn about this package.
 module Trivet
 	# Version
-	VERSION = '1.1'
+	VERSION = '1.2'
 	
 	#---------------------------------------------------------------------------
 	# query control constants
@@ -71,7 +72,7 @@ end
 class Trivet::Node
 	# delegate
 	extend Forwardable
-	delegate %w(remove_child) => :@children
+	delegate %w(remove_child have_child?) => :@children
 	
 	
 	#---------------------------------------------------------------------------
@@ -295,17 +296,22 @@ class Trivet::Node
 	# - 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.
 	#
+	# option: use
+	#
+	# If the `use` option is sent, then that object is used as the new node.
 	def node(opts={})
 		# normalize opts
 		if opts.is_a?(String)
 			opts = {'id'=>opts}
+		elsif opts.is_a?(Trivet::Node)
+			opts = {'use'=>opts}
 		end
 		
 		# $tm.hrm
 		idx = opts['index'] || 'last'
 		
 		# create child object
-		new_node = child_class(opts).new()
+		new_node = opts['use'] || child_class(opts).new()
 		
 		# id if sent
 		if opts['id']
@@ -356,12 +362,29 @@ class Trivet::Node
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# add
+	#
+	
+	# A shortcut for adding children of any arbistrary class. Takes zero or more
+	# params, each of which is an object.
+	
+	def add(*objs)
+		objs.each do |obj|
+			@children.push obj
+		end
+	end
+	#
+	# add
+	#---------------------------------------------------------------------------
+	
+	
 	#---------------------------------------------------------------------------
 	# id=
 	#
 	
 	# Sets the id property of the node. If any other node already has that id
-	# then an exception is raised.
+	# then that node loses its id.
 	def id=(new_id)
 		# $tm.hrm
 		
@@ -369,7 +392,8 @@ class Trivet::Node
 		if new_id
 			root.traverse('self'=>true) do |tag|
 				if (tag.id == new_id) and (tag != self)
-					raise 'redundant-id: ' + new_id.to_s
+					# raise 'redundant-id: ' + new_id.to_s
+					tag.id = nil
 				end
 			end
 		end
@@ -767,19 +791,23 @@ class Trivet::Node
 	
 	
 	#---------------------------------------------------------------------------
-	# to_s
+	# to_s, to_debug
 	#
 	
 	# Returns the id if there is one. Otherwise returns Object#to_s.
 	def to_s
-		if @id
-			return @id
-		else
-			return super()
-		end
+		return @id || super()
+	end
+	
+	# Useful to outputting a string that represents the node for the purpose of
+	# debugging. By default, outputs to_s. This method is used in to_tree, so
+	# it's usually a good idea to return a single-line string.
+	def to_debug
+		return to_s
 	end
+	
 	#
-	# to_s
+	# to_s, to_debug
 	#---------------------------------------------------------------------------
 	
 	
@@ -787,13 +815,13 @@ class Trivet::Node
 	# 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.
+	# This method is 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
+		rv = tab() * opts['depth'] + self.to_debug
 		
 		# indent
 		if opts['indent']
@@ -806,8 +834,23 @@ class Trivet::Node
 		
 		# recurse
 		@children.each do |child|
+			# recurse into child node
 			if child.is_a?(Trivet::Node)
 				rv += "\n" + child.to_tree(send_opts)
+				
+			# elsif if there's a custom child_to_tree method
+			elsif respond_to?('child_to_tree')
+				send_opts['tab'] = tab()
+				add = child_to_tree(child, send_opts)
+				
+				if add and add.match(/./mu)
+					rv += "\n" + add
+				end
+			
+			# String
+			elsif child.is_a?(String)
+				rv += "\n" + (tab() * send_opts['depth'] ) + child.lx.collapse
+				
 			end
 		end
 		
@@ -819,6 +862,17 @@ class Trivet::Node
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# tab
+	#
+	def tab
+		return '   '
+	end
+	#
+	# tab
+	#---------------------------------------------------------------------------
+	
+	
 	#---------------------------------------------------------------------------
 	# node_by_id
 	#
@@ -846,6 +900,20 @@ class Trivet::Node
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# allow_child?
+	#
+	
+	# This method is called when a node or other object is added to a node. By
+	# default, always returns true. Override this method to create custom rules.
+	def allow_child?(child)
+		return true
+	end
+	#
+	# allow_child?
+	#---------------------------------------------------------------------------
+	
+	
 	#---------------------------------------------------------------------------
 	# shortcut to create allow_child? that returns false
 	#
@@ -856,9 +924,7 @@ class Trivet::Node
 	#    self.no_children()
 	#
 	def self.no_children()
-		self.child_levels = []
-		
-		self.define_method('allow_child?') do
+		self.define_method('allow_child?') do |child|
 			return false
 		end
 	end
@@ -867,20 +933,6 @@ class Trivet::Node
 	#---------------------------------------------------------------------------
 	
 	
-	#---------------------------------------------------------------------------
-	# allow_child?
-	#
-	
-	# This method is called when a node or other object is added to a node. By
-	# default, always returns true. Override this method to create custom rules.
-	def allow_child?(child)
-		return true
-	end
-	#
-	# allow_child?
-	#---------------------------------------------------------------------------
-	
-	
 	#---------------------------------------------------------------------------
 	# document
 	#
@@ -930,6 +982,82 @@ class Trivet::Node
 	#
 	# depth
 	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# previous_sibling
+	#
+	
+	# Returns the node's previous sibling
+	def previous_sibling
+		# $tm.hrm
+		latest = nil
+		
+		# if parent, search through sibling
+		if parent
+			parent.children.each do |sib|
+				if sib == self
+					return latest
+				else
+					latest = sib
+				end
+			end
+		end
+		
+		# no parent
+		return nil
+	end
+	
+	#
+	# previous_sibling
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# next_sibling
+	#
+	
+	# Returns the node's next sibling.
+	def next_sibling
+		# $tm.hrm
+		found_self = false
+		
+		# if parent, search through siblings
+		if parent
+			parent.children.each do |sib|
+				if sib == self
+					found_self = true
+				elsif found_self
+					return sib
+				end
+			end
+		end
+		
+		# no next sibling
+		return nil
+	end
+	
+	#
+	# next_sibling
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# move_child
+	#
+	
+	# Moves the given object from this node to the given node. Note that the
+	# object being moved doesn't actually have to be a child of this node, but
+	# it will be removed if it is.
+	
+	def move_child(child, tgt)
+		# $tm.hrm
+		@children.remove_child child
+		tgt.add child
+	end
+	#
+	# move_child
+	#---------------------------------------------------------------------------
 end
 #
 # Trivet::Node
@@ -950,7 +1078,7 @@ class Trivet::Childset
 	extend Forwardable
 	
 	delegate %w(
-		[] each each_with_index length include? find_index reverse
+		[] each each_with_index length find_index reverse include?
 		all? at any? empty? reject + - collect cycle) => :@children;
 	#
 	# delegate
@@ -1003,6 +1131,23 @@ class Trivet::Childset
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# include?
+	#
+	# def include?(obj)
+	#	@children.each do |child|
+	#		if child.equal?(obj)
+	#			return true
+	#		end
+	#	end
+	#	
+	#	return false
+	# end
+	#
+	# include?
+	#---------------------------------------------------------------------------
+	
+	
 	#---------------------------------------------------------------------------
 	# methods for adding a child to the array
 	#
@@ -1011,14 +1156,14 @@ class Trivet::Childset
 	# 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
+		return add_child(new_child, 'last', opts)
 	end
 	
 	# Adds a child to the end of the array. Calls Trivet::Node#allow_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
+		return add_child(new_child, 'last', opts)
 	end
 	
 	# Shortcut for append without any options.
@@ -1030,14 +1175,14 @@ class Trivet::Childset
 	# 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
+		return add_child(new_child, 'first', opts)
 	end
 	
 	# Inserts the child at the position indicated by index. Calls Trivet::Node#allow_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
+		return add_child(new_child, index, opts)
 	end
 	#
 	# methods for adding a child to the array
@@ -1051,18 +1196,24 @@ class Trivet::Childset
 	# 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)
+		# opts = {'recurse'=>true}.merge(opts)
 		
 		@children.reject!() do |el|
-			el == child
+			el.equal? child
 		end
 	end
 	
 	# Removes all children.
 	def clear()
+		# explicitly unlink childen
 		@children.clone.each do |child|
-			child.unlink
+			if child.is_a?(Trivet::Node)
+				child.unlink
+			end
 		end
+		
+		# remove all other child objects
+		@children.clear
 	end
 	#
 	# remove_child
@@ -1155,6 +1306,23 @@ class Trivet::Childset
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# have_child?
+	#
+	def have_child?(potential)
+		@children.each_with_index do |child, idx|
+			if child.equal?(potential)
+				return idx
+			end
+		end
+		
+		return false
+	end
+	#
+	# have_child?
+	#---------------------------------------------------------------------------
+	
+	
 	# private
 	private
 	
@@ -1167,18 +1335,20 @@ class Trivet::Childset
 		
 		# check if this parent is allowed to have this child
 		if not @node.allow_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
+			if new_child.respond_to?('to_debug')
+				child_debug = new_child.to_debug
+			elsif new_child.is_a?(String)
+				child_debug = new_child
+			else
+				child_debug = '[unrecognized object]'
+			end
+			
+			raise 'parent-cannot-have-this-child: ' + @node.to_debug + ' / ' + child_debug
 		end
 		
 		# add to children if not already there
-		if dup_ok or (not @children.include?(new_child))
+		# if dup_ok or (not @children.include?(new_child))
+		if (not have_child?(new_child))
 			# add to start of array
 			if index == 'first'
 				@children.unshift new_child
@@ -1241,6 +1411,7 @@ class Trivet::Document
 	def initialize(new_root=nil)
 		# init
 		@root = nil
+		@misc = {}
 		
 		# set new root
 		if new_root
@@ -1263,6 +1434,9 @@ class Trivet::Document
 	# Returns the root node. Returns nil if the document does not have a root.
 	attr_reader :root
 	
+	# A hash of any miscellaneous information you want to attach to the node.
+	attr_reader :misc
+	
 	#
 	# reader
 	#---------------------------------------------------------------------------
@@ -1276,6 +1450,7 @@ class Trivet::Document
 	def root=(new_root)
 		set_root new_root
 	end
+	
 	#
 	# root=
 	#---------------------------------------------------------------------------
@@ -1313,6 +1488,26 @@ class Trivet::Document
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# children
+	#
+	
+	# If there is a root node, returns an array consisting of just the root
+	# node. Else returns an empty array. This method if is a convenience to that
+	# a node can always call its parent's children.
+	def children
+		if @root
+			return [@root]
+		else
+			return []
+		end
+	end
+	
+	#
+	# children
+	#---------------------------------------------------------------------------
+	
+	
 	#---------------------------------------------------------------------------
 	# traverse
 	#
@@ -1348,6 +1543,19 @@ class Trivet::Document
 	#---------------------------------------------------------------------------
 	
 	
+	#---------------------------------------------------------------------------
+	# []
+	#
+	
+	# Shortcut for #node_by_id().
+	
+	def [](id)
+		return node_by_id(id)
+	end
+	#
+	# []
+	#---------------------------------------------------------------------------
+	
 	# include method from querier
 	include Trivet::Querier
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trivet
 version: !ruby/object:Gem::Version
-  version: '1.1'
+  version: '1.2'
 platform: ruby
 authors:
 - Mike O'Sullivan
@@ -9,7 +9,21 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2020-06-18 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '1.1'
 description: Generic class for organizing objects in a hierarchy.
 email: mike@idocs.com
 executables: []