arboretum 0.0.3 → 0.0.4

data/lib/arboretum/doctree.rb

@@ -0,0 +1,1566 @@
+module Arboretum
+  module DocTree
+    module Counters
+
+      class Counter
+        attr_accessor :name, :incrementers, :resetters, :start_value, :gradient, :current_value
+        @@counters = Hash.new{|h, name| h[name] = Counter.new(name)}
+
+        def self.counters
+          @@counters
+        end
+
+        def initialize(name)
+          name = name.to_sym if !name.is_a?(Symbol)
+          @name = name
+          @incrementers = []
+          @resetters = []
+          @start_value = 1
+          @gradient = 1
+
+          @current_value = start_value
+        end
+
+        def reset
+          @current_value = start_value
+        end
+
+        def increment
+          @current_value += gradient
+        end
+      end
+
+      class Incrementer
+        attr_reader :name
+        attr_accessor :value
+
+        def initialize(name)
+          @name = name
+          @value = 0
+          Counter.counters[name].incrementers << self
+        end
+
+        def counter
+          Counter.counters[@name]
+        end
+      end
+
+      class Resetter
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+          Counter.counters[name].resetters << self
+        end
+
+        def counter
+          Counter.counters[@name]
+        end
+      end
+    end # Counters
+
+    module Elements
+      require 'forwardable'
+      require 'securerandom'
+      require_relative 'scandent'
+
+      # Tree is a representation of a tree data structure consisting of elements
+      # A Tree holds only reference to the root Element of the tree
+      # A tree is useful for contextual operations on elements with the root as an ancestor
+      class Tree
+        include Enumerable
+
+        attr_accessor :root
+
+        def initialize(root=nil)
+          @root = root    # Element
+          @listeners = [] # Array of GroupListeners
+        end
+
+        # Redefine the `each` method to iterate through all elements in the tree in depth-first order
+        def each(element=self.root)
+          yield element
+          element.children.each {|child| self.each(child) {|c| yield c}} unless element.nil?
+        end
+
+        def each_with_level(element=self.root, level=0)
+          yield [element, level]
+          level += 1 unless element.is_a?(DocRootElement)
+          element.children.each {|child| self.each_with_level(child, level) {|c,l| yield [c, l]}} unless element.nil?
+        end
+
+        # Returns an array with all elements in the subtree of the root in depth-first order
+        def get_DF_elements
+          Array.new.tap {|list| self.each {|element| list << element}}
+        end
+
+        # Find any and all elements in the tree that match a given ScandentRule string
+        def scan(rule_string)
+          selected = []
+          rule = Arboretum::Scandent::Parser.parse_rule_string(rule_string, :PATH_LISTENER)
+          self.each do |element|
+            selected << element if rule.valid_on?(element)
+            yield element if rule.valid_on?(element) and block_given?
+          end
+          puts "--Warning: Rule #{rule_string} did not match any elements!--" if selected.empty?
+          ElementGroup.new(selected)
+        end
+
+        def listen(rule_string, &block)
+          listener = GroupListener.new(rule_string, block)
+          @listeners << listener
+          listener
+        end
+
+        def apply_listeners
+          self.each do |element|
+            @listeners.each do |listener|
+              if listener.rule.valid_on?(element)
+                listener << element
+                listener.exe_block.call(element) if !listener.exe_block.nil?
+              end
+            end
+          end
+          @listeners.each do |listener|
+            puts "--Warning: Rule #{listener.rule} did not match any elements!--" if listener.empty?
+          end
+          @listeners = []
+        end
+
+        def apply_counters
+          self.each do |element|
+            element.resetters.each {|name, r| r.counter.reset}
+            element.incrementers.each {|name, i| i.value = i.counter.current_value; i.counter.increment}
+          end
+        end
+
+        def to_s(root=true, pretty=true)
+          tree_string = (root ? "<<Tree: \n" : "")
+          if not self.root.nil?
+            tree_string << (root ? self.root.to_s + (pretty ? "\n" : "") : "")
+            self.root.children.each {|child| tree_string << self.r_to_s(child, 1, pretty)}
+          end
+          tree_string << (root ? ">>" : "")
+        end
+
+        def dump_markup(style=:pretty, type=:xml)
+          # The string containing all the markup
+          tree_string = ""
+          # Array of possible whitespace chars
+          whitespace_chars = [" ", "\t", "\n"]
+          # Whether there has been whitespace since the last text node
+          whitespace_trailing = true
+          # Whether the whitespace since the last text node has been honored
+          whitespace_honored = true
+          # To track which elements must be closed explicitly
+          open_elements = Array.new
+          if style.eql? :pretty
+            self.each_with_level do |element, level|
+              # Close elements that should close before the current element
+              until open_elements.empty? or level > open_elements.last[1]
+                # The element to be closed and its respective indentation level and whether it was a text-only element
+                closed_element, closed_level, text_only = open_elements.pop
+                closed_indent = "  " * closed_level
+
+                # Whether the tail text of an element begins with whitespace e.g. `<div></div> I am tail text for the div` => true
+                tail_leading_space = (closed_element.sibling_next.is_a?(TextElement) and
+                                      whitespace_chars.include?(closed_element.sibling_next.text[0]))
+                # Whether element can break before the closing tag (to preserve whitespace):
+                #  Element can break and still maintain whitespace if there has been whitespace since the
+                #  last text element and the tail text of the current element
+                #  Additionally, element can break if its instance variable :break_within is true
+                can_break_after = (whitespace_trailing or closed_element.break_within or tail_leading_space)
+
+                # Add a newline if it preserve whitespace and is not redundant and the element was not fit into a single line
+                tree_string << "\n" if can_break_after and !tree_string[-1].eql? "\n" and !text_only
+                # Add the indentation for this level if a newline occurred
+                tree_string << closed_indent if tree_string[-1].eql? "\n"
+                # If we added whitespace, then we have honored any whitespace in the document
+                whitespace_honored = true if whitespace_chars.include?(tree_string[-1])
+                # If we added whitespace, then the next element should be safe to break as well
+                whitespace_trailing = true if can_break_after
+                # Dump the closing tag of the element
+                tree_string << closed_element.dump_markup_close
+              end
+              # Determine the indentation level for the current element
+              indent = "  " * level
+
+              # Handle element depending on its type
+              if element.is_a? TaggedElement
+                # Whether the element has any non-text children (text-only elements will be fit into a single line)
+                text_only = element.children.select{|c| !c.is_a?(TextElement)}.length == 0
+                # Whether element can break before the opening tag (to preserve whitespace):
+                #   Element can break and still maintain whitespace if there has been whitespace since the
+                #   last text element and the body text of the current element
+                #   Additionally, element can break if its instance variable :break_within is true
+                can_break_before = (whitespace_trailing or element.break_within)
+
+                # Lookahead to determine if whitespace is in between element and next TextElement
+                # e.g. `<div> I am body text for the div <a>I am not</a></div>` => true
+                # Only takes place if the less expensive options didn't pan out
+                unless can_break_before
+                  current = element
+                  until current.nil? or current.is_a?(TextElement) or can_break_before
+                    current = current.children.first
+                    can_break_before = true if current.is_a?(TaggedElement) and current.break_within
+                  end
+                  can_break_before = true if current.is_a?(TextElement) and whitespace_chars.include?(current.text[0])
+                end
+
+                # Add a newline if it preserves whitespace and is not redundant
+                tree_string << "\n" if can_break_before and !tree_string[-1].eql?("\n")
+                # Add the indentation for this level if a newline occurs before the opening tag
+                tree_string << indent if tree_string[-1].eql? "\n"
+                # If we added whitespace, then we have honored any whitespace in the document
+                whitespace_honored = true if whitespace_chars.include?(tree_string[-1])
+                # If we added whitespace, then the next element should be safe to break as well
+                whitespace_trailing = true if can_break_before
+                # Dump the opening tag of the element
+                tree_string << element.dump_markup(type)
+                # Add another newline if it preserves whitespace and this elements has a non-text element
+                tree_string << "\n" if can_break_before and !text_only
+                # Mark the element for closing if it is paired
+                open_elements << [element, level, text_only] if element.paired?
+              elsif element.is_a? TextElement
+                # Whether this element has any non-text siblings (and will not be fit into a single line)
+                non_text_siblings = (element.preceding_siblings + element.following_siblings).select{|s| !s.is_a?(TextElement)}.length > 0
+                text_prev = element.sibling_prev.is_a? TextElement
+                text_next = element.sibling_next.is_a? TextElement
+
+                # The text of the element, to be modified before adding to the markup string
+                element_text = element.dump_markup(type)
+
+                element_trailing_space = whitespace_chars.include?(element_text[-1])
+                element_preceding_space = whitespace_chars.include?(element_text[0])
+                # Determine if the preceding space in the element is redundant or not needed
+                can_remove_preceding = (element_preceding_space and !text_prev and whitespace_trailing)
+
+                tree_string << "\n" if can_remove_preceding and !tree_string[-1].eql?("\n") and non_text_siblings
+                tree_string << indent if tree_string[-1].eql?("\n") and !element_text.strip.empty?
+                # If we added whitespace, then we have honored any whitespace in the document
+                whitespace_honored = true if whitespace_chars.include?(tree_string[-1])
+
+                # Tack on some whitespace or mark leading whitespace as not redundant if whitespace hasn't been honored yet
+                if whitespace_trailing and !whitespace_honored
+                  if can_remove_preceding
+                    can_remove_preceding = false
+                  else
+                    element_text = " " << element_text
+                  end
+                end
+
+                # Strip redundant or unwanted whitespace
+                element_text[0] = "" if (can_remove_preceding and whitespace_chars.include?(tree_string[-1])) or
+                                        (can_remove_preceding and !non_text_siblings)
+                element_text[-1] = non_text_siblings ? "\n" : "" if element_trailing_space and !text_next and !element_text.strip.empty?
+
+                # Determine whether whitespace is trailing and if that trailing whitespace is honored by the end of the text node
+                whitespace_trailing = element_trailing_space
+                whitespace_honored = !(element_trailing_space and !whitespace_chars.include?(element_text[-1]))
+
+                tree_string << element_text unless tree_string[-1].eql?("\n") and element_text.strip.empty?
+              elsif element.is_a? DocRootElement
+                # Do nothing
+              else
+                # Just treat most elements like TaggedElements except for dumping a closing tag
+                #####
+                # Whether the element has any non-text children (text-only elements will be fit into a single line)
+                text_only = element.children.select{|c| !c.is_a?(TextElement)}.length == 0
+                # Whether element can break before the opening tag (to preserve whitespace):
+                #   Element can break and still maintain whitespace if there has been whitespace since the
+                #   last text element and the body text of the current element
+                #   Additionally, element can break if its instance variable :break_within is true
+                can_break_before = (whitespace_trailing or element.break_within)
+
+                # Lookahead to determine if whitespace is in between element and next TextElement
+                # e.g. `<div> I am body text for the div <a>I am not</a></div>` => true
+                # Only takes place if the less expensive options didn't pan out
+                unless can_break_before
+                  current = element
+                  until current.nil? or current.is_a?(TextElement) or can_break_before
+                    current = current.children.first
+                    can_break_before = true if current.is_a?(TaggedElement) and current.break_within
+                  end
+                  can_break_before = true if current.is_a?(TextElement) and whitespace_chars.include?(current.text[0])
+                end
+
+                # Add a newline if it preserves whitespace and is not redundant
+                tree_string << "\n" if can_break_before and !tree_string[-1].eql?("\n")
+                # Add the indentation for this level if a newline occurs before the opening tag
+                tree_string << indent if tree_string[-1].eql? "\n"
+                # If we added whitespace, then we have honored any whitespace in the document
+                whitespace_honored = true if whitespace_chars.include?(tree_string[-1])
+                # If we added whitespace, then the next element should be safe to break as well
+                whitespace_trailing = true if can_break_before
+                # Dump the opening tag of the element
+                tree_string << element.dump_markup(type)
+                # Add another newline if it preserves whitespace and this elements has a non-text element
+                tree_string << "\n" if can_break_before and !text_only
+              end
+            end
+            # Close remaining
+            until open_elements.empty?
+              # The element to be closed and its respective indentation level and whether it was a text-only element
+              closed_element, closed_level, text_only = open_elements.pop
+              closed_indent = "  " * closed_level
+
+              # Whether the tail text of an element begins with whitespace e.g. `<div></div> I am tail text for the div` => true
+              tail_leading_space = (closed_element.sibling_next.is_a?(TextElement) and
+                                    whitespace_chars.include?(closed_element.sibling_next.text[0]))
+              # Whether element can break before the closing tag (to preserve whitespace):
+              #  Element can break and still maintain whitespace if there has been whitespace since the
+              #  last text element and the tail text of the current element
+              #  Additionally, element can break if its instance variable :break_within is true
+              can_break_after = (whitespace_trailing or closed_element.break_within or tail_leading_space)
+
+              # Add a newline if it preserve whitespace and is not redundant and the element was not fit into a single line
+              tree_string << "\n" if can_break_after and !tree_string[-1].eql? "\n" and !text_only
+              # Add the indentation for this level if a newline occurred
+              tree_string << closed_indent if tree_string[-1].eql? "\n"
+              # If we added whitespace, then we have honored any whitespace in the document
+              whitespace_honored = true if whitespace_chars.include?(tree_string[-1])
+              # If we added whitespace, then the next element should be safe to break as well
+              whitespace_trailing = true if can_break_after
+              # Dump the closing tag of the element
+              tree_string << closed_element.dump_markup_close
+            end
+          elsif style.eql? :compact
+            self.each_with_level do |element, level|
+              until open_elements.empty? or level > open_elements.last[1]
+                closed_element, closed_level = open_elements.pop
+                tree_string << " " if closed_element.break_within
+                whitespace_trailing = true if whitespace_chars.include?(tree_string[-1])
+                tree_string << closed_element.dump_markup_close
+              end
+              if element.is_a? TaggedElement
+                tree_string << element.dump_markup(type)
+                tree_string << " " if element.break_within
+                whitespace_trailing = true if whitespace_chars.include?(tree_string[-1])
+                open_elements << [element, level] if element.paired?
+              elsif element.is_a? TextElement
+                tree_string << element.dump_markup(type) unless whitespace_chars.include?(tree_string[-1]) and element.text.strip.empty?
+                whitespace_trailing = whitespace_chars.include?(tree_string[-1])
+              elsif element.is_a? DocRootElement
+                # Do nothing
+              else
+                tree_string << element.dump_markup(type)
+                tree_string << " " if element.break_within
+                whitespace_trailing = true if whitespace_chars.include?(tree_string[-1])
+              end
+            end
+          # Unknown print style
+          else
+            puts "Warning: Unknown print style. Using `:pretty`..."
+            tree_string = dump_markup(:pretty, type)
+          end
+          (whitespace_chars.include?(tree_string[0])) ? tree_string[1..-1] : tree_string
+        end
+
+        protected
+          def r_to_s(element, level, pretty)
+            element_string = (pretty ? " |"*level : "") + element.to_s + (pretty ? "\n" : "")
+            element.children.each do |child|
+              element_string << self.r_to_s(child, level + 1, pretty)
+            end
+            element_string
+          end
+
+      end
+
+      module Contextualized
+        # Swap locations of this ContextualGroup with another ContextualGroup
+        def swap(other)
+          puts "Warning: Can't swap with nil" if other.nil?
+          unless other.nil?
+            # Temp
+            other_parent = other.parent
+            other_index = other.index_in_parent
+
+            other.graft_onto(self.parent, self.index_in_parent)
+            self.graft_onto(other_parent, other_index)
+          end
+        end
+        # Wrap this ContextualGroup in an Element, with the wrapping Element taking this ContextualGroup's original place in the tree
+        # If the wrapping Element already exitst, then this ContextualGroup is pushed to the given index in the other's
+        # children (but also idk why would you need to do that?)
+        def wrap(element, index=-1)
+          element = Element.create(element) if element.is_a?(Hash)
+          element.graft_onto(self.parent, self.index_in_parent)
+          self.graft_onto(element, index)
+          element
+        end
+      end
+
+
+      module Loggable
+        def log(*method_names)
+          method_names.each do |name|
+            method = instance_method(name)
+            define_method(name) do |*args, &block|
+              self.history << [name, args, caller]
+              method.bind(self).(*args, &block)
+            end
+          end
+        end
+        def log_string
+          lines = ""
+          self.history.each {|h| lines << h.inspect << "\n"}
+          lines
+        end
+      end
+
+      # Generic element class
+      # Meant to be inherited rather than used directly
+      # All elements hold reference to a parent, children, and their left and right siblings
+      class Element
+        extend Forwardable
+        def_delegators :listing, :each
+        extend Loggable
+        include Loggable
+        include Enumerable
+        include Contextualized
+
+        protected
+        attr_writer :parent, :children, :sibling_prev, :sibling_next, :incrementers, :resetters, :library
+          
+        public
+        attr_reader :parent, :children, :sibling_prev, :sibling_next, :incrementers, :resetters, :library
+        attr_accessor :break_within, :history
+
+        # Class method to stitch together two elements as siblings, ordered
+        # Will stitch values even if one or both is nil
+        # When used in isolation, can cause a mismatch in the tree (because parent is not updated)
+        def self.stitch!(prev_element, next_element)
+          prev_element.set_sibling_next!(next_element) unless prev_element.nil?
+          next_element.set_sibling_prev!(prev_element) unless next_element.nil?
+        end
+
+        # Create a custom element with a given namespace, tag, attributes, and text child
+        # If only text is given, a TextElement will be created rather than a tagged element
+        # If no tag is given, but attributes or namespace are given, a `div` element will be used by default
+        def self.create(namespace: nil, tag: nil, attrs: {}, text: nil)
+          tag = :div if tag.nil? and (!namespace.nil? or !attrs.empty? or text.nil?)
+          created_element = nil
+          if tag.nil?
+            raise TypeError.new("Text must be a String or TextElement") if !(text.is_a?(String) or text.is_a?(TextElement))
+            created_element = (text.is_a?(String)) ? TextElement.new(text) : text
+          else
+            tag = tag.to_sym if !tag.is_a?(Symbol)
+            raise TypeError.new("Tag must be a Symbol or String") if !tag.is_a?(Symbol)
+            namespace = namespace.to_sym if namespace.kind_of?(String) and !namespace.nil?
+            raise TypeError.new("Namespace must be a Symbol or String") if !namespace.is_a?(Symbol) and !namespace.nil?
+            sanitary_attrs = {}
+            attrs.each do |key, val|
+              key = key.to_sym if !key.is_a?(Symbol)
+              raise TypeError.new("Attribute name must be a Symbol or String") if !key.is_a?(Symbol)
+              val = val.split if val.is_a?(String)
+              # Ensure value is arrays of strings
+              raise TypeError.new("Attribute value must be a String or Array of Strings") if !val.is_a?(Array)
+              val.each{|sub_val| raise TypeError.new("Each attribute value in an array must be a String") if !sub_val.is_a?(String)}
+              sanitary_attrs[key] = val
+            end
+            created_element = TaggedElement.new(namespace, tag, sanitary_attrs)
+            if !text.nil?
+              raise TypeError.new("Text must be a string or TextElement") if !(text.is_a?(String) or text.is_a?(TextElement))
+              if text.is_a?(String)
+                text_child = TextElement.new(text)
+                created_element.append_child(text_child)
+              else
+                created_element.append_child(text)
+              end
+            end
+          end
+          created_element.break_within = true if !created_element.is_a?(TextElement)
+          yield created_element if block_given?
+          created_element
+        end
+        singleton_class.send(:alias_method, :make, :create)
+        singleton_class.send(:alias_method, :grow, :create)
+
+        def initialize
+          # Family of elements
+          @parent = nil           # Element
+          @sibling_prev = nil     # Element
+          @sibling_next = nil     # Element
+          @children = []          # Array of Elements
+
+          # Properties, references, and counters
+          @break_within = false     # Boolean
+          @incrementers = Hash.new  # Hash with key: Symbol (name), value: Incrementer
+          @resetters = Hash.new     # Hash with key: Symbol (name), value: Resetter
+          @library = Hash.new       # Hash with key: Symbol, value: Element/ElementGroup
+          @history = Array.new      # Array of arrays of form [method_called, arguments, callers]
+        end
+
+        # Add an element as this element's last child
+        def append_child(*elements)
+          placed = Array.new
+          elements.each do |element|
+            if !element.nil?
+              element = TextElement.new(element) if element.is_a?(String)
+              element = Element.create(element) if element.is_a?(Hash)
+              element.graft_last_onto(self)
+              element.listing.each do |member|
+                yield member if block_given?
+                placed << member
+              end
+            end
+          end
+          return nil if placed.empty?
+          return placed.first if placed.length == 1
+          return ElementGroup.new(placed)
+        end
+        alias_method :push, :append_child
+        alias_method :<<, :append_child
+
+        # Add an element as this element's first child
+        def prepend_child(*elements)
+          placed = Array.new
+          elements.each do |element|
+            if !element.nil?
+              element = TextElement.new(element) if element.is_a?(String)
+              element = Element.create(element) if element.is_a?(Hash)
+              element.graft_first_onto(self)
+              element.listing.each do |member|
+                yield member if block_given?
+                placed << member
+              end
+            end
+          end
+          return nil if placed.empty?
+          return placed.first if placed.length == 1
+          return ElementGroup.new(placed)
+        end
+        alias_method :place, :prepend_child
+        alias_method :unshift, :prepend_child
+
+        # Insert an element as a child at a specified index it this element's children
+        def insert_child(*elements)
+          placed = Array.new
+          elements.each do |element|
+            if !element.nil?
+              element = TextElement.new(element) if element.is_a?(String)
+              element = Element.create(element) if element.is_a?(Hash)
+              element.graft_onto(self, index)
+              element.listing.each do |member|
+                yield member if block_given?
+                placed << member
+              end
+            end
+          end
+          return nil if placed.empty?
+          return placed.first if placed.length == 1
+          return ElementGroup.new(placed)
+        end
+
+        def append_sibling(*elements)
+          placed = Array.new
+          elements.each do |element|
+            if !element.nil?
+              element = TextElement.new(element) if element.is_a?(String)
+              element = Element.create(element) if element.is_a?(Hash)
+              element.graft_onto(self.parent, self.index_in_parent+1)
+              element.listing.each do |member|
+                yield member if block_given?
+                placed << member
+              end
+            end
+          end
+          return nil if placed.empty?
+          return placed.first if placed.length == 1
+          return ElementGroup.new(placed)
+        end
+
+        def prepend_sibling(*elements)
+          placed = Array.new
+          elements.each do |element|
+            if !element.nil?
+              element = TextElement.new(element) if element.is_a?(String)
+              element = Element.create(element) if element.is_a?(Hash)
+              element.graft_onto(self.parent, self.index_in_parent)
+              element.listing.each do |member|
+                yield member if block_given?
+                placed << member
+              end
+            end
+          end
+          return nil if placed.empty?
+          return placed.first if placed.length == 1
+          return ElementGroup.new(placed)
+        end
+
+        def overwrite!(args)
+          replacement = Element.create(args)
+          puts "Warning: Overwriting this element will delete its children" if self.has_children? and !replacement.can_have_children?
+          replacement.graft_onto(self.parent, self.index_in_parent)
+          self.content.graft_onto(replacement)
+          replacement.break_within = self.break_within
+          replacement.counters = self.counters
+          replacement.resetters = self.resetters
+          replacement.library = self.library
+          self.detach
+          replacement
+        end
+
+        def index_in_parent
+          self.parent.children.index(self)
+        end
+
+        # Returns all text elements in this element's subtree
+        # Can be very expensive on large subtrees/documents, as it performs a full transversal of the subtree
+        def text_elements(text_children=[])
+          if self.is_a? TextElement
+            text_children << self
+          elsif self.is_a? TaggedElement or self.is_a? DocRootElement
+            @children.each {|child| child.text_elements(text_children)}
+          end
+          text_children
+        end
+
+        # Returns a string comprised of all text in this element's subtree
+        # Can be very expensive on large subtrees/documents, as it performs a full transversal of the subtree
+        def text_string(full_string='')
+          if self.is_a? TextElement
+            full_string << self.text
+          elsif self.is_a? TaggedElement or self.is_a? DocRootElement
+            full_string << ' ' if self.break_within
+            @children.each {|child| child.text_string(full_string)}
+            full_string << ' ' if self.break_within
+          end
+          full_string
+        end
+
+        # Special method to get an elements children as an AdjacentElementGroup
+        def content
+          group = AdjacentElementGroup.new
+          group.base(@children[0]) if not @children.empty?
+          group.fill
+        end
+        alias_method :contents, :content
+
+        # Add an counter incrementer to this element
+        def count(counter_name)
+          counter_name = counter_name.to_sym if !counter_name.is_a?(Symbol)
+          incrementers[counter_name] = Counters::Incrementer.new(counter_name)
+        end
+
+        # Get a CounterElement associated with the incrementer of this element of the given name
+        def counter(counter_name)
+          counter_name = counter_name.to_sym if !counter_name.is_a?(Symbol)
+          CounterElement.new(incrementers[counter_name])
+        end
+
+        # Add a counter resetter to this element
+        def reset(counter_name)
+          counter_name = counter_name.to_sym if !counter_name.is_a?(Symbol)
+          resetters[counter_name] = Counters::Resetter.new(counter_name)
+        end
+
+        # Add an element to a category in this element's library
+        def lib_add(other, category)
+          raise TypeError.new("Cannot create a record for a non-element") if !other.is_a?(Element)
+          if @library.has_key?(category)
+            record = @library[category]
+            if record.is_a?(Element)
+              @library[category] = ElementGroup.new([record, other])
+            else record.is_a?(ElementGroup)
+              record << other
+            end
+          else
+            @library[category] = other
+          end
+
+        end
+        alias_method :allude, :lib_add
+        alias_method :cite, :lib_add
+
+        # Get record from the given category in this element's library
+        def lib_get(category)
+          @library[category]
+        end
+        alias_method :[], :lib_get
+        alias_method :record, :lib_get
+
+        # Provides a listing/array containing the element
+        def listing
+          [self]
+        end
+
+        # General element deep copy method
+        def copy
+          element_copy = Element.new
+          element_copy.set_children!(@children.map {|child| child.copy})
+          element_copy
+        end
+
+        # Detach from current parent/siblings
+        def detach
+          Element.stitch!(@sibling_prev, @sibling_next)
+          @parent.children.delete(self) unless @parent.nil?
+          @parent, @sibling_prev, @sibling_next = nil
+        end
+        alias_method :prune, :detach
+        alias_method :delete, :detach
+
+        # Graft onto another element of the tree at any index of its children
+        # By default, it will graft as the last element of the other element's children
+        def graft_onto(graft_parent, index=-1)
+          # If index to small or large, graft to edges of graft_parent children
+          if index.abs > graft_parent.children.length
+            index = graft_parent.children.length * (index > 1 ? 1 : 0)
+          end
+          if index == graft_parent.children.length or index == -1
+            self.graft_last_onto(graft_parent)
+          elsif index == 0
+            self.graft_first_onto(graft_parent)
+          else
+            # Detach from current context
+            self.detach
+
+            # Update context
+            @parent = graft_parent
+
+            previous_child = graft_parent.children[index-1]
+            Element.stitch!(previous_child, self)
+
+            next_child = graft_parent.children[index]
+            Element.stitch!(self, next_child)
+
+            # Graft group at index
+            graft_parent.children.insert(index, self)
+          end
+        end
+
+        # Graft onto another element of the tree as the first child
+        def graft_first_onto(graft_parent)
+          # Detach from current context
+          self.detach
+
+          # Update context
+          @parent = graft_parent
+
+          next_child = graft_parent.children[0]
+          Element.stitch!(nil, self)
+          Element.stitch!(self, next_child)
+
+          # Insert graft group at the beginning of parent children
+          graft_parent.children.insert(0, self)
+        end
+
+        # Graft onto another element of the tree as the last child
+        def graft_last_onto(graft_parent)
+          # Detach from current context
+          self.detach
+
+          # Update context
+          @parent = graft_parent
+
+          previous_child = graft_parent.children[-1]
+          Element.stitch!(previous_child, self)
+          Element.stitch!(self, nil)
+
+          # Push graft group onto parent children
+          graft_parent.children.push(self)
+        end
+
+        # Unwrap the children of this Element, deleting it, and it's children taking its original place in the tree
+        def unwrap_children
+          unwrapped_elements = self.content
+          unwrapped_elements.graft_onto(self.parent, self.index_in_parent)
+          self.detach
+          unwrapped_elements
+        end
+
+        # Get list of all of this element's preceding siblings
+        def preceding_siblings
+          sibling_list = []
+          current = self
+          while not current.sibling_prev.nil?
+            sibling_list << current.sibling_prev
+            current = current.sibling_prev
+          end
+          sibling_list = sibling_list.reverse
+          sibling_list.each {|sibling| yield sibling if block_given?}
+          ElementGroup.new(sibling_list)
+        end
+
+        # Get list of all of this element's preceding siblings in reversed depth-first order
+        # Used for slightly speedier and practical searching
+        def preceding_siblings_reverse
+          sibling_list = []
+          current = self
+          while not current.sibling_prev.nil?
+            yield current.sibling_prev if block_given?
+            sibling_list << current.sibling_prev
+            current = current.sibling_prev
+          end
+          ElementGroup.new(sibling_list)
+        end
+
+        # Get list of all of this element's following siblings in depth-first order
+        def following_siblings
+          sibling_list = []
+          current = self
+          while not current.sibling_next.nil?
+            yield current.sibling_next if block_given?
+            sibling_list << current.sibling_next
+            current = current.sibling_next
+          end
+          ElementGroup.new(sibling_list)
+        end
+
+        # Get list of all this element's ancesotrs in depth-first order
+        def ancestors
+          parent_list = []
+          current = self
+          while not current.parent.nil?
+            parent_list << current.parent
+            current = current.parent
+          end
+          parent_list = parent_list.reverse
+          parent_list.each {|parent| yield parent if block_given?}
+          ElementGroup.new(parent_list)
+        end
+
+        # Get list of all of this element's ancestors in reversed depth-first order
+        # Used for slightly speedier and practical searching
+        def ancestors_reverse
+          parent_list = []
+          current = self
+          while not current.parent.nil?
+            yield current.parent if block_given?
+            parent_list << current.parent
+            current = current.parent
+          end
+          ElementGroup.new(parent_list)
+        end
+
+        # Get list of all this element's descendants in depth-first order
+        def descendants(child_list=[])
+          self.children.each do |child|
+            yield child if block_given?
+            child_list << child
+            child.descendants(child_list)
+          end
+          ElementGroup.new(child_list)
+        end
+
+        # Finds elements in relation to this one that fit a ScandentRule string
+        def find(rule_string)
+          rule = Arboretum::Scandent::Parser.parse_rule_string(rule_string, :PATH_LOCATOR)
+          selected = rule.locate(self) {|found_element| yield found_element if block_given?}
+          puts "--Warning: Rule #{rule} did not match any elements!--" if selected.empty?
+          ElementGroup.new(selected)
+        end
+        alias_method :locate, :find
+
+        # Finds up to `n` elements in relation to this one that fit a ScandentRule string
+        def find_first_n(rule_string, limit)
+          if limit.zero?
+            puts "--Warning: Rule #{rule} was given limit '0'. Returning nil...--" if selected.empty?
+            return nil
+          end
+          selected = []
+          rule = Arboretum::Scandent::Parser.parse_rule_string(rule_string, :PATH_LOCATOR)
+          rule.locate(self) do |found_element|
+            return ElementGroup.new(selected) if selected.length >= limit
+            yield found_element if block_given?
+            selected << found_element
+          end
+          puts "--Warning: Rule #{rule} did not match any elements!--" if selected.empty?
+          ElementGroup.new(selected)
+        end
+        alias_method :locate_first_n, :find_first_n
+
+        # Find the first element in relation to this one that fits a ScandentRule string
+        def find_first(rule_string)
+          self.find_first_n(rule_string, 1) {|found_element| yield found_element if block_given?}.first
+        end
+        alias_method :locate_first, :find_first
+
+        def matches_rule?(rule_string)
+          rule = Arboretum::Scandent::Parser.parse_rule_string(rule_string, :PATH_LISTENER)
+          rule.valid_on?(self)
+        end
+
+        def has_children?
+          !@children.empty?
+        end
+
+        def can_have_children?
+          false
+        end
+
+        # Does nothing but set sibling_next of this element
+        # If used in isolation, will cause a sibling mismatch in the tree
+        def set_sibling_next!(other)
+          @sibling_next = other
+          self
+        end
+
+        # Does nothing but set sibling_prev of this element
+        # If used in isolation, will cause a sibling mismatch in the tree
+        def set_sibling_prev!(other)
+          @sibling_prev = other
+          self
+        end
+
+        # Does nothing but set parent of this element
+        # If used in isolation, will cause a parent <=> child mismatch in the tree
+        def set_parent!(other)
+          @parent = other
+          self
+        end
+
+        # Does nothing but set children of this element
+        # If used in isolation, will cause a parent <=> child mismatch in the tree
+        # Should only be used for when set operations must be performed on element children
+        def set_children!(other_arr)
+          @children = other_arr
+          self
+        end
+
+        def to_tree
+          Tree.new(self)
+        end
+
+        def to_s
+          "<Generic_Element>"
+        end
+
+        # Temporary fix to prevent inspect from exploding due to child references
+        # Ideally will provide detailed state information rather than string output
+        def inspect
+          self.to_s
+        end
+
+      end
+
+      # Special type of element to represent the root element of a document
+      # A DocRootElement has no output but simply acts as a wrapper for the top level elements of an imported document
+      class DocRootElement < Element
+        def initialize
+          super()
+        end
+
+        def can_have_children?
+          true
+        end
+
+        # DocRootElement deep copy method
+        def copy
+          element_copy = DocRootElement.new
+          element_copy.set_children!(@children.map {|child| child.copy})
+          element_copy
+        end
+
+        def to_s
+          "<Root_Element>"
+        end
+
+      end
+
+      # A tagged element of a doctree
+      # Only TaggedElements have tags (duh!) and attributes, and TaggedElements hold no direct reference to text
+      # Ex: Both <p></p> or <br /> are considered tagged elements with no children
+      class TaggedElement < Element
+        @@unpaired_tags = [:'DOCTYPE', :'!DOCTYPE', :'area', :'base', :'br', :'col', :'command', :'embed', :'hr', :'img',
+                          :'input', :'keygen', :'link', :'meta', :'param', :'source', :'track', :'wbr']
+        @@need_valid_xml = true
+
+        attr_accessor :namespace, :tag, :attrs
+
+        def initialize(namespace=nil, tag=nil, attrs={})
+          super()
+
+          # Element tag and attributes
+          @namespace = namespace  # Symbol
+          @tag = tag              # Symbol
+          @attrs = attrs          # Hash with key: Symbol, String: Array of Strings
+        end
+
+        def self.paired?(tag)
+          !@@unpaired_tags.include?(tag)
+        end
+
+        # TaggedElement deep copy method
+        def copy
+          element_copy = TaggedElement.new(@namespace, @tag, @attrs.clone)
+          element_copy.set_children!(@children.map {|child| child.copy})
+          element_copy
+        end
+
+        # Returns the id of this element, or an auto-assigned one if none exists
+        def ref
+          if !self.has_attr?(:id) or self.attr_value_str(:id).nil?
+            auto_id = "auto_#{SecureRandom.uuid}"
+            self.attrs[:id] = [auto_id]
+            auto_id
+          else
+            self.attrs[:id].join.gsub(' ', '')
+          end
+        end
+
+        def href
+          "#" << self.ref
+        end
+
+        # Returns the string value for an attribute of the given name
+        def attr_value_str(attr_name)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          return nil if !self.has_attr?(attr_name)
+          return self.attrs[attr_name].join(' ')
+        end
+
+        def del_attr(attr_name)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          self.attrs.delete(attr_name)
+        end
+
+        def set_attr_value(attr_name, attr_value)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          attr_value = attr_value.split if attr_value.is_a?(String)
+
+          # Ensure value is arrays of strings
+          raise TypeError.new("Attribute value must be a String or Array of Strings") if !attr_value.is_a?(Array)
+          attr_value.each{|sub_val| raise TypeError.new("Each attribute value in an array must be a String") if !sub_val.is_a?(String)}
+
+          self.attrs[attr_name] = attr_value
+        end
+
+        def del_attr_value(attr_name, attr_value)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          attr_value = attr_value.split if attr_value.is_a?(String)
+
+          # Ensure value is arrays of strings
+          raise TypeError.new("Attribute value must be a String or Array of Strings") if !attr_value.is_a?(Array)
+          attr_value.each{|sub_val| raise TypeError.new("Each attribute value in an array must be a String") if !sub_val.is_a?(String)}
+
+          self.attrs[attr_name].delete_if {|sub_val| attr_value.include?(sub_val)}
+        end
+
+        def add_attr_value(attr_name, attr_value)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          attr_value = attr_value.split if attr_value.is_a?(String)
+
+          # Ensure value is arrays of strings
+          raise TypeError.new("Attribute value must be a String or Array of Strings") if !attr_value.is_a?(Array)
+          attr_value.each{|sub_val| raise TypeError.new("Each attribute value in an array must be a String") if !sub_val.is_a?(String)}
+          if self.has_attr?(attr_name)
+            self.attrs[attr_name] += attr_value
+          else
+            self.attrs[attr_name] = attr_value
+          end
+        end
+
+        def set_tag(new_tag)
+          new_tag = new_tag.to_sym if !new_tag.is_a?(Symbol)
+          @tag = new_tag
+        end
+
+        def set_namespace(new_ns)
+          new_ns = new_tag.to_sym if !new_tag.is_a?(Symbol)
+          @namespace = new_ns
+        end
+
+        def del_namespace
+          @namespace = nil
+        end
+
+        # Returns whether or not the element is a paired element
+        def paired?
+          not @@unpaired_tags.include? self.tag
+        end
+
+        def has_attr?(attr_name)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          self.attrs.has_key?(attr_name)
+        end
+
+        def contains_attr_val?(attr_name, attr_value)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          self.has_attr?(attr_name) and self.attrs[attr_name].include?(attr_value)
+        end
+
+        def equals_attr_val?(attr_name, attr_value)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          self.has_attr?(attr_name) and (self.attrs[attr_name]-attr_value).empty?
+        end
+
+        def matches_attr_val?(attr_name, attr_regex)
+          attr_name = attr_name.to_sym if !attr_name.is_a?(Symbol)
+          self.has_attr?(attr_name) and !self.attrs[attr_name].grep(attr_regex).empty?
+        end
+
+        def namespaced_tag
+          self.namespace.nil? ? "#{self.tag}" : "#{self.namespace}:#{self.tag}"
+        end
+
+        def can_have_children?
+          true
+        end
+
+        def dump_markup(type=:xml)
+          element_string = "<#{self.namespaced_tag}"
+          self.attrs.each do |key, values|
+            element_string << " #{key}"
+            element_string << "=\""
+            values.each do |v|
+              element_string << "#{v.gsub('&','&amp;').gsub('<', '&lt;').gsub('>','&gt;')} "
+            end
+            if not values.empty?
+              element_string = element_string[0..-2]
+            end
+            element_string << "\""
+          end
+          # Close the tag if document must have valid xml
+          if self.paired? or type == :html
+            element_string << ">"
+          else
+            element_string << " />"
+          end
+          element_string
+        end
+
+        def dump_markup_close
+          "</#{self.namespaced_tag}>"
+        end
+
+        def to_s
+          element_string = "<#{self.namespaced_tag}"
+          self.attrs.each do |key, values|
+            element_string << " #{key}"
+            element_string << "=\""
+            values.each do |v|
+              element_string << "#{v} "
+            end
+            if not values.empty?
+              element_string = element_string[0..-2]
+            end
+            element_string << "\""
+          end
+          # Close the tag if document must have xml/xhtml
+          if self.paired? or not @@need_valid_xml
+            element_string << ">"
+          else
+            element_string << " />"
+          end
+          element_string
+        end
+
+        def to_s_close
+          "</#{self.namespaced_tag}>"
+        end
+
+      end
+
+      # A text element of a doctree.
+      # TextElements have no tags nor attributes and are only meant to represent document content
+      # Ex: <p>Hello World</p> is a tagged element 'p' with a single text element child with text "Hello World"
+      class TextElement < Element
+        attr_writer :text
+
+        def initialize(text='')
+          super()
+          
+          # Element text
+          @text = text  # String
+        end
+
+        # TextElement deep copy method
+        def copy
+          TextElement.new(@text)
+        end
+
+        def text
+          @text
+        end
+
+        def dump_markup(type=:xml)
+          self.text.gsub('&','&amp;').gsub('<', '&lt;').gsub('>','&gt;')
+        end
+
+        def to_s
+          self.text.inspect
+        end
+
+      end
+
+      # A comment element of a doctree.
+      # CommentElements have no tags nor attributes nor contribute to document content, but are preserved in the tree
+      # Ex: <!-- This is an example comment -->
+      class CommentElement < Element
+        attr_accessor :text
+
+        def initialize(text='')
+          super()
+          
+          # Comment text
+          @text = text  # String
+        end
+
+        # CommentElement deep copy method
+        def copy
+          CommentElement.new(@text)
+        end
+
+        def dump_markup(type=:xml)
+          "<!--#{self.text.gsub('&','&amp;').gsub('<', '&lt;').gsub('>','&gt;')}-->"
+        end
+
+        def to_s
+          "<!--#{self.text}-->"
+        end
+
+      end
+
+      # An XML Processing Instruction element in the doctree
+      # PIElements have no tags nor attributes nor contribute to document content, but are preserved in the tree
+      # Ex: <?...?> represents a processing instruction i.e. <?PITarget PIContent?>
+      class PIElement < Element
+        attr_accessor :text
+
+        def initialize(text='')
+          super()
+          
+          # Element text
+          @text = text  # String
+        end
+
+        # PIElement deep copy method
+        def copy
+          PIElement.new(@text)
+        end
+
+        def dump_markup(type=:xml)
+          "<?#{self.text.gsub('&','&amp;').gsub('<', '&lt;').gsub('>','&gt;')}?>"
+        end
+
+        def to_s
+          "<?#{self.text}?>"
+        end
+
+      end
+
+      # A TextElement that holds a reference to an incrementer within the tree
+      # CounterElements have no tags nor attributes and are only meant to represent document content
+      class CounterElement < TextElement
+        def initialize(incrementer)
+          super()
+          @incrementer = incrementer
+        end
+
+        # CounterElement deep copy method
+        def copy
+          CounterElement.new(@incrementer)
+        end
+
+        # The text representation of this element is the value of the referenced incrementere
+        def text
+          @incrementer.value.to_s
+        end
+      end
+
+      # An arbitrary group of elements
+      # ElementGroups can be placed and moved to a single location like standard elements
+      class ElementGroup
+        extend Forwardable
+        def_delegators :@group, :[], :each, :push, :<<, :length, :empty?, :first, :last
+        include Enumerable
+
+        attr_accessor :group
+
+        def initialize(elements=[])
+          @group = (elements.nil? or elements.empty?) ? [] : elements
+        end
+
+        # Provides a listing/array containing the elements of the group
+        def listing
+          @group
+        end
+
+        def +(other)
+          ElementGroup.new(self.group + other.group)
+        end
+
+        def adjacent?
+          return true if @group.length <= 1
+          @group.each_cons(2) do |current, following|
+            return false if !current.sibling_next.eql? following or !following.sibling_prev.eql? current
+          end
+          @group.first.sibling_prev.nil? and @group.last.sibling_next.nil?
+        end
+
+        def to_adjacent
+          adj_group = AdjacentElementGroup.new
+          adj_group.base(@group[0])
+          adj_group.fill
+        end
+
+        # Deep copy for ElementGroup
+        def copy
+          ElementGroup.new(@group.map {|member| member.copy})
+        end
+
+        # Detach from current parent/siblings
+        def detach
+          @group.each do |member|
+            member.detach
+          end
+        end
+        alias_method :prune, :detach
+        alias_method :delete, :detach
+
+        # Graft onto another element of the tree at any index of its children
+        # By default, it will graft as the last element of the other element's children
+        def graft_onto(graft_parent, index=-1)
+          # If index to small or large, graft to edges of graft_parent children
+          if index.abs > graft_parent.children.length
+            index = graft_parent.children.length * (index > 1 ? 1 : 0)
+          end
+          if index == graft_parent.children.length or index == -1
+            self.graft_last_onto(graft_parent)
+          elsif index == 0
+            self.graft_first_onto(graft_parent)
+          else
+            # Detach from current context
+            self.detach
+
+            # Update context
+            previous_child = graft_parent.children[index-1]
+            next_child = graft_parent.children[index]
+            @group.each do |member|
+              member.set_parent!(graft_parent)
+
+              Element.stitch!(previous_child, member)
+              previous_child = member
+            end
+            Element.stitch!(@group[-1], next_child)
+
+            # Graft group at index
+            graft_parent.children.insert(index, *@group)
+          end
+        end
+
+        # Graft onto another element of the tree as the last child
+        def graft_last_onto(graft_parent)
+          # Detach from current context
+          self.detach
+
+          # Update context
+          previous_child = graft_parent.children[-1]
+          @group.each do |member|
+            member.set_parent!(graft_parent)
+
+            Element.stitch!(previous_child, member)
+            previous_child = member
+          end
+          Element.stitch!(@group[-1], nil)
+
+          # Push graft group onto parent children
+          graft_parent.children.push(*@group)
+        end
+
+        # Graft onto another element of the tree as the first child
+        def graft_first_onto(graft_parent)
+          # Detach from current context
+          self.detach
+
+          # Update context
+          previous_child = nil
+          next_child = graft_parent.children[0]
+          @group.each do |member|
+            member.set_parent!(graft_parent)
+
+            Element.stitch!(previous_child, member)
+            previous_child = member
+          end
+          Element.stitch!(@group[-1], next_child)
+
+          # Graft group at index
+          graft_parent.children.insert(0, *@group)
+        end
+
+      end
+
+      class GroupListener < ElementGroup
+        attr_accessor :rule, :exe_block
+
+        def initialize(rule_string, exe_block)
+          super()
+          @rule = Arboretum::Scandent::Parser.parse_rule_string(rule_string, :PATH_LISTENER)
+          @exe_block = exe_block
+        end
+      end
+
+      # A group of adjacent/sibling elements
+      # Must strictly be connected to one another continuously (in order)
+      # AdjacentElementGroups have all functionality of ElementGroups
+      # They can also wrapped and swapped with other Elements/AdjacentElementGroups
+      class AdjacentElementGroup < ElementGroup
+        extend Forwardable
+        def_delegators :@group, :[], :each, :length, :empty?, :first, :last
+        undef :<<, :push
+        alias_method :to_adjacent, :itself
+        include Enumerable
+        include Contextualized
+
+        attr_accessor :group
+
+        def initialize(element=nil)
+          @group = element.nil? ? [] : [element]
+        end
+
+        # Assign starting element of the AdjacentElementGroup, if there is not already one
+        def base(element)
+          raise IndexError.new("Base element already selected") if not @group.empty?
+          raise TypeError.new("Base element cannot be nil") if element.nil?
+          @group << element
+          self
+        end
+
+        def +(other)
+          ElementGroup.new(self.group + other.group)
+        end
+
+        def adjacent?
+          true
+        end
+
+        # Deep copy for AdjacentElementGroup
+        def copy
+          group_copy = @group.map {|member| member.copy}
+          Element.stitch!(nil, group_copy.first)
+          group_copy.each_cons(2) {|current, following| Element.stitch!(current,following)}
+          Element.stitch(group_copy.last, nil)
+          adj_group_copy = AdjacentElementGroup.new
+          adj_group_copy.base(group_copy.first)
+          adj_group_copy.fill
+        end
+
+        # Extend group as much as it can be extended
+        def fill
+          if not @group.empty?
+            extend_prev until @group.first.sibling_prev.nil?
+            extend_next until @group.last.sibling_next.nil?
+          end
+          self
+        end
+
+        def index_in_parent
+          self.parent.children.index(@group.first)
+        end
+
+        def sibling_prev
+          @group.first.sibling_prev
+        end
+
+        def sibling_next
+          @group.last.sibling_next
+        end
+
+        def parent
+          @group.first.parent
+        end
+
+        # Extend the adjacent group to the last element's next sibling
+        def extend_next
+          @group << @group.last.sibling_next unless @group.last.sibling_next.nil?
+          self
+        end
+        # Extend the adjacent group to the first element's previous sibling
+        def extend_prev
+          @group.unshift(@group.first.sibling_prev) unless @group.first.sibling_prev.nil?
+          self
+        end
+
+        # Provides a listing/array containing the elements of the group
+        def listing
+          @group
+        end
+
+        # Detach from current parent/siblings, but maintain internal references between siblings
+        def detach
+          next_sibling = @group[-1].nil? ? nil : @group[-1].sibling_next
+          prev_sibling = @group[0].nil? ? nil : @group[0].sibling_prev
+          Element.stitch!(prev_sibling, next_sibling)
+          @group[0].parent.set_children!(@group[0].parent.children - @group) unless (@group[0].nil? or @group[0].parent.nil?)
+
+          @group.each {|member| member.set_parent!(nil)}
+          @group.first.set_sibling_prev!(nil)
+          @group.last.set_sibling_next!(nil)
+        end
+        alias_method :prune, :detach
+        alias_method :delete, :detach
+
+        # Graft onto another element of the tree at any index of its children
+        # By default, it will graft as the last element of the other element's children
+        def graft_onto(graft_parent, index=-1)
+          # If index to small or large, graft to edges of graft_parent children
+          if index.abs > graft_parent.children.length
+            index = graft_parent.children.length * (index > 1 ? 1 : 0)
+          end
+          if index == graft_parent.children.length or index == -1
+            self.graft_last_onto(graft_parent)
+          elsif index == 0
+            self.graft_first_onto(graft_parent)
+          else
+            # Detach from current context
+            self.detach
+
+            # Update context
+            @group.each do |member|
+              member.set_parent!(graft_parent)
+            end
+
+            previous_child = graft_parent.children[index-1]
+            next_child = graft_parent.children[index]
+            Element.stitch!(previous_child, @group[0])
+            Element.stitch!(@group[-1], next_child)
+
+            # Graft group at index
+            graft_parent.children.insert(index, *@group)
+          end
+        end
+
+        # Graft onto another element of the tree as the first child
+        def graft_first_onto(graft_parent)
+          # Detach from current context
+          self.detach
+
+          # Update context
+          @group.each do |member|
+            member.set_parent!(graft_parent)
+          end
+
+          next_child = graft_parent.children[0]
+          Element.stitch!(nil, @group[0])
+          Element.stitch!(@group[-1], next_child)
+
+          # Insert graft group at the beginning of parent children
+          graft_parent.children.insert(0, *@group)
+        end
+
+        # Graft onto another element of the tree as the last child
+        def graft_last_onto(graft_parent)
+          # Detach from current context
+          self.detach
+
+          # Update context
+          @group.each do |member|
+            member.set_parent!(graft_parent)
+          end
+
+          previous_child = graft_parent.children[-1]
+          Element.stitch!(previous_child, @group[0])
+          Element.stitch!(@group[-1], nil)
+
+          # Push graft group onto parent children
+          graft_parent.children.push(*@group)
+        end
+
+      end
+
+    end # Elements
+  end # DocTree
+end # Arboretum