rtml 1.2.2 → 2.0.0.alpha.1

data/lib/rtml/reverse_engineering/simulator/casting.rb

@@ -0,0 +1,9 @@
+module Rtml::ReverseEngineering::Simulator::Casting
+  # Returns an instance of +Rtml::ReverseEngineering::Simulator+ with self as the initialization argument.
+  def to_tml_simulator
+    Rtml::ReverseEngineering::Simulator.new(self)
+  end
+
+  alias to_rtml_simulator to_tml_simulator
+  alias to_simulator to_tml_simulator
+end

data/lib/rtml/reverse_engineering/simulator/snapshot.rb

@@ -0,0 +1,18 @@
+# This class is used to contain a single +screen+ element (an instance of Hpricot::Elem) as well as any variable
+# assignments that have been made. Basically, it is simply used by +Rtml::ReverseEngineering::Simulator+ to check
+# for circular pathways. If two identical snapshots would be created, then it stands to reason that the resultant
+# pathways for those two snapshots will also be identical. If you're following a path and creating snapshots at every
+# step of the way, and two snapshots match, then using that logic, those two snapshots would indicate a circular
+# pathway. (It comes down to either that, or waiting to catch a stack overflow error, which is less than optimal.)
+#
+class Rtml::ReverseEngineering::Simulator::Snapshot
+  attr_reader :screen, :variables
+
+  def initialize(screen, variables)
+    @screen, @variables = screen, variables.dup
+  end
+
+  def ==(other_snapshot)
+    @screen == other_snapshot.screen && variables == other_snapshot.variables
+  end
+end

data/lib/rtml/reverse_engineering/simulator/variable_lookup.rb

@@ -0,0 +1,32 @@
+module Rtml::ReverseEngineering::Simulator::VariableLookup
+  # Checks a value to see if it references a TML variable; if so, it resolves that variable into its value;
+  # otherwise, the original value is returned.
+  def resolve(value, all_variables, known_variable_types)
+    if value =~ /^tmlvar:(.*)$/
+      lookup_variable_value($~[1], all_variables, known_variable_types)
+    else
+      value
+    end
+  end
+
+  # Finds the variable in the all_variables hash whose name matches the specified name (string or symbol), and then
+  # returns its value. If that value is an instance of +Rtml::ReverseEngineering::Simulator::VariableValue+, calls
+  # the #value method on that object instead.
+  #
+  # If the variable is not found, then a default value will be returned depending on its type.
+  def lookup_variable_value(name, all_variables, known_variable_types)
+    all_variables.each do |var_name, varval|
+      if var_name.to_s == name
+        return(varval.kind_of?(Rtml::ReverseEngineering::Simulator::VariableValue) ? varval.value : varval)
+      end
+    end
+    default_value_for_type(known_variable_types[name])
+  end
+
+  def default_value_for_type(type)
+    case type
+      when :integer then 1
+      else "generic"
+    end
+  end
+end

data/lib/rtml/reverse_engineering/simulator/variable_value.rb

@@ -0,0 +1,105 @@
+# Used by +Rtml::ReverseEngineering::Simulator+ to track the value of a variable. Attempts
+# to build a logical value by processing the setvar's :lo, :op and :ro attributes. References to
+# other variables are automatically resolved. References to nonexistent values assume built-in variables
+# and assign generic values to them.
+#
+# Implements a #== method to see if one variable's value is equal to another's, though this may not always be accurate.
+#
+class Rtml::ReverseEngineering::Simulator::VariableValue
+  include Rtml::ReverseEngineering::Simulator::VariableLookup
+  attr_reader :value
+
+  def initialize(setvar, all_variables, known_variable_types)
+    @setvar, @all_variables, @known_variable_types = setvar, all_variables, known_variable_types
+    @value = setvar.to_s
+
+    %w(lo op ro).each { |i| instance_variable_set("@#{i}", resolve(self.send(i), all_variables, known_variable_types)) }
+    catch(:done) do
+      check_for_assignment
+      check_for_operation
+    end
+
+    do_casting
+    check_boundaries
+  end
+
+  def ==(other)
+    self.value == other.value
+  end
+
+  private
+  attr_reader :setvar, :all_variables, :known_variable_types
+
+  def type
+    @type ||= known_variable_types[setvar['name']]
+  end
+
+  def check_boundaries
+    case type
+      when :integer
+        unless (-999999999..999999999).include? @value
+          raise RulesViolationError, "TML numbers must be no more than 9 digits in length: #{@value}"
+        end
+    end
+  end
+
+  def do_casting
+    @value = case type
+      when :integer then value.to_i
+      else value.to_s
+    end
+  end
+
+  def check_for_operation
+    unless setvar['op'].blank?
+      method_name = "perform_operation_#{setvar['op']}"
+      @value = self.send(method_name)
+      throw :done
+    end
+  rescue NoMethodError
+    raise Rtml::Error::InvalidOperation
+  end
+
+  def check_for_assignment
+    if setvar['op'].blank? && !setvar['lo'].blank?
+      @value = setvar['lo']
+      throw :done
+    end
+  end
+
+  def lo; @lo ||= setvar['lo']; end
+  def op; @op ||= setvar['op']; end
+  def ro; @ro ||= setvar['ro']; end
+
+  def perform_operation_plus
+    case type
+      when :integer then lo.to_i + ro.to_i
+      when :string  then lo.to_s + ro.to_s
+      when :date then "#{lo.to_s} + #{ro.to_s}"
+      else raise Rtml::Errors::InvalidOperation
+    end
+  end
+
+  def perform_operation_minus
+    case type
+      when :integer then lo.to_i - ro.to_i
+      when :string  then lo.to_s[0..-(ro.to_i+1)]
+      when :date then "#{lo.to_s} - #{ro.to_s}"
+      else raise Rtml::Errors::InvalidOperation
+    end
+  end
+
+  def perform_operation_number
+    case type
+      when :integer then lo.split(/;/).length
+      else raise Rtml::Errors::InvalidOperation
+    end
+  end
+
+  def perform_operation_item
+    case type
+      when :string then lo.split(/;/)[ro.to_i]
+      else raise Rtml::Errors::InvalidOperation
+    end
+  end
+end

data/lib/rtml/rules/dom_ruleset.rb

@@ -0,0 +1,166 @@
+class Rtml::Rules::DomRuleset
+  def initialize
+    @tags = HashWithIndifferentAccess.new
+    @root = nil
+    @order = HashWithIndifferentAccess.new
+  end
+
+  def freeze
+    super
+    @tags.freeze
+    @root.freeze
+    @order.freeze
+    self
+  end
+
+  # Loads the ruleset from a file.
+  def parse(file)
+    instance_eval File.read(file), file, 1
+    self
+  end
+
+  # Loads the ruleset from a file.
+  def self.parse(file)
+    self.new.parse(file)
+  end
+
+  # Returns the tag with the specified name, or nil if it can't be found
+  def tag_rules(name)
+    return nil unless tags.include?(name)
+    tag(name)
+  end
+
+  # If a parent and children are supplied, the parent element may contain the specified children. This does not
+  # enforce order.
+  # If a block is supplied, notation can be simplified.
+  #
+  # If a parent is supplied, the valid children for that parent are returned.
+  # If no parent is supplied, nil is returned.
+  #
+  # A few options are also allowed:
+  #   :minimum => the minimum number of children, 0 for no minimum
+  #   :maximum => the maximum number of children, 0 for no maximum
+  #
+  # Examples:
+  #   ruleset.children :head, :base, :link, :defaults # [:base, :link, :defaults] are valid children of :head
+  #
+  #   # Does the same thing:
+  #   ruleset.children do
+  #     head :base, :link, :defaults
+  #   end
+  #
+  #   # Retrieve the array of valid children for :head
+  #   ruleset.children(:head)
+  #
+  def children(parent = nil, *children, &block)
+    r = nil
+    if parent # make sure all tags are registered
+      options = children.extract_options!
+      tags = tag(parent, *children)
+      parent_tag = tags.shift
+      parent_tag.child_tags << (children.flatten.collect { |i| i.to_s } + [options]) unless tags.empty?
+      r = parent_tag.children
+    end
+    if block_given?
+      proxy_into(:children).new(self).instance_eval &block
+    end
+    r
+  end
+
+  # Creates a proxy class for the specified method.
+  def proxy_into(method_name)
+    @proxy_classes ||= HashWithIndifferentAccess.new
+    return @proxy_classes[method_name] if @proxy_classes[method_name]
+    klass = Class.new
+    line = __LINE__ + 2
+    code = <<-end_code
+      def initialize(parent)
+        @parent = parent
+        # Proxy known tags in case they clash with Ruby methods
+        @parent.tags.each do |tag|
+          line = __LINE__ + 2
+          kode = <<-end_kode
+            def \#{tag}(*args, &block)
+              @parent.#{method_name} :\#{tag}, *args, &block
+            end
+          end_kode
+          instance_eval kode, __FILE__, line
+        end
+      end
+      def method_missing(name, *args, &block) @parent.#{method_name} name, *args, &block; end
+    end_code
+    klass.class_eval code, __FILE__, line
+    @proxy_classes[method_name] = klass
+  end
+
+  # If parent and children are supplied, the order of the children within the parent element will be enforced.
+  # If a block is supplied, notation can be simplified.
+  #
+  # If a parent is supplied, then the order of its children is returned.
+  # If no parent is supplied, then nil is returned.
+  #
+  # Examples:
+  #   ruleset.order :head, :base, :link, :defaults # order [:base, :link, :defaults] beneath :head
+  #   
+  #   # Does the same thing:
+  #   ruleset.order do
+  #     head :base, :link, :defaults
+  #   end
+  #
+  #   # Retrieve the order of :head
+  #   ruleset.order(:head)
+  #
+  def order(parent = nil, *children, &block)
+    if parent # make sure all tags are registered
+      parent_tag = tag(parent, *children).first
+      parent_tag.order.concat children.flatten.collect { |i| i.to_s }
+    end
+    if block_given?
+      proxy_into(:order).new(self).instance_eval &block
+    end
+    return tag(parent).order if parent
+    return nil
+  end
+
+  # Declares one or more tags. If a tag is used that has not been previously declared, it will be
+  # added automatically. Returns an array of all added tags, or the tag itself if there was only one.
+  #
+  # If no arguments are specified, nothing happens and an array of all registered tags is returned.
+  def tag(*value)
+    return @tags if value.empty?
+    ts = []
+    value.flatten.each do |t|
+      if @tags.key?(t) || !frozen?
+        ts << (@tags[t] ||= Rtml::Rules::DomTag.new(t.to_s))
+      end
+    end
+    ts.length == 1 ? ts.first : ts
+  end
+
+  def all_tag_names
+    tags.collect { |a| a[0] }
+  end
+
+  alias tags tag
+
+  # Returns true if the specified String or Symbol represents a root tag.
+  def root?(name)
+    name.to_s == @root
+  end
+
+  # Returns true if the specified String or Symbol represents a tag.
+  def tag?(name)
+    tags.collect { |t| t.name }.include?(name.to_s)
+  end
+
+  # Specifies a root tag. If a root tag has already been specified, an error will be raised.
+  # If no root tag is specified, the current root tag is returned instead, or nil if there is none.
+  def root(*value)
+    unless value.empty?
+      raise Rtml::Errors::MultipleRootsError, "Can only have one root element" if @root
+      @root = value.shift.to_s
+      tag @root
+    end
+    @root
+  end
+end

data/lib/rtml/rules/dom_tag.rb

@@ -0,0 +1,43 @@
+class Rtml::Rules::DomTag
+  attr_reader :name
+  attr_reader :child_tags
+  attr_reader :order
+
+  def initialize(name)
+    @name = name
+    @child_tags = []
+    @order = []
+  end
+
+  def children
+    child_tags.flatten.select { |t| t.kind_of?(String) }
+  end
+
+  def minimum(child_name) option_for_child(child_name, :minimum) end
+  def maximum(child_name) option_for_child(child_name, :maximum) end
+
+  # compatiblity with Array; see Tml::Dom::Ruleset
+  def first
+    self
+  end
+
+  def ==(a)
+    a.kind_of?(String) ? a == name : a.name == name
+  end
+
+  def to_s
+    name
+  end
+
+  private
+  def option_for_child(child_name, key)
+    child_tags.each do |children|
+      charr = children.dup
+      options = charr.extract_options!
+      unless charr.select { |i| i == child_name }.empty?
+        return options[key].to_i
+      end
+    end
+    raise "Element with name '#{child_name}' is not allowed within parent '#{name}'"
+  end
+end

data/lib/rtml/rules/dom_validation.rb

@@ -0,0 +1,162 @@
+module Rtml::Rules::DomValidation
+  # Validates that the TML produced by the given string or Rtml::Document is well-formed and syntactically valid
+  def validate_tml(doc)
+    if doc.kind_of?(String) || doc.kind_of?(Symbol)
+      tag = Hpricot::XML(doc.respond_to?(:to_tml) ? doc.to_tml : doc).root
+    else tag = doc
+    end
+    validate_tml_tag(tag)
+  end
+
+  # Validates that the TML produced by the specified tag matches the overall structure. Structure can be
+  # a symbol, an array of symbols, or a hash of symbols and arrays of symbols. Only tag names are matched.
+  # The tag may contain additional tags, so this method should be used to check that the tag contains
+  # *at least* the given structure, and not to check for *at most* the given structure.
+  #
+  # Example:
+  #   validate_tml_dom("<tml><screen id='init'><next uri='#main' /><display> . . . </display></screen></tml>",
+  #                    :tml => { :screen => [ :next, :display ] }) #=> true
+  def validate_tml_dom(tag, structure)
+    structure = ignore_root_tag(structure)
+    tag = root_hpricot_tag(tag)
+
+    matches = []
+    case structure
+      when String, Symbol then matches.concat validate_tml_dom_with_string(tag, structure)
+      when Array          then matches.concat validate_tml_dom_with_array(tag, structure)
+      when Hash           then matches.concat validate_tml_dom_with_hash(tag, structure)
+      else raise ArgumentError, "Expected a String, Symbol, Array or Hash argument", caller
+    end
+
+    matches
+  end
+
+  # Validates that the TML produced by the specified tag is syntactically valid. Does not check its parent.
+  def validate_tml_tag(tag, parent_options = {})
+    tag = root_hpricot_tag(tag)
+    tag_name = tag.name
+    tag_rules = rules.tag_rules(tag_name) # contains :name, :minimum, :maximum, :children, :order
+    tracker = {}
+
+    validate_tag_exists(tag_name)
+
+    # add to parent_options for tracking, to match against minimum after children have been validated
+    parent_options[tag_name] = parent_options[tag_name].to_i + 1
+
+    if tag.children
+      assert_children_in_order(tag)
+      tag.children.each do |child|
+        next unless child.kind_of?(Hpricot::Elem)
+        assert_element_allowed(tag, child)
+        validate_tml_tag(child, tracker)
+      end
+
+      # assert each child >= minimum (&& <= maximum unless maximum == 0)
+      tag_rules.children.each do |child_name|
+        count = tracker[child_name] || 0
+        minimum = rules.tag(tag_name).minimum(child_name)
+        maximum = rules.tag(tag_name).maximum(child_name)
+        raise Rtml::Errors::RulesViolationError, "Too few '#{child_name}' tags within parent '#{tag_name}'" unless count >= minimum
+        raise Rtml::Errors::RulesViolationError, "Too many '#{child_name}' tags within parent '#{tag_name}'" unless maximum == 0 || count <= maximum
+      end
+    end
+  end
+
+  private
+  def validate_tag_exists(tag_name)
+    raise Rtml::Errors::RulesViolationError, "Tag does not exist: #{tag_name}" unless rules.tag_rules(tag_name)
+  end
+
+  def validate_tml_dom_with_hash(tag, structure)
+    matches = []
+    structure.each do |parent, child|
+      unless parent.kind_of?(String) || parent.kind_of?(Symbol)
+        raise ArgumentError, "Keys of hashes should be symbols or strings", caller
+      end
+
+      matches.concat validate_tml_dom(tag, parent)
+      failure = true
+      matches.each do |match|
+        begin
+          validate_tml_dom(match, child)
+          failure = false
+        rescue Rtml::Errors::RulesViolationError
+
+        end
+        break unless failure
+      end
+      raise Rtml::Errors::RulesViolationError, "Expected all of #{structure.inspect} but found #{tag}" if failure
+    end
+    matches
+  end
+
+  def validate_tml_dom_with_array(tag, structure)
+    matches = []
+    structure.each do |e|
+      begin
+        matches.concat validate_tml_dom(tag, e)
+      rescue
+        raise Rtml::Errors::RulesViolationError,
+              "Expected all of #{structure.inspect} but couldn't find #{e.to_s}\nin tml: #{tag}"
+      end
+    end
+    matches
+  end
+
+  def validate_tml_dom_with_string(tag, structure)
+    matches = []
+    matches.concat tag / structure
+    if matches.empty?
+      raise Rtml::Errors::RulesViolationError,
+            "Expected <#{structure.inspect}> but found\n#{tag.to_s}\nin tml: #{tag}"
+    end
+    matches
+  end
+
+  def ignore_root_tag(structure)
+    if structure.kind_of?(Hash) && structure.keys.length == 1 && structure.keys.first.to_s == rules.root
+      structure.delete(structure.keys[0])
+    else
+      structure.kind_of?(Symbol) ? structure.to_s : structure
+    end
+  end
+
+  def root_hpricot_tag(tag)
+    if tag.kind_of?(String) then Hpricot::XML(tag).root
+    elsif tag.respond_to?(:to_tml) then Hpricot::XML(tag.to_tml).root
+    else tag
+    end
+  end
+
+  def rules
+    @rules ||= Rtml::Document.rules
+  end
+
+  # asserts that all children of the given tag appear in their proper order.
+  def assert_children_in_order(element)
+    # assert children appear in order
+    tag_name = element.name
+    tag_rules = rules.tag_rules(tag_name)
+    prev_index = -1
+    element.children.each do |child|
+      chn = child.name
+      prn = '[no element]'
+      index = tag_rules.order.index(child.name)
+      unless index.nil? # if element is not mentioned, then it can appear at any time.
+        unless index >= prev_index
+          raise Rtml::Errors::RulesViolationError, "Elements out of order: '#{chn}' follows '#{prn}' within parent '#{tag_name}'"
+        end
+        prev_index = index
+        prn = chn
+      end
+    end
+  end
+
+  # asserts that child is allowed to appear within element
+  def assert_element_allowed(element, child)
+    tag_rules = rules.tag_rules(element.name)
+    unless tag_rules.children.include?(child.name)
+      raise Rtml::Errors::RulesViolationError, "Tag '#{child.name}' not allowed within parent '#{element.name}'"
+    end
+  end
+end