duxml 0.7.2

data/lib/duxml/meta/history.rb

@@ -0,0 +1,88 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/history/add')
+require File.expand_path(File.dirname(__FILE__) + '/history/remove')
+require File.expand_path(File.dirname(__FILE__) + '/history/validate_error')
+require File.expand_path(File.dirname(__FILE__) + '/history/qualify_error')
+require File.expand_path(File.dirname(__FILE__) + '/history/new_attr')
+require File.expand_path(File.dirname(__FILE__) + '/history/change_attr')
+require File.expand_path(File.dirname(__FILE__) + '/history/new_text')
+require File.expand_path(File.dirname(__FILE__) + '/history/change_text')
+require File.expand_path(File.dirname(__FILE__) + '/history/undo')
+require File.expand_path(File.dirname(__FILE__) + '/../doc')
+require 'forwardable'
+
+module Duxml
+  # monitors XML Elements for changes and GrammarClass for errors, recording them and saving to Meta file
+  module History
+    include Duxml
+    include Reportable
+  end
+
+  # as an object, HistoryClass holds events latest first, earliest last
+  # it also has delegators that allow the use of Array-style notation e.g. '[]' and #each to search the history.
+  class HistoryClass
+    include History
+    extend Forwardable
+
+    def_delegators :@nodes, :[], :each
+
+    # @param harsh_or_kind [Boolean] by default harsh i.e. true so that if this History detects an error it will raise an Exception; otherwise not
+    def initialize(harsh_or_kind = true)
+      @nodes = []
+      @strict = harsh_or_kind
+    end
+
+    attr_reader :nodes
+    alias_method :events, :nodes
+  end
+
+  module History
+    # used when creating a new metadata file for a static XML file
+    #
+    # @return [Element] XML element for a new <duxml:history> node
+    def self.xml
+      Element.new(name.nmtokenize).extend self
+    end
+
+    # @return [Boolean] toggles (true by default) whether History will raise exception or tolerate qualify errors
+    def strict?(harsh_or_kind=nil)
+      @strict = harsh_or_kind.nil? ? @strict : harsh_or_kind
+      @strict
+    end
+
+    # @return [ChangeClass, ErrorClass] the latest event
+    def latest
+      events[0]
+    end
+
+    # @return [GrammarClass] grammar that is observing this history's events
+    def grammar
+      @observer_peers.first.first if @observer_peers and @observer_peers.any? and @observer_peers.first.any?
+    end
+
+    # @return [String] shortened self description for debugging
+    def inspect
+      "#<#{self.class.to_s} #{object_id}: @events=#{nodes.size}>"
+    end
+
+    # @return [String] returns entire history, calling #description on each event in chronological order
+    def description
+      "history follows: \n" +
+      events.reverse.collect do |change_or_error|
+        change_or_error.description
+      end.join("\n")
+    end
+
+    # @param type [Symbol] category i.e. class symbol of changes/errors reported
+    # @param *args [*several_variants] information needed to accurately log the event; varies by change/error class
+    def update(type, *args)
+      change_class = Duxml::const_get "#{type.to_s}Class".to_sym
+      change_comp = change_class.new *args
+      @nodes.unshift change_comp
+      changed
+      notify_observers(change_comp) unless change_comp.respond_to?(:error?)
+      raise(Exception, change_comp.description) if strict? && type == :QualifyError
+    end
+  end # module History
+end # module Duxml

data/lib/duxml/meta.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/meta/grammar')
+require File.expand_path(File.dirname(__FILE__) + '/meta/history')
+require File.expand_path(File.dirname(__FILE__) + '/saxer')
+
+module Duxml
+  module Meta
+
+    FILE_EXT = '.duxml'
+  end
+
+  # all XML files ready by Duxml have a metadata file generated with a modified, matching file name
+  # @see #Meta.meta_path
+  class MetaClass
+    include Meta
+
+    # @param grammar_path [String] optional path of grammar file which can be a spreadsheet or Duxml::Grammar file
+    def initialize(grammar_path=nil)
+      @history = HistoryClass.new
+      self.grammar = grammar_path ? Grammar.import(grammar_path) : GrammarClass.new
+      @grammar_path = grammar_path
+    end
+
+    attr_reader :history, :grammar
+  end
+
+  module Meta
+    # @return [Doc] metadata document
+    def self.xml
+      d = Doc.new << (Element.new(name.nmtokenize) << Grammar.xml << History.xml)
+      d.root.grammar[:ref] = @grammar_path if @grammar_path
+      d
+    end
+
+    # @param path [String] path of XML-content file
+    # @return [String] full path of metadata file based on content file's name e.g.
+    #   'design.xml' => '.design.xml.duxml'
+    def self.meta_path(path)
+      dir = File.dirname(path)
+      "#{dir}/.#{File.basename(path)}#{FILE_EXT}"
+    end
+
+    def grammar=(g)
+      @grammar = g.is_a?(GrammarClass) ? g : Grammar.import(g)
+      history.delete_observers if history.respond_to?(:delete_observers)
+      history.add_observer(grammar, :qualify)
+      grammar.add_observer history
+    end
+  end # module Meta
+end # module Duxml

data/lib/duxml/reportable.rb

@@ -0,0 +1,27 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require 'observer'
+
+module Reportable
+  include Observable
+
+  # @param obs [Object] observer to add to this Element as well as its NodeSet
+  def add_observer(obs, sym=nil)
+    super(obs, sym || :update)
+    nodes.add_observer(obs) if self.respond_to?(:nodes) and nodes.respond_to?(:add_observer)
+  end
+
+  private
+
+  # all public methods that alter XML must call #report in the full scope of that public method
+  # in order to correctly acquire name of method that called #report
+  #
+  # @param *args [*several_variants]
+  def report(*args)
+    return nil if @observer_peers.nil?
+    changed
+    new_args = [args.first, self]
+    args[1..-1].each do |a| new_args << a end if args.size > 1
+    notify_observers(*new_args)
+  end
+end

data/lib/duxml/ruby_ext/fixnum.rb

@@ -0,0 +1,56 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+class Fixnum
+  NUM_NAMES = %w(zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen twenty thirty forty fifty sixty seventy eighty ninety)
+  ORDINAL_SUFFIXES = %w(th st nd rd th)
+  ORDINAL_NAMES = %w(zeroth first second third fourth fifth sixth seventh eighth ninth tenth eleventh twelfth)
+
+  # @return [String] short string ordinal e.g. 3.ordinal =? 'third'
+  def ordinal
+    self.to_s + suffix
+  end
+
+  def suffix
+    if self%100 < 4 or self%100 > 20
+      ORDINAL_SUFFIXES[self%10]
+    else
+      ORDINAL_SUFFIXES.first
+    end
+  end
+
+  # @return [String] full name of number e.g. 200058.to_word => 'two-hundred thousand and fifty-eight' for any Fixnum less than a billion
+  def to_word
+    case
+      when self < 21 then NUM_NAMES[self]
+      when self < 100
+        ones = self%10
+        ones_str = ones.zero? ? '' : "-#{ones.to_word}"
+        NUM_NAMES[self/10+18]+ones_str
+      when self < 1000
+        tens = self%100
+        "#{NUM_NAMES[self/100]} hundred #{'and '+(tens).to_word unless tens.zero?}"
+      when self < 1000000
+        remainder = self%1000 < 100 ? "and #{(self%1000).to_word}" : (self%1000).to_word
+        "#{(self/1000).to_word} thousand #{remainder}"
+      when self < 1000000000
+        "#{(self/1000000).to_word} million #{(self%1000000).to_word}"
+      else raise Exception, 'method only supports names for numbers less than 1000000000 i.e. <= 999,999,999'
+    end.strip.gsub(' and zero', '')
+  end
+
+  # @return [String] full name of ordinal number e.g. 4281.ordinal_name => 'four thousand and two-hundred eighty-first'
+  def ordinal_name
+    ones = self%10
+    tens = self%100
+    case
+      when tens.zero? then self.to_word+ORDINAL_SUFFIXES.first
+      when ones.zero? && tens > 10 then self.to_word[-3..-1] + 'tieth'
+      when ones.zero? && tens == 10 then self.to_word+ORDINAL_SUFFIXES.first
+      when tens < 13 then "#{(self-tens).to_word} and #{ORDINAL_NAMES[tens]}"
+      when tens < 20 && tens > 12
+        "#{(self-tens).to_word} and #{NUM_NAMES[tens]}#{ORDINAL_SUFFIXES.first}"
+      when tens-ones != 0 then "#{(self-ones).to_word}-#{ORDINAL_NAMES[ones]}"
+      else "#{(self-ones).to_word} and #{ORDINAL_NAMES[ones]}"
+    end.strip.gsub('zero and ', '').gsub('zero', '')
+  end
+end

data/lib/duxml/ruby_ext/module.rb

@@ -0,0 +1,12 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+class Module
+  def simple_name
+    self.to_s.split('::').last
+  end
+
+  def simple_module
+    a = self.to_s.split('::')
+    a.size > 1 ? a[-2] : 'Module'
+  end
+end

data/lib/duxml/ruby_ext/object.rb

@@ -0,0 +1,14 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/string')
+
+class Object
+  def simple_name
+    self.class.to_s.split('::').last
+  end
+
+  def simple_module
+    a = self.class.to_s.split('::')
+    a.size > 1 ? a[-2] : 'Module'
+  end
+end

data/lib/duxml/ruby_ext/regexp.rb

@@ -0,0 +1,20 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+class Regexp
+  class << self
+    # @return [Regexp] C identifier e.g. ident_ifier0, excluding 'true' and 'false'
+    def identifier
+      /(?:(?!true|false))\b([a-zA-Z_][a-zA-Z0-9_]*)\b/
+    end
+
+    # @return [Regexp] XML NMTOKEN e.g xml:attribute, also-valid, CDATA
+    def nmtoken
+      /(?!\s)([a-zA-Z0-9_\-.:]*)(?!\s)/
+    end
+
+    # @return [Regexp] Ruby constant e.g. Constant, CONSTANT
+    def constant
+      /\b([A-Z][a-zA-Z0-9_]*)\b/
+    end
+  end
+end

data/lib/duxml/ruby_ext/string.rb

@@ -0,0 +1,29 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+require File.expand_path(File.dirname(__FILE__) + '/regexp')
+
+class String
+  # @return [String] converts string into Ruby constant. self must be String with no whitespaces and match Regexp.nmtoken
+  #   'foo-bar'.constantize => 'Foo_bar'
+  #   'foo_bar'.constantize => 'FooBar'
+  def constantize
+    return self if Regexp.constant.match(self)
+    raise Exception unless Regexp.nmtoken.match(self)
+    s = split('_').collect do |word| word.capitalize unless word == '_' end.join.gsub('-', '_')
+    raise Exception unless s.match(Regexp.constant)
+    s
+  end
+
+  # @return [String] does reverse of #constantize e.g.
+  #   'Foo_b'.nmtokenize  => 'foo-bar'
+  #   'FooBar'.nmtokenize => 'foo_bar'
+  def nmtokenize
+    split('::').collect do |word|
+      word.gsub(/(?!^)[A-Z_]/) do |match|
+        case match
+          when '_' then '-'
+          else "_#{match.downcase}"
+        end
+      end.downcase
+    end.join(':')
+  end
+end # class String

data/lib/duxml/saxer.rb

@@ -0,0 +1,71 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/doc')
+
+module Duxml
+  module Saxer
+    @io
+
+    attr_accessor :io
+    # @param path [String] path of file to parse
+    # @return [Doc] finished document with each Element's line and column info added
+    def sax(path, obs=nil)
+      io = File.open path
+      saxer = DocuLiner.new(Duxml::Doc.new, obs)
+      Ox.sax_parse(saxer, io, {convert_special: true, symbolize: false})
+      doc = saxer.cursor
+      doc.add_observer obs if obs
+      doc
+    end
+
+    class DocuLiner < ::Ox::Sax
+      # @param doc [Ox::Document] document that is being constructed as XML is parsed
+      # @param _observer [Object] object that will observe this document's content
+      def initialize(doc, _observer)
+        @cursor_stack = [doc]
+        @line = 0
+        @column = 0
+        @observer = _observer
+      end
+
+      attr_reader :line, :column, :observer
+
+      def cursor
+        cursor_stack.last
+      end
+
+      attr_accessor :cursor_stack
+
+      def start_element(name)
+        cursor << Duxml::Element.new(name, line, column)
+        cursor_stack << cursor.nodes.last
+      end
+
+      def attr(name, val)
+        cursor[name] = val
+      end
+
+      def text(str)
+        cursor << str
+      end
+
+      def end_element(name)
+        cursor.add_observer(observer) if observer
+        @cursor_stack.pop
+      end
+
+      private
+
+      def doc
+        cursor_stack.first
+      end
+
+      def location_key
+        @alocation.inject do |a, index|
+          a ||= ""
+          a << index.to_s
+        end
+      end
+    end # class DocuLiner < ::Ox::Sax
+  end # module Saxer
+end # module Duxml

data/lib/duxml.rb

@@ -0,0 +1,97 @@
+# Copyright (c) 2016 Freescale Semiconductor Inc.
+
+require File.expand_path(File.dirname(__FILE__) + '/duxml/saxer')
+require File.expand_path(File.dirname(__FILE__) + '/duxml/meta')
+
+module Duxml
+  DITA_GRAMMAR = File.expand_path(File.dirname(__FILE__) + '/../xml/dita_grammar.xml')
+  include Saxer
+  include Meta
+
+  # path to XML file
+  @file
+  # current document
+  @doc
+  # meta data document
+  @meta
+
+  attr_reader :meta, :file, :doc
+
+  # @param file [String, Doc] loads or creates given file or document 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 [Duxml::Meta] combined Object tree from metadata root (metadata and content's XML documents are kept separate)
+  def load(_file, grammar_path=nil)
+    if _file.is_a?(String) and File.exists?(_file)
+      @file = _file
+    else
+      @file = "#{(_file.respond_to?(:name) ? _file.name : _file.class.to_s) + _file.object_id.to_s}"
+      File.write file, ''
+    end
+
+    set_metadata!(grammar_path)
+    set_doc!
+  end # def load
+
+  # @param file [String] creates new XML file at given path
+  # @param content [Doc, Element] XML content with which to initialize new file
+  def create(file, content=nil)
+    File.write(file, content.to_s)
+    @doc = content.is_a?(Doc) ? content : Doc.new
+  end
+
+  # @param file [String] saves current content XML to given file path (Duxml@file by default)
+  def save(file)
+    meta_path = Meta.meta_path(file)
+    unless File.exists?(meta_path)
+      File.new meta_path, 'w+'
+      File.write(meta_path, Meta.xml)
+    end
+  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 [*several_variants] @see #load
+  # @return [Boolean] whether file passed validation
+  def validate(*args)
+    load(*args) unless args.empty?
+    raise Exception, "grammar not defined!" unless meta.grammar.defined?
+    raise Exception, "document not loaded!" unless doc.root
+    results = []
+    doc.root.traverse do |n| results << meta.grammar.validate(n) unless n.is_a?(String) end
+    !results.any? do |r| !r end
+  end # def validate
+
+  # @return [Nokogiri::XML::RelaxNG] current metadata's grammar as a relaxng file
+  def relaxng
+    #meta.grammar.relaxng
+  end
+
+  private
+
+  # @return [Doc] @doc is set to either file given by user or new Doc
+  def set_doc!
+    @doc ||= if file.nil?
+               f = Doc.new
+               f.add_observer meta.history
+               f
+             else
+               f = File.open file
+               sax(f, meta.history)
+             end
+  end
+
+  # @return [MetaClass] @meta is set to either file extrapolated from path of XML-content file or new MetaClass
+  def set_metadata!(grammar_path=nil)
+    meta_path = Meta.meta_path(file)
+    if file and File.exists?(meta_path)
+      @meta = sax(File.open(meta_path)).root
+      meta.grammar=grammar_path unless grammar_path.nil? or meta.grammar.defined?
+    else
+      @meta = MetaClass.new(grammar_path)
+    end
+    meta
+  end
+end # module Duxml