duxml 0.7.2

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

@@ -0,0 +1,59 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/pattern')
+require File.expand_path(File.dirname(__FILE__) + '/../../reportable')
+
+module Duxml
+  # scans DTD statements for XML rule operators
+  Struct.new 'Scanner', :match, :operator
+
+  # contains methods to apply Duxml::RuleClass to XML edit or validate events
+  module Rule
+    include Reportable
+  end
+
+  # as an object, Rules consist of a subject, representing the XML Element, and a statement representing the Rule's logic
+  # this class cannot be used alone and is rather subclassed, one for each type of possible XML changes
+  class RuleClass < PatternClass
+    include Rule
+
+    # @param subj [String] NMTOKEN name of element this rule applies to
+    # @param _statement [String, Regexp] string statement of rule in DTD declaration form or Regexp
+    def initialize(subj, _statement)
+      @statement = _statement
+      @object = nil
+      super subj
+    end
+
+    attr_reader :statement, :object
+  end
+
+  module Rule
+    # Duxml::Rule's #qualify is only used to report errors found by its subclasses' #qualify methods
+    # @param change_or_pattern [Duxml::Pattern, Duxml::Change] Change or Pattern to be reported for Rule violation
+    # @return [Boolean] always false; this method should always be subclassed to apply that specific rule type's #qualify
+    def qualify(change_or_pattern)
+      type = (change_or_pattern.respond_to?(:time_stamp)) ? :QualifyError : :ValidateError
+      report(type, change_or_pattern)
+      false
+    end
+
+    # @return [HistoryClass] history to which this rule will report errors
+    def history
+      @observer_peers.first.first if @observer_peers.any? and @observer_peers.first.any?
+    end
+
+    # @param change_or_pattern [Duxml::Change, Duxml::Pattern] change or pattern that rule may apply to
+    # @return [Boolean] whether this rule does in fact apply
+    def applies_to?(change_or_pattern)
+      pattern_type = change_or_pattern.subject.name
+      subject == pattern_type
+    end
+
+    # @return [String] default description for a Rule
+    def description
+      statement_str = (statement.is_a?(String) ? statement : statement.inspect).gsub('\b','')
+      %(#{relationship.capitalize} Rule that <#{subject}>'s #{relationship} must match '#{statement_str}')
+    end
+  end # module Rule
+end # module Duxml

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

@@ -0,0 +1,35 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require 'rubyXL'
+
+module Duxml
+  # contains helper methods to convert spreadsheet of DTD rules into Duxml::Rules
+  module Spreadsheet
+    private
+  # @param path [String] spreadsheet file
+    def self.sheet_to_xml(path)
+      worksheet = RubyXL::Parser.parse(path)[0]
+      attr_val_rule_hash = {}
+      g = GrammarClass.new
+      worksheet.each_with_index do |row, index|
+        next if index == 0
+        break if row[3].nil? || row[4].nil?
+        element_name = row[3].value
+        statement_str = row[4].value
+        g << ChildrenRuleClass.new(element_name, statement_str)
+        attribute_rules = row[5].value.split(/\n/)
+        attribute_rules.each_with_index do |rule, i|
+          next if i == 0 or rule.empty?
+          attr_name, value_expr, attr_req = *rule.split
+          next if [attr_name, value_expr, attr_req].any? do |s| s.empty? or s.match(/\w/).nil? end
+          g << AttrsRuleClass.new(element_name, attr_name, attr_req)
+          unless attr_val_rule_hash[attr_name]
+            g << ValueRuleClass.new(attr_name, value_expr)
+            attr_val_rule_hash[attr_name] = true
+          end
+        end # attribute_rules.each_with_index
+      end # worksheet.each_with_index
+      g
+    end # def sheet_to_xml(path)
+  end # module Spreadsheet
+end # module Duxml

data/lib/duxml/meta/grammar.rb

@@ -0,0 +1,134 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../reportable')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/spreadsheet')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/pattern_maker')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/rule/children_rule')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/rule/attrs_rule')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/rule/value_rule')
+require File.expand_path(File.dirname(__FILE__) + '/../doc/lazy_ox')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/rule/text_rule')
+require File.expand_path(File.dirname(__FILE__) + '/grammar/relax_ng')
+require 'forwardable'
+
+module Duxml
+  # module shares name with <grammar> to activate its methods when that XML Element is encountered in a Meta file
+  module Grammar
+    include Reportable
+    include Duxml
+    include Spreadsheet
+    include PatternMaker
+    include LazyOx
+    include RelaxNG
+  end
+  # contains Duxml::Rules and can apply them by validating XML or qualifying user input
+  # reporting Duxml::Errors to History as needed
+  class GrammarClass
+    extend Forwardable
+    include Grammar
+
+    # @param rules [[RuleClass]] optional, can initialize grammar with rules
+    def initialize(rules=[])
+      @rules = rules
+    end
+
+    def_delegators :@rules, :<<, :[], :each
+    attr_reader :rules
+    alias_method :nodes, :rules
+  end
+
+  module Grammar
+    # @param path [String] path of grammar file; can be in .xlsx, .csv or Duxml GrammarClass file
+    # @return [GrammarClass, Element] XML Element named <grammar> and GrammarClass object are functionally equivalent
+    def self.import(path)
+      if %w(.xlsx .csv).include?(File.extname path)
+        doc = Spreadsheet.sheet_to_xml path
+        File.write(File.basename(path)+'.xml', Ox.dump(doc)) #TODO make optional!
+        doc
+      else
+        Ox.parse_obj(File.read path)
+      end
+    end
+
+    # @return [Element] returns self as XML element e.g. '<duxml:grammar/>'
+    def self.xml
+      Element.new(name.nmtokenize).extend self
+    end
+
+    # @return [History] history that this grammar is currently reporting to
+    def history
+      @observer_peers.first.first if @observer_peers and @observer_peers.any? and @observer_peers.first.any?
+    end
+
+    # @return [Boolean] whether or not any rules have been defined yet in this grammar
+    def defined?
+      !rules.empty?
+    end
+
+    # @param obj [Object] object that will observe this grammar's rules, usually the History
+    def add_observer(obj, sym=nil)
+      super(obj, sym || :update)
+      @rules.each do |r| r.add_observer(obj, :update)end
+    end
+
+    # @return [String] lists XML schema and content rules in order of precedence
+    def description
+    "grammar follows: \n" +
+        rules.collect do |change_or_error|
+          change_or_error.description
+        end.join("\n")
+    end
+
+    # @return [String] formatted to appear in tight spaces e.g. debugger
+    def inspect
+      "#<#{self.class.to_s} #{object_id}: @rules=#{rules.size}>"
+    end
+
+    # @return [String] 'grammar'
+    def name
+      'grammar'
+    end
+
+    # @param node [Duxml::Object] applies grammar rules to all relationships of the given object
+    # @result [Boolean] whether all rules qualified
+    def validate(node)
+      rels = get_relationships(node)
+      results = rels.collect do |rel|
+        qualify rel
+      end
+      any_disqualified = results.any? do |qualified| !qualified end
+      !any_disqualified
+    end # def validate
+
+    # @param change_or_pattern [Duxml::Change, Duxml::Pattern] applies applicable rule type and subject
+    #   to given change_or_pattern and generates errors when disqualified
+    # @return [Boolean] false if any rule disqualifies; true if they all pass
+    def qualify(change_or_pattern)
+      return true unless self.defined?
+      rules = get_rule(change_or_pattern)
+
+      # define behaviors for when there are no rules applying to a given pattern
+      if rules.empty?
+
+        if change_or_pattern.respond_to?(:text) or
+            change_or_pattern.respond_to?(:value) or
+            change_or_pattern.subject.is_a?(Doc)
+          return true
+        end
+        report(:ValidateError, change_or_pattern)
+        return false
+      end
+      results = rules.collect do |rule|
+        rule.qualify change_or_pattern
+      end
+      !results.any? do |qualified| !qualified end
+    end # def qualify
+
+    # @param change_or_pattern [Duxml::Change, Duxml::Pattern] change or pattern to be qualified
+    # @return [Array[Duxml::Rule]] rules that match the pattern type (e.g. :change_content => :content_rule)
+    #   and subject (e.g. change_or_pattern.subject.type => 'blobs' && rule.subject => 'blobs')
+    def get_rule(change_or_pattern)
+      rules.select do |rule| rule.applies_to?(change_or_pattern) end
+    end # def get_rules
+  end # module Grammar
+end # module Duxml

data/lib/duxml/meta/history/add.rb

@@ -0,0 +1,36 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module Add; end
+
+  # created when an doc gains a child
+  class AddClass < ChangeClass
+    include Add
+
+    def initialize(_subject, _index)
+      super _subject
+      @index = _index
+    end
+
+    alias_method :parent, :subject
+    attr_reader :subject, :index
+  end
+
+  module Add
+    def description
+      %(#{super} #{child.description} added to #{parent.description}.)
+    end
+
+    def parent
+      subject
+    end
+
+    def child
+      subject.nodes[index]
+    end
+
+    alias_method :object, :child
+  end # class Add
+end # module Duxml

data/lib/duxml/meta/history/change.rb

@@ -0,0 +1,71 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../grammar/pattern')
+
+module Duxml
+  module Change; end
+  # do not use - only for subclassing
+  # changes represent events i.e. patterns with a fixed position in time,
+  # and can include qualification and validation errors
+  class ChangeClass < PatternClass
+    include Change
+
+    @time_stamp
+
+    # all subclasses of Change must call this super method or implement the same function within their #initialize
+    #
+    # @param _subject [Duxml::Element] parent doc affected by change
+    def initialize(_subject, *args)
+      super _subject
+      @time_stamp = Time.now
+      args.each do |arg|
+        if arg.is_a?(Duxml::Element)
+          @object = arg
+          break
+        end
+      end
+    end
+
+    attr_reader :time_stamp
+  end # class ChangeClass < PatternClass
+
+  module Change
+    def abstract?
+      false
+    end
+
+    # @return [String] gives its time stamp
+    def description
+      "at #{time_stamp}#{line_expr}:"
+    end
+
+    # @return [-1,0,1,nil] compares dates of changes
+    def <=>(obj)
+      return nil unless obj.is_a?(Duxml::Change)
+      date <=> obj.date
+    end
+
+    # @return [Fixnum] line number of changed object; -l if not applicable
+    def line
+      case
+        when object.respond_to?(:line) && object.line.is_a?(Numeric) && object.line >= 0
+          object.line
+        when object.respond_to?(:object) && object.object.respond_to?(:line) && object.object.line.is_a?(Numeric) && object.object.line >= 0
+          object.object.line
+        when object.respond_to?(:subject) && object.subject.respond_to?(:line) && object.subject.line.is_a?(Numeric) && object.subject.line >= 0
+          object.subject.line
+        when subject.respond_to?(:line) && subject.line.is_a?(Numeric) && subject.line >= 0
+          subject.line
+        else
+          -1
+      end
+    end
+
+    private
+
+    # @return [String] string equivalent of object's line number
+    def line_expr
+      line >= 0 ? " on line #{line.to_s}" : ''
+    end
+  end # class Change
+end # module Duxml

data/lib/duxml/meta/history/change_attr.rb

@@ -0,0 +1,34 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module ChangeAttr; end
+
+  # created when Element has an attribute already and its value has been changed
+  class ChangeAttrClass < ChangeClass
+    include ChangeAttr
+
+    # @param _subject [Duxml::Element] parent doc whose attribute changed
+    # @param _attr_name [String] name of the changed attribute
+    # @param _old_value [String] old attribute value
+    def initialize(_subject, _attr_name, _old_value)
+      super _subject
+      @attr_name, @old_value = _attr_name, _old_value
+    end
+
+    attr_reader :attr_name, :old_value
+  end # class ChangeAttributeClass
+
+  module ChangeAttr
+    # @return [String] new value of attribute
+    def value
+      subject[attr_name]
+    end
+
+    # @return [String] self description
+    def description
+      "#{super} #{subject.description}'s @#{attr_name} changed value from '#{old_value}' to '#{value}'."
+    end
+  end # module ChangeAttribute
+end # module Duxml

data/lib/duxml/meta/history/change_text.rb

@@ -0,0 +1,33 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module ChangeText; end
+  # created when doc has text and text has been changed
+  class ChangeTextClass < ChangeClass
+    include ChangeText
+
+    # @param _subject [Duxml::Element] parent doc whose text has changed
+    # @param _index [Fixnum] index of parent's nodes that text is found at
+    # @param _old_text [String] string that was replaced
+    def initialize(_subject, _index, _old_text)
+      super _subject
+      @index, @old_text = _index, _old_text
+    end
+
+    attr_reader :index, :old_text
+  end
+
+  module ChangeText
+    # @return [String] self description
+    def description
+      "#{super} #{subject.description}'s text at index #{index} changed from '#{old_text}' to '#{text}'."
+    end
+
+    # @return [String] new content (subsequent changes may mean this new content no longer exists in its original form!)
+    def text
+      subject.nodes[index]
+    end
+  end # module ChangeText
+end # module Duxml

data/lib/duxml/meta/history/error.rb

@@ -0,0 +1,25 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module Error
+    def error?
+      true
+    end
+  end # class Error
+
+  # do not use except to subclass
+  class ErrorClass < ChangeClass
+    include Error
+
+    # @param _rule [Rule] rule that was violated
+    # @param _change_or_pattern [ChangeClass, PatternClass] can be triggered by a change or a pattern found in a static document
+    def initialize(_rule, _change_or_pattern)
+      super(_rule)
+      @object = _change_or_pattern
+    end
+    alias_method :rule, :subject
+  end
+
+end # module Duxml

data/lib/duxml/meta/history/new_attr.rb

@@ -0,0 +1,33 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module NewAttr; end
+
+    # created when doc gains a new attribute
+  class NewAttrClass < ChangeClass
+    include NewAttr
+
+    # @param _subject [Duxml::Element] parent doc
+    # @param _attr_name
+    def initialize(_subject, _attr_name)
+      super(_subject)
+      @attr_name = _attr_name
+    end
+
+    attr_reader :attr_name
+  end
+
+  module NewAttr
+    # @return [String] value of the new attribute
+    def value
+      subject[attr_name]
+    end
+
+    # @return [String] self description
+    def description
+      "#{super} #{subject.description} given new attribute '#{attr_name}' with value '#{value}'."
+    end
+  end # module NewAttribute
+end # module Duxml

data/lib/duxml/meta/history/new_text.rb

@@ -0,0 +1,37 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module NewText; end
+
+  # created when object had no children or text and text has been added
+  class NewTextClass < ChangeClass
+    include NewText
+
+    # @param _subject [Duxml::Element] doc that has gained new text
+    # @param _index [Fixnum] index of new text node
+    def initialize(_subject, _index)
+      super _subject
+      @index = _index
+    end
+
+    attr_reader :index
+  end
+
+  module NewText
+    def text
+      subject.nodes[index]
+    end
+    alias_method :object, :text
+
+    # @return [String] self description
+    def description
+      "#{super} #{subject.description} given new text '#{text}'."
+    end
+
+    def line_expr
+      subject.line < 0 ? '' : " on line #{subject.line}"
+    end
+  end # class NewContent
+end # module Duxml

data/lib/duxml/meta/history/qualify_error.rb

@@ -0,0 +1,22 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/error')
+
+module Duxml
+  module QualifyError; end
+
+  # created when grammar detects error from user input
+  class QualifyErrorClass < ErrorClass
+    include QualifyError
+
+    alias_method :bad_change, :object
+  end
+
+  module QualifyError
+
+    def description
+      rule_str = rule.respond_to?(:validate) ? 'not allowed by this Grammar' : "violates #{rule.description}"
+      "Qualify Error #{super} #{bad_change.description} #{rule_str}."
+    end
+  end # module QualifyError
+end # module Duxml

data/lib/duxml/meta/history/remove.rb

@@ -0,0 +1,28 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/change')
+
+module Duxml
+  module Remove; end
+
+  # created when doc loses a child
+  class RemoveClass < ChangeClass
+    include Remove
+    # @param _subject [Dux::Element] parent doc that lost child
+    # @param _child [Dux::Element] removed child; it gets added as child of this Remove object so it never actually goes away
+    def initialize(_subject, _child)
+      super(_subject)
+      @removed = _child
+    end
+
+    attr_reader :removed
+    alias_method :object, :removed
+  end
+
+  module Remove
+    # @return [String] describes removal event
+    def description
+      %(#{super} #{removed.description} removed from #{subject.description}.)
+    end
+  end # module Remove
+end # module Duxml

data/lib/duxml/meta/history/undo.rb

@@ -0,0 +1,24 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/../grammar/pattern')
+
+module Duxml
+  # TODO NOT IMPLEMENTED YET!!!
+  module Undo; end
+
+  # created when a previous change is undone
+  class UndoClass < ChangeClass
+    include Undo
+  end
+
+  module Undo
+    def description
+      "#{super} change '#{subject.id}' undone."
+    end
+
+    # returns previous change instance that was undone
+    def undone_change
+      self[:change]
+    end
+  end
+end # module Duxml

data/lib/duxml/meta/history/validate_error.rb

@@ -0,0 +1,21 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/error')
+
+module Duxml
+  module ValidateError; end
+
+  # created when grammar detects error from file
+  class ValidateErrorClass < ErrorClass
+    include ValidateError
+
+    alias_method :bad_pattern, :object
+  end
+
+  module ValidateError
+    def description
+      rule_str = rule.respond_to?(:validate) ? 'not allowed by this Grammar' : "violates #{rule.description}"
+      "Validate Error #{super} #{bad_pattern.description} #{rule_str}."
+    end
+  end # module ValidateError
+end # module Duxml