duxml 0.8.8 → 0.8.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2112e7514be18ba981441e3bf2ce709214022103
-  data.tar.gz: c937e76e2c260d688f7607078f4c924224ef1c16
+  metadata.gz: ad78564c059484c71fa9c061134ba7534da88a5f
+  data.tar.gz: 5f4d4c73d8098085722ed2116173642d3a9996a6
 SHA512:
-  metadata.gz: 961905236877bba259f7331b993417b381f97ed0307bddb2206a16409c3ad630d1c1d814b50008d562062cc9471ac06ff920f63e3575df06e6baaa5819965f2d
-  data.tar.gz: d0c73ee66fc501bacd47cae5ddbee3117824154962cd41695d504b59c5b76181dcf26b389ce003089bfbee79fe87aed2c1458bb1b44b52d03c2c594c35becf8a
+  metadata.gz: c6f8d8e57be9041a357fd1067665907726910de00573c4a0647c8cb4b04d3ce29eea68314b61951bdf1384ea18054b8d28da23872caa9d9587ff5f36e11bd230
+  data.tar.gz: 903c91e7740a7093764c4405bd62dc29d21ff661f381def99b34eef087785b240f98e30ae06d09ead3f704cee471a916410e7c2b265807cd26172b4e47cbb404

data/bin/validate_xml

@@ -1,31 +1,31 @@
-#!/usr/bin/env ruby
-# Copyright (c) 2016 Freescale Semiconductor Inc.
-
-require File.expand_path(File.dirname(__FILE__) + '/../lib/duxml')
-
-include Duxml
-
-DITA_GRAMMAR_FILE = File.expand_path(File.dirname(__FILE__) + '/../xml/test_grammar.xml')
-xml_file = ARGV.first
-log_file = ARGV[1] || 'log.txt'
-
-load xml_file
-puts "loaded XML file: #{xml_file}"
-meta.grammar = DITA_GRAMMAR_FILE
-puts "loaded grammar file: #{DITA_GRAMMAR_FILE}"
-validate
-puts "validation complete"
-log log_file
-puts "logged errors to #{log_file}"
-
-
-if conditions
-
-end
-
-
-def conditions
-  asdf and b and c
-end
-
+#!/usr/bin/env ruby
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../lib/duxml')
+
+include Duxml
+
+DITA_GRAMMAR_FILE = File.expand_path(File.dirname(__FILE__) + '/../xml/test_grammar.xml')
+xml_file = ARGV.first
+log_file = ARGV[1] || 'log.txt'
+
+load xml_file
+puts "loaded XML file: #{xml_file}"
+meta.grammar = DITA_GRAMMAR_FILE
+puts "loaded grammar file: #{DITA_GRAMMAR_FILE}"
+validate
+puts "validation complete"
+log log_file
+puts "logged errors to #{log_file}"
+
+
+if conditions
+
+end
+
+
+def conditions
+  asdf and b and c
+end
+
 File

data/lib/duxml.rb

@@ -1,76 +1,76 @@
-# Copyright (c) 2016 Freescale Semiconductor Inc.
-
-require File.expand_path(File.dirname(__FILE__) + '/duxml/saxer')
-
-module Duxml
-  include Saxer
-
-  # most recently processed document - default location for validated documents that are not loaded explicitly
-  @doc
-
-  attr_reader :doc
-
-  # @param _file [String] loads XML file from given path and finds or creates corresponding metadata file e.g. '.xml_file.duxml'
-  # @param grammar_path [nil, String, Duxml::Grammar] optional - provide an external grammar file or object
-  # @return [Doc] XML document as Ruby object
-  def load(_file, grammar_path=nil)
-    meta_path = Meta.meta_path(_file)
-
-    if File.exists?(meta_path)
-      meta = Ox.parse_obj(File.read meta_path)
-      meta.grammar = grammar_path unless grammar_path.nil? or meta.grammar.defined?
-    else
-      meta = MetaClass.new(grammar_path)
-    end
-
-    if File.exists?(_file)
-      @doc = sax(_file, meta.history)
-    else
-      @doc = Doc.new
-      @doc.path = _file
-
-      doc.delete_observers if doc.count_observers > 0 and doc.observer_peers.first.object_id != meta.history.object_id
-      doc.add_observer meta.history if doc.count_observers < 1
-    end
-    doc.set_meta meta
-  end # def load
-
-  # @param file [String] saves current content XML to given file path
-  # @param xml [Doc, Element] current Doc by default, but can also be unattached XML Element
-  def save(file, xml=doc)
-    @doc = xml.respond_to?(:root) ? xml : Doc.new << xml
-    doc.write_to file
-    File.write(Meta.meta_path(file), Ox.dump(doc.meta, circular: true))
-  end
-
-  # @param file [String] output file path for logging human-readable validation error messages
-  def log(file)
-    File.write(file, meta.history.description)
-  end
-
-  # @param *Args [String, Doc] if string then path to load Doc, else Doc to validate
-  # @param options [Hash, Symbol] currently just supports suppression of console output of results with :quiet
-  # @return [Boolean] whether file passed validation
-  def validate(path_or_doc, options={})
-    doc = path_or_doc.is_a?(Doc) ? path_or_doc : load(path_or_doc)
-    unless doc.grammar.defined?
-      raise Exception, "grammar not defined!" unless options[:grammar]
-      doc.grammar = options[:grammar]
-    end
-    raise Exception, "XML document has no root element!" unless doc.root
-    results = []
-    doc.root.traverse do |n| results << doc.grammar.validate(n) unless n.is_a?(String) end
-    puts(doc.history.description) unless options[:quiet]
-    !results.any? do |r| !r end
-  end # def validate
-
-  private
-  # @param g_path [String, GrammarClass] grammar to associate with @doc, which must be set to a Doc and not nil
-  def associate_grammar(g_path)
-    doc.grammar = g_path if g_path
-  end
-
-  def find_meta
-
-  end
-end # module Duxml
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/duxml/saxer')
+
+module Duxml
+  include Saxer
+
+  # most recently processed document - default location for validated documents that are not loaded explicitly
+  @doc
+
+  attr_reader :doc
+
+  # @param _file [String] loads XML file from given path and finds or creates corresponding metadata file e.g. '.xml_file.duxml'
+  # @param grammar_path [nil, String, Duxml::Grammar] optional - provide an external grammar file or object
+  # @return [Doc] XML document as Ruby object
+  def load(_file, grammar_path=nil)
+    meta_path = Meta.meta_path(_file)
+
+    if File.exists?(meta_path)
+      meta = Ox.parse_obj(File.read meta_path)
+      meta.grammar = grammar_path unless grammar_path.nil? or meta.grammar.defined?
+    else
+      meta = MetaClass.new(grammar_path)
+    end
+
+    if File.exists?(_file)
+      @doc = sax(_file, meta.history)
+    else
+      @doc = Doc.new
+      @doc.path = _file
+
+      doc.delete_observers if doc.count_observers > 0 and doc.observer_peers.first.object_id != meta.history.object_id
+      doc.add_observer meta.history if doc.count_observers < 1
+    end
+    doc.set_meta meta
+  end # def load
+
+  # @param file [String] saves current content XML to given file path
+  # @param xml [Doc, Element] current Doc by default, but can also be unattached XML Element
+  def save(file, xml=doc)
+    @doc = xml.respond_to?(:root) ? xml : Doc.new << xml
+    doc.write_to file
+    File.write(Meta.meta_path(file), Ox.dump(doc.meta, circular: true))
+  end
+
+  # @param file [String] output file path for logging human-readable validation error messages
+  def log(file)
+    File.write(file, meta.history.description)
+  end
+
+  # @param *Args [String, Doc] if string then path to load Doc, else Doc to validate
+  # @param options [Hash, Symbol] currently just supports suppression of console output of results with :quiet
+  # @return [Boolean] whether file passed validation
+  def validate(path_or_doc, options={})
+    doc = path_or_doc.is_a?(Doc) ? path_or_doc : load(path_or_doc)
+    unless doc.grammar.defined?
+      raise Exception, "grammar not defined!" unless options[:grammar]
+      doc.grammar = options[:grammar]
+    end
+    raise Exception, "XML document has no root element!" unless doc.root
+    results = []
+    doc.root.traverse do |n| results << doc.grammar.validate(n) unless n.is_a?(String) end
+    puts(doc.history.description) unless options[:quiet]
+    !results.any? do |r| !r end
+  end # def validate
+
+  private
+  # @param g_path [String, GrammarClass] grammar to associate with @doc, which must be set to a Doc and not nil
+  def associate_grammar(g_path)
+    doc.grammar = g_path if g_path
+  end
+
+  def find_meta
+
+  end
+end # module Duxml

data/lib/duxml/doc.rb

@@ -1,92 +1,109 @@
-# Copyright (c) 2016 Freescale Semiconductor Inc.
-
-require File.expand_path(File.dirname(__FILE__) + '/doc/element')
-require File.expand_path(File.dirname(__FILE__) + '/meta')
-
-module Duxml
-  class Doc < ::Ox::Document
-    include ElementGuts
-
-    # path of file where this Doc is saved to
-    @path
-
-    # meta data for this Doc; contains reference to grammar if it exists and history
-    @meta
-
-    attr_reader :meta, :path
-
-    def initialize(prolog={})
-      super(prolog)
-      self[:version] ||= '1.0'
-      @meta = MetaClass.new
-      @nodes = NodeSet.new(self)
-      add_observer meta.history
-    end
-
-    # @param _path [String] assigns file path to document, creating it if it does not already exist along with metadata file
-    def path=(_path)
-      @path = _path
-      set_meta _path unless path
-      unless File.exists?(path)
-        write_to(path)
-      end
-    end
-
-    # @return [String] summary of XML document as Ruby object and description of root element
-    def to_s
-      "#<#{self.class.to_s} @object_id='#{object_id}' @root='#{root.nil? ? '' : root.description}'>"
-    end
-
-    # @param path_or_obj [String, MetaClass] metadata object itself or path of metadata for this file; if none given, saves existing metadata to file using @path
-    # @return [Doc] self
-    def set_meta(path_or_obj=nil)
-      @meta = case path_or_obj
-                when MetaClass, Element then path_or_obj
-                when String && File.exists?(path_or_obj)
-                  Ox.parse_obj(path_or_obj)
-                else
-                  File.write(Meta.meta_path(path), Ox.dump(meta)) if path
-                  meta
-              end
-      self
-    end
-
-    # shortcut method @see Meta#grammar
-    def grammar
-      meta.grammar
-    end
-
-    # shortcut method @see Meta#grammar=
-    def grammar=(grammar_or_file)
-      meta.grammar = grammar_or_file
-    end
-
-    # shortcut method @see Meta#history
-    def history
-      meta.history
-    end
-
-    # @return [String] one word description of what this object is: 'document'
-    def description
-      'document'
-    end
-
-    # @param path [String] document's file path
-    # @return [Doc] returns self after writing contents to file
-    def write_to(path)
-      s = attributes.collect do |k, v| %( #{k}="#{v}") end.join
-      File.write(path, %(<?xml #{s}?>\n) + root.to_s)
-      x = meta.xml
-      File.write(Meta.meta_path(path), meta.xml.to_s)
-      self
-    end
-
-    def <<(obj)
-      super(obj)
-      obj.set_doc! self
-      self
-    end
-  end # class Document < Element
-end
-
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/doc/element')
+require File.expand_path(File.dirname(__FILE__) + '/meta')
+
+module Duxml
+  class Doc < ::Ox::Document
+    include ElementGuts
+
+    # path of file where this Doc is saved to
+    @path
+
+    # meta data for this Doc; contains reference to grammar if it exists and history
+    @meta
+
+    # hash of all unique-id elements within document; gets initialized as each is searched for
+    @id_hash
+
+    attr_reader :meta, :path, :id_hash
+
+    def initialize(prolog={})
+      super(prolog)
+      self[:version] ||= '1.0'
+      @id_hash = {}
+      @meta = MetaClass.new
+      @nodes = NodeSet.new(self)
+      add_observer meta.history
+    end
+
+    # @param _path [String] assigns file path to document, creating it if it does not already exist along with metadata file
+    def path=(_path)
+      @path = _path
+      set_meta _path unless path
+      unless File.exists?(path)
+        write_to(path)
+      end
+    end
+
+    # @return [String] summary of XML document as Ruby object and description of root element
+    def to_s
+      "#<#{self.class.to_s} @object_id='#{object_id}' @root='#{root.nil? ? '' : root.description}'>"
+    end
+
+    # @param path_or_obj [String, MetaClass] metadata object itself or path of metadata for this file; if none given, saves existing metadata to file using @path
+    # @return [Doc] self
+    def set_meta(path_or_obj=nil)
+      @meta = case path_or_obj
+                when MetaClass, Element then path_or_obj
+                when String && File.exists?(path_or_obj)
+                  Ox.parse_obj(path_or_obj)
+                else
+                  File.write(Meta.meta_path(path), Ox.dump(meta)) if path
+                  meta
+              end
+      self
+    end
+
+    # shortcut method @see Meta#grammar
+    def grammar
+      meta.grammar
+    end
+
+    # shortcut method @see Meta#grammar=
+    def grammar=(grammar_or_file)
+      meta.grammar = grammar_or_file
+    end
+
+    # shortcut method @see Meta#history
+    def history
+      meta.history
+    end
+
+    # @return [String] one word description of what this object is: 'document'
+    def description
+      'document'
+    end
+
+    # @param path [String] document's file path
+    # @return [Doc] returns self after writing contents to file
+    def write_to(path)
+      s = attributes.collect do |k, v| %( #{k}="#{v}") end.join
+      File.write(path, %(<?xml #{s}?>\n) + root.to_s)
+      x = meta.xml
+      File.write(Meta.meta_path(path), meta.xml.to_s)
+      self
+    end
+
+    def <<(obj)
+      super(obj)
+      obj.set_doc! self
+      self
+    end
+
+    # @param id [String, Symbol] document-unique id attribute value
+    # @return [Element, NilClass] found element or nil if not found
+    def find_by_id(id)
+      id_str = id.to_s
+      return @id_hash[id_str] if @id_hash[id_str]
+      root.traverse do |node|
+        if node.respond_to?(:nodes) and node[:id] == id_str
+          return @id_hash[id_str] = node
+        end
+      end
+      nil
+    end
+  end # class Document < Element
+end
+
 Hash

data/lib/duxml/doc/element.rb

@@ -1,251 +1,251 @@
-# Copyright (c) 2016 Freescale Semiconductor Inc.
-
-require 'ox'
-require File.expand_path(File.dirname(__FILE__) + '/lazy_ox')
-require File.expand_path(File.dirname(__FILE__) + '/node_set')
-require File.expand_path(File.dirname(__FILE__) + '/../reportable')
-
-module Duxml
-  # contains actual methods of XML Element
-  module ElementGuts
-    include Duxml
-    include Enumerable
-    include Reportable
-    include LazyOx
-  end
-
-  # basic component of XML file that can possess attributes and take sub Elements or String content
-  class Element < ::Ox::Element
-    include ElementGuts
-
-    # line number
-    @line
-
-    # column
-    @column
-
-    # document to which this Element belongs
-    @doc
-
-    # operates in two modes:
-    # - from Ruby
-    # - from file
-    # in file mode, args provide Element's line and column location then freezes each Fixnum so it cannot be overwritten
-    # in Ruby mode, args are some combination of new attributes/values and/or child nodes (text or XML) with which to initialize this node
-    #
-    # @param name [String] name of element, in both Ruby and file modes
-    # @param _line_or_content [Fixnum, Array, Hash] line number of element file mode; if Array, new child nodes; if Hash, attributes; can be nil
-    # @param _col_or_children [Fixnum, Array] column position in file mode; if Array, new child nodes; can be nil
-    # @return [Element] new XML Element
-    def initialize(name, _line_or_content=nil, _col_or_children=nil)
-      super name
-      @line = _line_or_content if _line_or_content.respond_to?(:%)
-      _line_or_content.each do |k,v| self[k] = v end if _line_or_content.respond_to?(:key)
-      @nodes = NodeSet.new(self, _line_or_content) if _line_or_content.respond_to?(:pop) && _col_or_children.nil?
-      @column = _col_or_children if _col_or_children.respond_to?(:%)
-      @nodes = NodeSet.new(self, _col_or_children) if _col_or_children.respond_to?(:pop)
-      @nodes = NodeSet.new(self) if @nodes.empty?
-    end
-
-    attr_reader :line, :column, :doc
-
-    attr_accessor :nodes
-  end
-
-  module ElementGuts
-    # @return [Boolean] whether or not this has been written to file
-    def abstract?
-      line < 0 || column < 0
-    end
-
-    # @param _doc [Doc] document to which this element belongs - recursively applies to all descendants of this node
-    # @return [Element] self
-    def set_doc!(_doc)
-      @doc = _doc
-      traverse do |node|
-        next if node === self or node.is_a?(String)
-        node.set_doc!(_doc)
-      end
-      self
-    end
-
-    # @see Ox::Element#<<
-    # this override reports changes to history; NewText for Strings, Add for elements
-    #
-    # @param obj [Element, Array] element or string to add to this Element; can insert arrays which are always inserted in order
-    # @return [Element] self
-    def <<(obj)
-      add(obj)
-    end
-
-    # @see #<<
-    # this version of the method allows insertions between existing elements
-    #
-    # @param obj [Element, Array] element or string to add to this Element; can insert arrays which are always inserted in order
-    # @param index [Fixnum] index at which to insert new node; inserts at end of element by default; when inserting arrays, index is incremented for each item to avoid reversing array order
-    # @return [Element] self
-    def add(obj, index=-1)
-      case
-        when obj.is_a?(Array), obj.is_a?(NodeSet)
-          obj.each_with_index do |e, i|
-            add(e, index == -1 ? index : index+i)
-          end
-        when obj.is_a?(String)
-          if obj[0] == '<' and obj[-1] == '>' and (s = Ox.parse(obj))
-            add dclone s
-          else
-            type = :NewText
-            nodes.insert(index, obj)
-          end
-        else
-          type = :Add
-          nodes.insert(index, obj)
-          if obj.count_observers < 1 && @observer_peers
-            obj.add_observer(@observer_peers.first.first)
-          end
-          obj.set_doc! @doc
-      end
-      report(type, obj, index)
-      self
-    end
-
-    # @param index_or_attr [String, Symbol, Fixnum] string or symbol of attribute or index of child node
-    # @return [Element, String] string if attribute value or text node; Element if XML node
-    def [](index_or_attr)
-      index_or_attr.is_a?(Fixnum) ? nodes[index_or_attr] : super(index_or_attr)
-    end
-
-    # @param attr_sym [String, Symbol, Fixnum] name of attribute or index of child to replace
-    # @param val [String] new attribute value or replacement child node
-    # @return [Element] self
-    def []=(attr_sym, val)
-      if attr_sym.is_a?(Fixnum)
-        remove nodes[attr_sym]
-        add(val, attr_sym)
-        return self
-      end
-      attr = attr_sym.to_s
-      raise "argument to [] must be a Symbol or a String." unless attr.is_a?(Symbol) or attr.is_a?(String)
-      args = [attr]
-      args << attributes[attr] if attributes[attr]
-      super(attr, val)
-      type = args.size == 1 ? :NewAttr : :ChangeAttr
-      report(type, *args)
-      self
-    end
-
-    # @return [String] self description
-    def description
-      "<#{name}>"
-    end
-
-    # @return [Element] copy of this Element but with no children
-    def stub
-      Element.new(name, attributes)
-    end
-
-    # @return [HistoryClass] history that is observing this element for changes
-    def history
-      @observer_peers.first.first if @observer_peers.respond_to?(:any?) and @observer_peers.any? and @observer_peers.first.any?
-    end
-
-    # @return [String] XML string (overrides Ox's to_s which just prints the object pointer)
-    def to_s
-      s = %(<#{name})
-      attributes.each do |k,v| s << %( #{k.to_s}="#{v}") end
-      return s+'/>' if nodes.empty?
-      s << ">#{nodes.collect do |n| n.to_s end.join}</#{name}>"
-    end
-
-    # @return #to_s
-    def inspect
-      to_s
-    end
-
-    # TODO do we need this method to take Fixnum node index as well?
-    # @param obj [Element] element child to delete
-    # @return [Element] deleted element
-    def delete(obj)
-      report(:Remove, @nodes.delete(obj))
-      obj
-    end
-
-    alias_method :remove, :delete
-
-    # pre-order traverse through this node and all of its descendants
-    #
-    # @param &block [block] code to execute for each yielded node
-    def traverse(node=nil, &block)
-      return self.to_enum unless block_given?
-      node_stack = [node || self]
-
-      until node_stack.empty?
-        current = node_stack.shift
-        if current
-          yield current
-          node_stack = node_stack.insert(0, *current.nodes) if current.respond_to?(:nodes)
-        end
-      end
-
-      node || self if block_given?
-    end
-
-    # traverse through just the children of this node
-    #
-    # @param &block [block] code to execute for each child node
-    def each(&block)
-      @nodes.each(&block)
-    end
-
-    # @return [String] namespace of element, derived from name e.g. '<duxml:element>' => 'duxml'
-    def name_space
-      return nil unless (i = name.index(':'))
-      name[0..i-1]
-    end
-
-
-    # @param source [Element] if not explicitly provided, creates deep clone of this element; source can be any XML element (not only Duxml) that responds to traverse with pre-order traversal
-    # @return [Element] deep clone of source, including its attributes and recursively cloned children
-    def dclone(source = self)
-      input_stack = []
-      output_stack = []
-      traverse(source) do |node|
-        if node.is_a?(String)
-          output_stack.last << node
-          next
-        end
-        copy = Element.new(node.name, node.attributes)
-        if output_stack.empty?
-          output_stack << copy
-          input_stack << node
-        else
-
-          if input_stack.last.nodes.none? do |n| n === node end
-            input_stack.pop
-            output_stack.pop
-          end
-
-          output_stack.last << copy
-          if node.nodes.any?
-            output_stack << copy
-            input_stack << node
-          end
-
-        end
-      end
-      output_stack.pop
-    end
-
-    # @return [Element] shallow clone of this element, with all attributes and children only if none are Elements
-    def sclone
-      stub = Element.new(name, attributes)
-      stub << nodes if text?
-      stub
-    end
-
-    # @return [true, false] true if all child nodes are text only; false if any child nodes are XML
-    def text?
-      nodes.all? do |node| node.is_a?(String) end
-    end
-  end # class Element < Node
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require 'ox'
+require File.expand_path(File.dirname(__FILE__) + '/lazy_ox')
+require File.expand_path(File.dirname(__FILE__) + '/node_set')
+require File.expand_path(File.dirname(__FILE__) + '/../reportable')
+
+module Duxml
+  # contains actual methods of XML Element
+  module ElementGuts
+    include Duxml
+    include Enumerable
+    include Reportable
+    include LazyOx
+  end
+
+  # basic component of XML file that can possess attributes and take sub Elements or String content
+  class Element < ::Ox::Element
+    include ElementGuts
+
+    # line number
+    @line
+
+    # column
+    @column
+
+    # document to which this Element belongs
+    @doc
+
+    # operates in two modes:
+    # - from Ruby
+    # - from file
+    # in file mode, args provide Element's line and column location then freezes each Fixnum so it cannot be overwritten
+    # in Ruby mode, args are some combination of new attributes/values and/or child nodes (text or XML) with which to initialize this node
+    #
+    # @param name [String] name of element, in both Ruby and file modes
+    # @param _line_or_content [Fixnum, Array, Hash] line number of element file mode; if Array, new child nodes; if Hash, attributes; can be nil
+    # @param _col_or_children [Fixnum, Array] column position in file mode; if Array, new child nodes; can be nil
+    # @return [Element] new XML Element
+    def initialize(name, _line_or_content=nil, _col_or_children=nil)
+      super name
+      @line = _line_or_content if _line_or_content.respond_to?(:%)
+      _line_or_content.each do |k,v| self[k] = v end if _line_or_content.respond_to?(:key)
+      @nodes = NodeSet.new(self, _line_or_content) if _line_or_content.respond_to?(:pop) && _col_or_children.nil?
+      @column = _col_or_children if _col_or_children.respond_to?(:%)
+      @nodes = NodeSet.new(self, _col_or_children) if _col_or_children.respond_to?(:pop)
+      @nodes = NodeSet.new(self) if @nodes.empty?
+    end
+
+    attr_reader :line, :column, :doc
+
+    attr_accessor :nodes
+  end
+
+  module ElementGuts
+    # @return [Boolean] whether or not this has been written to file
+    def abstract?
+      line < 0 || column < 0
+    end
+
+    # @param _doc [Doc] document to which this element belongs - recursively applies to all descendants of this node
+    # @return [Element] self
+    def set_doc!(_doc)
+      @doc = _doc
+      traverse do |node|
+        next if node === self or node.is_a?(String)
+        node.set_doc!(_doc)
+      end
+      self
+    end
+
+    # @see Ox::Element#<<
+    # this override reports changes to history; NewText for Strings, Add for elements
+    #
+    # @param obj [Element, Array] element or string to add to this Element; can insert arrays which are always inserted in order
+    # @return [Element] self
+    def <<(obj)
+      add(obj)
+    end
+
+    # @see #<<
+    # this version of the method allows insertions between existing elements
+    #
+    # @param obj [Element, Array] element or string to add to this Element; can insert arrays which are always inserted in order
+    # @param index [Fixnum] index at which to insert new node; inserts at end of element by default; when inserting arrays, index is incremented for each item to avoid reversing array order
+    # @return [Element] self
+    def add(obj, index=-1)
+      case
+        when obj.is_a?(Array), obj.is_a?(NodeSet)
+          obj.each_with_index do |e, i|
+            add(e, index == -1 ? index : index+i)
+          end
+        when obj.is_a?(String)
+          if obj[0] == '<' and obj[-1] == '>' and (s = Ox.parse(obj))
+            add dclone s
+          else
+            type = :NewText
+            nodes.insert(index, obj)
+          end
+        else
+          type = :Add
+          nodes.insert(index, obj)
+          if obj.count_observers < 1 && @observer_peers
+            obj.add_observer(@observer_peers.first.first)
+          end
+          obj.set_doc! @doc
+      end
+      report(type, obj, index)
+      self
+    end
+
+    # @param index_or_attr [String, Symbol, Fixnum] string or symbol of attribute or index of child node
+    # @return [Element, String] string if attribute value or text node; Element if XML node
+    def [](index_or_attr)
+      index_or_attr.is_a?(Fixnum) ? nodes[index_or_attr] : super(index_or_attr)
+    end
+
+    # @param attr_sym [String, Symbol, Fixnum] name of attribute or index of child to replace
+    # @param val [String] new attribute value or replacement child node
+    # @return [Element] self
+    def []=(attr_sym, val)
+      if attr_sym.is_a?(Fixnum)
+        remove nodes[attr_sym]
+        add(val, attr_sym) if val
+        return self
+      end
+      attr = attr_sym.to_s
+      raise "argument to [] must be a Symbol or a String." unless attr.is_a?(Symbol) or attr.is_a?(String)
+      args = [attr]
+      args << attributes[attr] if attributes[attr]
+      val.nil? ? @attributes.delete(attr) : super(attr, val)
+      type = args.size == 1 ? :NewAttr : :ChangeAttr
+      report(type, *args)
+      self
+    end
+
+    # @return [String] self description
+    def description
+      "<#{name}>"
+    end
+
+    # @return [Element] copy of this Element but with no children
+    def stub
+      Element.new(name, attributes)
+    end
+
+    # @return [HistoryClass] history that is observing this element for changes
+    def history
+      @observer_peers.first.first if @observer_peers.respond_to?(:any?) and @observer_peers.any? and @observer_peers.first.any?
+    end
+
+    # @return [String] XML string (overrides Ox's to_s which just prints the object pointer)
+    def to_s
+      s = %(<#{name})
+      attributes.each do |k,v| s << %( #{k.to_s}="#{v}") end
+      return s+'/>' if nodes.empty?
+      s << ">#{nodes.collect do |n| n.to_s end.join}</#{name}>"
+    end
+
+    # @return #to_s
+    def inspect
+      to_s
+    end
+
+    # TODO do we need this method to take Fixnum node index as well?
+    # @param obj [Element] element child to delete
+    # @return [Element] deleted element
+    def delete(obj)
+      report(:Remove, @nodes.delete(obj))
+      obj
+    end
+
+    alias_method :remove, :delete
+
+    # pre-order traverse through this node and all of its descendants
+    #
+    # @param &block [block] code to execute for each yielded node
+    def traverse(node=nil, &block)
+      return self.to_enum unless block_given?
+      node_stack = [node || self]
+
+      until node_stack.empty?
+        current = node_stack.shift
+        if current
+          yield current
+          node_stack = node_stack.insert(0, *current.nodes) if current.respond_to?(:nodes)
+        end
+      end
+
+      node || self if block_given?
+    end
+
+    # traverse through just the children of this node
+    #
+    # @param &block [block] code to execute for each child node
+    def each(&block)
+      @nodes.each(&block)
+    end
+
+    # @return [String] namespace of element, derived from name e.g. '<duxml:element>' => 'duxml'
+    def name_space
+      return nil unless (i = name.index(':'))
+      name[0..i-1]
+    end
+
+
+    # @param source [Element] if not explicitly provided, creates deep clone of this element; source can be any XML element (not only Duxml) that responds to traverse with pre-order traversal
+    # @return [Element] deep clone of source, including its attributes and recursively cloned children
+    def dclone(source = self)
+      input_stack = []
+      output_stack = []
+      traverse(source) do |node|
+        if node.is_a?(String)
+          output_stack.last << node
+          next
+        end
+        copy = Element.new(node.name, node.attributes)
+        if output_stack.empty?
+          output_stack << copy
+          input_stack << node
+        else
+
+          if input_stack.last.nodes.none? do |n| n === node end
+            input_stack.pop
+            output_stack.pop
+          end
+
+          output_stack.last << copy
+          if node.nodes.any?
+            output_stack << copy
+            input_stack << node
+          end
+
+        end
+      end
+      output_stack.pop
+    end
+
+    # @return [Element] shallow clone of this element, with all attributes and children only if none are Elements
+    def sclone
+      stub = Element.new(name, attributes)
+      stub << nodes if text?
+      stub
+    end
+
+    # @return [true, false] true if all child nodes are text only; false if any child nodes are XML
+    def text?
+      nodes.all? do |node| node.is_a?(String) end
+    end
+  end # class Element < Node
 end # module Ox