duxml 0.7.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a443f0b41070e85e05a9042711af460f1a9de0ce
+  data.tar.gz: c25d6801574a1730e3a38a5ccab2ed91b482d37b
+SHA512:
+  metadata.gz: 2804f997a7fa48f9bd6c24ddef5e8b84df058b4bfbc1f6a41cbda340646378ef0d94a95a32b89cc1160819bb2d9bf37926c8196e2e8f5d9d70950a5baa973f3b
+  data.tar.gz: d2cac9f2b2c16c07b754f98224eea4da660857a73345215bed10824818cd837de15ce2fe98bb06a2100eb69171537fd270ae27dd6199710c1e740c88fd3d2711

data/bin/validate_xml

@@ -0,0 +1,19 @@
+#!/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}"

data/lib/duxml/doc/element.rb

@@ -0,0 +1,157 @@
+# 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
+
+    # 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_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
+    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
+
+    attr_accessor :nodes
+  end
+
+  module ElementGuts
+    # @return [Boolean] whether or not this has been written to file
+    def abstract?
+      line < 0 || column < 0
+    end
+
+    # @see Ox::Element#<<
+    # this override reports changes to history; NewText for Strings, Add for elements
+    #
+    # @param obj [Element] element or string to add to this Element
+    # @return [Element] self
+    def <<(obj)
+      case
+        when obj.is_a?(Array), obj.is_a?(NodeSet)
+          obj.each do |e| self << e end
+        when obj.is_a?(String)
+          type = :NewText
+          super(obj)
+        else
+          type = :Add
+          super(obj)
+          if nodes.last.count_observers < 1 && @observer_peers
+            nodes.last.add_observer(@observer_peers.first.first)
+          end
+      end
+      report(type, nodes.size - 1)
+      self
+    end
+
+    # @param attr_sym [String, Symbol] name of attribute
+    # @param val [String]
+    # @return [Element] self
+    def []=(attr_sym, val)
+      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(&block)
+      return self.to_enum unless block_given?
+      node_stack = [self]
+
+      until node_stack.empty?
+        current = node_stack.shift
+        if current
+          yield current
+          node_stack = node_stack.concat(current.nodes) if current.respond_to?(:nodes)
+        end
+      end
+
+      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
+  end # class Element < Node
+end # module Ox

data/lib/duxml/doc/lazy_ox.rb

@@ -0,0 +1,153 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../ruby_ext/string')
+
+
+module Duxml
+  module LazyOx
+  # welcome to Lazy-Ox - where any method that doesn't exist, you can create on the fly and assign its methods to
+  # a corresponding Duxml::Element. see Regexp.nmtoken and String#nmtokenize and String#constantize to see how a given symbol
+  # can be converted into XML element names and vice versa. it can also use Class names as method calls to return children by type
+  #
+  # this method uses Ox::Element's :method_missing but adds an additional rescue block that:
+  #   matches namespaced Ruby module to this Element's name and extends this node with module's methods
+  #   then method matching symbol is called again with given arguments, yielding result to block if given, returning result if not
+  #   e.g.
+  #     module Duxml
+  #       module Throwable
+  #         def throw
+  #           puts 'throwing!!'
+  #         end
+  #       end
+  #     end
+  #
+  #     Element.new('throwable').throw => 'throwing!!'
+  #
+  #   if symbol name matches a class then method yields to block or returns as array child nodes that matches class
+  #   you can further refine search results by adding the symbol of the child instance variable, including name, by which to filter
+  #   if block given, returns first child for which block evaluates to true
+  #
+  #   e.g.
+#       class Child; end
+  #
+  #     n = Element.new('node')
+  #     n << 'text'
+  #     n << Element.new('child')
+  #     n << Element.new('child')
+  #     n.Element                                                      # returns Array of Element nodes
+  #         => [#<Duxml::Element:0x0002 @value="child" ...>,
+  #             #<Duxml::Element:0x0003 @value="child" ...>]
+  #
+  #     n.Element.each do |child| child << 'some text' end              # adding some text
+  #         => ['text',
+  #             #<Duxml::Element:0x0002 @value="child" ... @nodes=['some text']>,
+  #             #<Duxml::Element 0x0003 @value="child" ... @nodes=['some text']>]
+  #
+  #     n.Element do |child| child.nodes.first == 'some text' end                             # returns all children for which block is true
+  #         => [#<Duxml::Element:0x0002 @value="child" ... @nodes=['some text']>]
+  #
+  #     %w(bar mar).each_with_index do |x, i| next if i.zero?; n.Child[:foo] = x end        # adding some attributes
+  #         => ['text',
+  #             #<Duxml::Element:0x0002 @value="child" @attributes={foo: 'bar'} ...>,
+  #             #<Duxml::Element:0x0003 @value="child" @attributes={foo: 'mar'} ...>]
+  #
+  #     n.Element(:foo)                                                                       # returns array of Child nodes with attribute :foo
+  #         => [#<Duxml::Element:0x0002 @value="child" @attributes={foo: 'bar'} ...>,
+  #             #<Duxml::Element:0x0003 @value="child" @attributes={foo: 'mar'} ...>]
+  #
+  #     n.Element(foo: 'bar')                                                                 # returns array of Child nodes with attribute :foo equal to 'bar'
+  #         => [#<Duxml::Element:0xfff @value="child" @attributes={foo: 'bar'} ...>]
+  #
+  #
+  #   if element name has no matching Class or Module in namespace,
+  #     if symbol is lower case, it is made into a method, given &block as definition, then called with *args
+  #       e.g. n.change_color('blue') do |new_color|  => #<Duxml::Element:0xfff @value="node" @attributes={color: 'blue'} @nodes=[]>
+  #              @color = new_color
+  #              self
+  #            end
+  #            n.color                                => 'blue'
+  #            n.change_color('mauve').color          => 'mauve'
+  #
+  # @param sym [Symbol] method, class or module
+  # @param *args [*several_variants] either arguments to method or initializing values for instance of given class
+  # @param &block [block] if yielding result, yields to given block; if defining new method, block defines its contents
+    def method_missing(sym, *args, &block)
+      super(sym, *args, &block)
+    rescue NoMethodError
+      # handling Constant look up to dynamically extend or add to element
+      if lowercase?(sym)
+        if (const = look_up_const) and const.is_a?(Module)
+          extend const
+          result = method(sym).call(*args)
+          return(result) unless block_given?
+          yield(result)
+        elsif block_given?
+          new_method = proc(&block)
+          self.const_set(sym, new_method)
+          return new_method.call *args
+        else
+          raise NoMethodError, "undefined method `#{sym.to_s}' for #{description}"
+        end # if (const = look_up_const) ... elsif block_given? ... else ...
+      else
+        results = filter(sym, args)
+        return results unless block_given?
+        results.keep_if do |node| yield(node) end
+      end # if lowercase? ... else ...
+    end # def method_missing(sym, *args, &block)
+
+    private
+
+    # @param sym [Symbol] indicates which element type is being filtered for
+    # @param args [several_variants] arguments for filtering element children that matched 'sym'
+    # @return [[Element]] Elements of type 'sym' that match criteria 'args'
+    def filter(sym, args)
+      class_nodes = nodes.select do |node|
+        node.name == sym.to_s.nmtokenize or simple_class(node) == sym.to_s
+      end
+      class_nodes.keep_if do |node|
+        if args.empty?
+          true
+        else
+          args.any? do |arg|
+            if arg.is_a?(Hash)
+              node[arg.first.first] == arg.first.last
+            else
+              !node[arg].nil?
+            end
+          end
+        end # if args.empty? ... else ...
+      end # class_nodes.keep_if do |node|
+    end # def filter(args)
+
+    # @param maudule [Module] module context in which to look for duck-called method's module
+    # @return [Module, Class] requested module or class
+    def look_up_const(maudule = Duxml)
+      mod_names = name.split(':')
+      until mod_names.empty?
+        word = mod_names.shift
+        k = word.constantize
+        if maudule.const_defined?(k, true) or Module.const_defined?(simple_class, true)
+          const = maudule.const_get(k)
+          if const.is_a?(Module)
+            maudule = const
+          end
+
+          return const if mod_names.empty? and [Module, Class].include?(const.class)
+        end
+      end
+      nil
+    end
+
+    # @param sym [Symbol] symbol for a constant
+    # @return [Boolean] is symbol lowercase?
+    def lowercase?(sym)
+      sym.to_s[0].match(/[A-Z]/).nil?
+    end
+
+    # @param obj [Object] usually Element
+    # @return [String] name of final Class or Module of self
+    def simple_class(obj=self)
+      obj.class.to_s.split('::').last
+    end
+  end # module LazyOx
+end # module Duxml

data/lib/duxml/doc/node_set.rb

@@ -0,0 +1,39 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require 'observer'
+
+module Duxml
+  # subclass of Array that is Observable by History
+  # used to track changes in String nodes of XML Element
+  class NodeSet < Array
+    include Observable
+
+    @parent
+
+    attr_reader :parent
+
+    # @param _parent [Element] Element that is parent to this NodeSet's elements
+    # @param ary [[String, Element]] child nodes with which to initialize this NodeSet
+    def initialize(_parent, ary=[])
+      super ary
+      @parent = _parent
+    end
+
+    # @return [HistoryClass] object that observes this NodeSet for changes
+    def history
+      @observer_peers.first.first if @observer_peers and @observer_peers.first.any?
+    end
+
+    # @param index [Fixnum] index of array where old String is to be replaced
+    # @param str [String] replacing String
+    # @return [self] reports old String and index to history
+    def []=(index, str)
+      raise Exception if count_observers < 1
+      old_str = self[index]
+      super(index, str)
+      changed
+      notify_observers(:ChangeText, parent, index, old_str)
+      self
+    end
+  end # class NodeSet < Array
+end # module Duxml

data/lib/duxml/doc.rb

@@ -0,0 +1,26 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/doc/element')
+
+module Duxml
+  class Doc < ::Ox::Document
+    include ElementGuts
+    def initialize(prolog={})
+      super(prolog)
+      self[:version] ||= '1.0'
+      @nodes = NodeSet.new(self)
+      # TODO should also create new metadata!!
+    end
+
+    def write_to(path)
+      s = attributes.collect do |k, v| %( #{k}="#{v}") end.join
+      %(<?xml #{s}?>)+nodes.first.to_s
+      File.write(path, s)
+      self
+    end
+
+    def to_s
+      "#<#{self.class.to_s} @object_id='#{object_id}' @root='#{root.nil? ? '' : root.description}'>"
+    end
+  end # class Document < Element
+end

data/lib/duxml/meta/grammar/pattern/attr_name_pattern.rb

@@ -0,0 +1,36 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../../grammar/pattern')
+
+module Duxml
+  module AttrNamePattern; end
+  # pattern representing relationship between an object and one of its attributes
+  class AttrNamePatternClass < PatternClass
+    include AttrNamePattern
+
+    # @param _subject [Duxml::Element] subject doc
+    # @param _attr_name [String] name of attribute
+    def initialize(_subject, _attr_name)
+      @attr_name = _attr_name
+      super _subject
+    end
+
+    attr_reader :attr_name
+  end
+
+  module AttrNamePattern
+    def relationship
+      'attribute'
+    end
+
+    # @return [Boolean] true if subject does not have the attr_name; false otherwise
+    def abstract?
+      subject[attr_name].nil?
+    end
+
+    def description
+      abstract? ? "#{subject.description} does not have #{relationship} [#{attr_name}]" :
+          "#{subject.description}'s #{relationship} [#{attr_name}]"
+    end
+  end # class AttrNamePattern
+end # module Duxml

data/lib/duxml/meta/grammar/pattern/attr_val_pattern.rb

@@ -0,0 +1,36 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../../grammar/pattern')
+
+module Duxml
+  module AttrValPattern; end
+
+  # pattern representing relationship between an object's attribute and its value
+  class AttrValPatternClass < PatternClass
+    include AttrValPattern
+
+    # @param _subject [Element] subject element
+    # @param _attr_name [String] name of attribute whose value is the object of this pattern
+    def initialize(_subject, _attr_name)
+      @attr_name = _attr_name
+      super _subject
+    end
+
+    attr_reader :subject, :attr_name
+  end
+
+  module AttrValPattern
+    def relationship
+      'value'
+    end
+
+    def description
+      "#{subject.description}'s @#{attr_name} #{relationship} of '#{value}'"
+    end
+
+    # current value of this attribute
+    def value
+      subject[attr_name]
+    end
+  end # class AttrValPattern
+end # module Duxml

data/lib/duxml/meta/grammar/pattern/child_pattern.rb

@@ -0,0 +1,72 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../../grammar/pattern')
+require File.expand_path(File.dirname(__FILE__) + '/../../../ruby_ext/fixnum')
+
+module Duxml
+  module ChildPattern; end
+  # pattern representing relationship between an object and its child
+  class ChildPatternClass < PatternClass
+    include ChildPattern
+
+    # @param _subject [Duxml::Element] parent element
+    # @param _index [Fixnum] index of child
+    def initialize(_subject, _index)
+      @index = _index
+      super _subject
+    end
+
+    alias_method :parent, :subject
+    attr_reader :index
+  end # class ChildPatternClass
+
+  # null child patterns represent and parent child relationship where the child
+  # is required by the Grammar but the element is missing that child
+  class NullChildPatternClass < PatternClass
+    include ChildPattern
+
+    # @param _subject [Element] parent element
+    # @param _missing_child [String] nmtoken for missing child element
+    def initialize(_subject, _missing_child)
+      @missing_child = _missing_child
+      super _subject
+    end
+
+    # @return [-1] class must respond to #index; only NullChildPatternClass is allowed to have a negative index
+    def index
+      -1
+    end
+
+    def relationship
+      'missing child'
+    end
+
+    # @return [String] description of this child pattern
+    def description
+      "#{subject.description} #{relationship} <#{child}>"
+    end
+
+    attr_reader :missing_child
+    alias_method :child, :missing_child
+    alias_method :parent, :subject
+  end
+
+  module ChildPattern
+    # @return [Element] child element
+    def child
+      subject.nodes[index]
+    end
+
+    alias_method :object, :child
+
+    # @return [String] describes relationship between parent and child
+    def relationship
+      "#{(index+1).ordinal_name} #{super}"
+    end
+
+    # @return [String] description of this child pattern
+    def description
+      "#{subject.description}'s #{relationship} #{child.description}"
+    end
+  end
+end # module Duxml

data/lib/duxml/meta/grammar/pattern/text_pattern.rb

@@ -0,0 +1,30 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../../grammar/pattern')
+
+module Duxml
+  module TextPattern; end
+  # pattern representing relationship between an object and its text-only child
+  class TextPatternClass < PatternClass
+    include TextPattern
+
+    # @param _subject [Ox::Element] parent of text node
+    # @param _index [Fixnum] index of text node
+    def initialize(_subject, _index)
+      @index = _index
+      super _subject
+    end
+
+    attr_reader :subject, :index
+  end
+
+  module TextPattern
+    def text
+      subject.nodes[index]
+    end
+
+    def description
+      "#{subject.description}'s #{relationship} is '#{text}'"
+    end
+  end # class ContentPattern
+end # module Duxml

data/lib/duxml/meta/grammar/pattern.rb

@@ -0,0 +1,98 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../../ruby_ext/string')
+
+module Duxml
+  # Patterns represent a relationship between a specific XML Element and
+  # a specific or hypothetical attribute, attribute value, text value or child Element
+  # For example, given an XML Element: '<element attr='value'/>', there exists a valid PatternClass
+  # that represents the relationship betweeen <element> and the attribute value 'value'
+  # There can also exists a hypothetical relationship between <element> and a new child <child/> that
+  # is defined as an allowed child Element in the Rules that apply to this Element.
+  module Pattern; end
+
+  # as an object, a Pattern consists of a subject and may or may not have an object
+  # a Pattern without an object represents a childless empty node with no attributes
+  # this class must be subclassed to be used; there is one for each type of XML relationship
+  # that an Element can have up to one degree of separation, that is, grandparent relationships are not considered
+  # and neither are the attributes of children
+  class PatternClass
+    include Pattern
+    @subject
+
+    # @param subj [Element] specific Element that is the subject of this pattern
+    def initialize(subj)
+      @subject = subj
+    end
+
+    attr_reader :subject
+  end
+
+  module Pattern
+    include Duxml
+
+    # @return [String] nmtoken name of this pattern without namespace prefix e.g. ChildPattern.new(parent, child).name => 'child_pattern'
+    def simple_name
+      name.split(':').last
+    end
+
+    # @return [Boolean] if either subject or object points to a name/type i.e. not an Element
+    def abstract?
+      subject.is_a?(String) or object.nil?
+    end
+
+    # @return [Boolean] if both subject and at least one object point to an actual XML Element
+    def concrete?
+      !abstract?
+    end
+
+    # @return [String] nmtoken name of this pattern e.g. ChildPattern.new(parent, child).name => 'duxml:child_pattern'
+    def name
+      c = self.class.to_s
+      return c.nmtokenize unless c.include?('::')
+      a =  c.split('::')
+      a[-2..-1].collect do |word|
+        word.nmtokenize
+      end.join(':')
+    end
+
+    # returns relationship description as string by subtracting super class name
+    # (e.g. 'pattern' or 'rule') from simple_class
+    # Duxml::ChildrenRule#relationship => 'children'
+    # Duxml::TextPattern#relationship => 'text'
+    # can be overridden if class name does not match human-readable string
+    # @return [String] single word to describe relationship of subject to object
+    def relationship
+      simple_name.split('_').first
+    end
+
+    # @return [String] "#{object.description} is #{relationship} of #{subject.description}"
+    def description
+      "#{object.description} is #{relationship} of #{subject.description}"
+    end
+
+    # @return [Element] will only return non-nil value when pattern represents relationship with a child Element
+    def object
+      return @object if instance_variable_defined?(:@object)
+      instance_variables.each do |var|
+        target = instance_variable_get(var)
+        return target unless target.is_a?(String) or target == subject
+      end
+      nil
+    end
+
+    # @param pattern [Duxml::Pattern] pattern or any subclass object
+    # @return [Fixnum] first applies <=> to subjects, and if equal, applies <=> to objects
+    def <=>(pattern)
+      return 1 unless pattern.respond_to?(:subject)
+      case subject <=> pattern.subject
+        when -1 then
+          -1
+        when 0 then
+          object <=> pattern.object
+        else
+          -1
+      end
+    end # def <=>
+  end # module Pattern
+end # module Duxml