rtml 1.2.2 → 2.0.0.alpha.1

data/lib/rtml/environment.rb

@@ -0,0 +1,28 @@
+path = File.expand_path File.join(File.dirname(__FILE__), '../..')
+
+if defined?(Rails.configuration)
+  Rails.configuration.controller_paths << File.join(path, 'builtin/controllers')
+end
+
+%w(document
+   instruction
+   state
+   dom/element
+   dom/frontend_element
+   dom/property
+   dom/screen_element
+   instruction/follow_class_methods
+   state/variable_mapping).each do |fi|
+  require File.join(path, 'builtin/models/rtml', fi)
+end
+
+require File.join(path, 'builtin/rtml_helpers/rtml/get_state')
+require File.join(path, 'builtin/rtml_helpers/rtml/rescue_action')
+
+Dir[File.join(path, 'lib/extensions/**/*.rb')].each { |fi| require fi if File.file?(fi) }
+
+# Add RTML routes
+routes_file = File.join(Rtml.root, 'lib/rtml_routes.rb')
+unless ActionController::Routing::Routes.configuration_files.include? routes_file
+  ActionController::Routing::Routes.configuration_files << routes_file
+end

data/lib/rtml/errors/invalid_format.rb

@@ -0,0 +1,4 @@
+# Raised by Rtml::ReverseEngineering::Crawler when the response format was not what it was expected to be.
+class Rtml::Errors::InvalidFormat < StandardError
+
+end

data/lib/rtml/errors/invalid_operation.rb

@@ -0,0 +1,4 @@
+# Raised when RTML attempts to evaluate a TML operation (usually in a +setvar+ tag) that is illegal or nonexistent.
+class Rtml::Errors::InvalidOperation < StandardError
+
+end

data/lib/rtml/errors/invalid_option_error.rb

@@ -0,0 +1,4 @@
+# Raised when an invalid option is passed to RTML, for instance in the VariableProcessing Widget
+class Rtml::Errors::InvalidOptionError < StandardError
+
+end

data/lib/rtml/errors/missing_document_error.rb

@@ -0,0 +1,4 @@
+# Raised when an element attempts to render a view with no corresponding Rtml::Document model to render it through.
+class MissingDocumentError < StandardError
+
+end

data/lib/rtml/errors/missing_variable_error.rb

@@ -0,0 +1,4 @@
+# Raised when Rtml::HighLevel::VariableManager can't find the requested variable definition.
+class Rtml::Errors::MissingVariableError < StandardError
+
+end

data/lib/rtml/errors/multiple_roots_error.rb

@@ -0,0 +1,4 @@
+# Raised when RTML detects multiple root elements in a document
+class Rtml::Errors::MultipleRootsError < StandardError
+  
+end

data/lib/rtml/errors/processing_error.rb

@@ -0,0 +1,4 @@
+# Raised when RTML encounters an error while processing a Widget
+class Rtml::Errors::ProcessingError < StandardError
+
+end

data/lib/rtml/errors/rules_violation_error.rb

@@ -0,0 +1,4 @@
+# Raised when RTML detects a rules violation in the TML document object model, usually due to malformed XML
+class Rtml::Errors::RulesViolationError < StandardError
+
+end

data/lib/rtml/errors/screen_not_found.rb

@@ -0,0 +1,4 @@
+# Raised when a screen cannot be found, usually with a specified ID.
+class Rtml::Errors::ScreenNotFound < StandardError
+
+end

data/lib/rtml/errors/screen_variant_error.rb

@@ -0,0 +1,4 @@
+# Raised when the ScreenVariant Widget encounters an error while processing.
+class Rtml::Errors::ScreenVariantError < StandardError
+
+end

data/lib/rtml/errors/sti_type_error.rb

@@ -0,0 +1,4 @@
+# Raised when the STI type specified for an instance of Rtml::Dom::Element is not a descendant of Rtml::Dom::Element
+class Rtml::Errors::StiTypeError < StandardError
+  
+end

data/lib/rtml/errors/subprocessing_not_supported.rb

@@ -0,0 +1,4 @@
+# Raised when Widget attempts to perform subprocessing on an object that doesn't support it.
+class Rtml::Errors::SubprocessingNotSupported < StandardError
+
+end

data/lib/rtml/errors/unknown_rtml_action.rb

@@ -0,0 +1,4 @@
+# raised when an RTML action cannot be found
+class Rtml::Errors::UnknownRtmlAction < ActionController::UnknownAction
+
+end

data/lib/rtml/high_level/managed_variable.rb

@@ -0,0 +1,72 @@
+class Rtml::HighLevel::ManagedVariable
+  attr_reader :name
+  
+  def initialize(name)
+    @name = name
+  end
+
+  # Returns the TML necessary to test whether this variable's value is equal to the specified argument's value.
+  def ==(other)
+    op(:equal, other)
+  end
+
+  # Returns the TML necessary to test whether this variable's value is not equal to the specified argument's value.
+  def not_equal(other)
+    op(:not_equal, other)
+  end
+  alias not_equal_to not_equal
+
+  # Returns the TML necessary to test whether this variable's value is less than the specified argument's value.
+  def <(other)
+    op(:less, other)
+  end
+
+  # Returns the TML necessary to test whether this variable's value is greater than the specified argument's value.
+  def >(other)
+    op(:greater, other)
+  end
+
+  # Returns the TML necessary to test whether this variable's value is less than or equal to the specified value.
+  def <=(other)
+    op(:less_or_equal, other)
+  end
+
+  # Returns the TML necessary to test whether this variable's value is greater than or equal to the specified value.
+  def >=(other)
+    op(:greater_or_equal, other)
+  end
+
+  # Returns the TML necessary to add or concatenate the specified value with this one.
+  def +(other) op(:plus, other) end
+
+  # Returns the TML necessary to subtract the specified value from this one.
+  def -(other) op(:minus, other) end
+
+  # Returns the TML necessary to retrieve an item from the list with the specified index.
+  def item(other)
+    op(:item, other)
+  end
+  alias [] item
+
+  # Returns the TML necessary to retrieve the number of items in the list.
+  def number
+    op(:number, nil)
+  end
+  alias length number
+  alias size number
+
+  # Returns the TML necessary to format this variable using the specified format.
+  def format(other)
+    op(:format, other)
+  end
+
+  private
+  def op(which, other)
+    which = which.to_s
+    if other.kind_of?(Rtml::HighLevel::ManagedVariable)
+      ["tmlvar:#{name}", which, "tmlvar:#{other.name}"]
+    else
+      ["tmlvar:#{name}", which, other]
+    end
+  end
+end

data/lib/rtml/high_level/subroutine.rb

@@ -0,0 +1,22 @@
+class Rtml::HighLevel::Subroutine
+  def initialize(name, parent, options = {}, &blk)
+    @block = blk
+    @name = name
+    @parent = parent
+  end
+
+  def call(context, args)
+    method_name = @name
+    block = @block
+    
+    (class << context; self; end).instance_eval do
+      define_method method_name, &block
+      new_method = instance_method(method_name)
+      define_method method_name do |arguments|
+        new_method.bind(self).call(arguments)
+      end
+    end
+
+    context.send(method_name, args)
+  end
+end

data/lib/rtml/high_level/variable_manager.rb

@@ -0,0 +1,35 @@
+class Rtml::HighLevel::VariableManager
+  attr_accessor :screen
+
+  def initialize()
+    @vars = HashWithIndifferentAccess.new
+  end
+
+  def [](variable_name)
+    variable_name = variable_name.to_s
+    vardec = screen.document.variable_definitions.select { |i| i['name'] == variable_name }
+    vardec = vardec.collect { |i| i['name'] }.first
+    raise Rtml::Errors::MissingVariableError, "Could not find a TML variable named #{variable_name}. "+
+            "Did you forget to declare it?" unless vardec
+    @vars[variable_name] ||= Rtml::HighLevel::ManagedVariable.new(variable_name)
+  end
+
+  def []=(target, other)
+    case other
+      when Rtml::HighLevel::ManagedVariable
+        screen.set self[target].name => "tmlvar:#{other.name}"
+      else
+        screen.set self[target].name => other
+    end
+  end
+
+  def method_missing(name, *args, &block)
+    if args.empty? && !block_given?
+      self.send("[]", name)
+    elsif name.to_s[-1] == ?= && args.length == 1 && !block_given?
+      self.send("[]=", name.to_s[0...-1], *args)
+    else
+      super
+    end
+  end
+end

data/lib/rtml/inherited_instance_variables.rb

@@ -0,0 +1,25 @@
+module Rtml::InheritedInstanceVariables
+  def copy_ivars_from(source)
+    ivars = source.instance_variables
+    ivars -= source.protected_instance_variables if source.respond_to?(:protected_instance_variables)
+    ivars.each { |ivar| instance_variable_set(ivar, source.instance_variable_get(ivar)) }
+  rescue
+    # fail silently if they can't be copied
+  end
+
+  def initialize_with_inherited_instance_variables(*a, &b)
+    initialize_without_inherited_instance_variables(*a, &b)
+
+    %w(controller document parent).each do |method|
+      copy_ivars_from(send(method)) if respond_to?(method) rescue nil
+    end
+  end
+
+  def self.included(base)
+    base.instance_eval do
+      class_inheritable_array :protected_instance_variables
+      read_inheritable_attribute(:protected_instance_variables) || write_inheritable_attribute(:protected_instance_variables, [])
+      alias_method_chain :initialize, :inherited_instance_variables
+    end
+  end
+end

data/lib/rtml/init.rb

@@ -0,0 +1,82 @@
+unless defined?(Rtml) && defined?(Rails)
+  # Now, for some reason, Rails (ActiveSupport?) is removing a lot of existing directories from
+  # the load path. Probably for optimization, but kind of counterproductive for this edge case.
+  # So I'm going to back them up, and then re-add them.
+  load_path_backup = $LOAD_PATH.collect { |lp| File.expand_path(lp) }
+
+  require File.join(File.dirname(__FILE__), '../rtml/dependencies')
+
+  unless defined?(RAILS_ROOT)
+    RAILS_ROOT = Dir.pwd.gsub(/\/test(\/|)$/, '')
+  end
+
+  module Rails
+    module VERSION
+      MAJOR = 2
+      MINOR = 3
+      TINY  = 5
+
+      STRING = [MAJOR, MINOR, TINY].join('.')
+    end
+
+    class Configuration
+      attr_accessor :controller_paths, :view_path
+
+      def initialize
+        @controller_paths = [File.join(RAILS_ROOT, 'controllers'), File.join(File.dirname(__FILE__), '../../builtin/controllers')]
+        @view_path = File.join(RAILS_ROOT, 'views')
+      end
+    end
+
+    class << self
+      attr_writer :logger, :backtrace_cleaner, :configuration
+
+      def logger
+        @logger ||= Logger.new(File.join(RAILS_ROOT, "tmp/rtml.log"))
+      end unless defined?(Rails.logger)
+
+      def backtrace_cleaner
+        @backtrace_cleaner ||= ActiveSupport::BacktraceCleaner.new
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def root
+        RAILS_ROOT
+      end
+    end
+  end
+
+  class ApplicationController < ActionController::Base
+  end unless defined?(ApplicationController)
+
+  # Restore the missing load paths.
+  load_path_backup.reverse.each do |path|
+    $LOAD_PATH.unshift path unless $LOAD_PATH.include?(path)
+  end
+
+  ActiveRecord::Base.logger = Rails.logger
+  ActiveRecord::Base.establish_connection(:database => File.join(RAILS_ROOT, "tmp/rtml_test_db.sqlite3"),
+                                          :adapter => 'sqlite3',
+                                          :timeout => 5000,
+                                          :pool => 5)
+
+
+  ActionController::Base.session = { :key => '_myapp_session', :secret => '1'*60 }
+
+  # Now that we're emulating the bare bones of Rails (at least as far as RTML is concerned), let's
+  # get to RTML itself.
+  require File.join(File.dirname(__FILE__), '../rtml')
+  require File.join(File.dirname(__FILE__), '../rtml/environment')
+
+  if defined?(Rake::Task)
+    task :environment
+    load File.join(File.dirname(__FILE__), '../../tasks/rtml.rake')
+    load File.join(File.dirname(__FILE__), '../../tasks/db.rake')
+    load 'tasks/routes.rake'
+  end
+
+  Dir.chdir RAILS_ROOT
+end

data/lib/rtml/reverse_engineering/crawler.rb

@@ -0,0 +1,58 @@
+class Rtml::ReverseEngineering::Crawler
+  attr_reader :simulator, :session
+  delegate :tml, :route, :set, :to => :simulator
+  delegate :response, :request, :controller, :get, :post, :put, :delete, :to => :session
+
+  def tml=(tml)
+    @path = nil
+    simulator.tml = tml
+  end
+
+  def initialize(options = {})
+    @simulator = Rtml::ReverseEngineering::Simulator.new(options.delete(:tml))
+    @session = ActionController::Integration::Session.new
+  end
+
+  def visit(path, screen = nil)
+    path, screen = split_path_and_screen_name_out_of(path) unless screen
+    unless path.blank? or path == @path
+      get @path = path
+      format = response.template.template_format
+      if format == :rtml then simulator.tml = response.body
+      else raise Rtml::Errors::InvalidFormat, "Response must be in :rtml format; found #{format.inspect}:\n#{response.body}"
+      end
+    end
+    
+    @simulator.visit screen
+  end
+
+  def split_path_and_screen_name_out_of(path)
+    path, screen = path.split(/#/)
+    if screen =~ /\?/
+      screen, query = screen.split(/\?/)
+      path = "#{path}?#{query}"
+    end
+    [path, screen]
+  end
+
+  def current_screen
+    route.last
+  end
+
+  private
+  # Since we're using ActionController::Integration::Session instead of including ActionController::TestProcess,
+  # this method isn't used any more and should really be removed.
+  def setup_controller_request_and_response
+    # How to get this info into a TestResult so we don't have to create 2 requests?! TestResult seems to always override
+    # the env with Rack::MockRequest.env_for("/"), even though it looks like it SHOULD be merging the two. Bug?
+    temp_request = ActionController::Request.new(Rack::MockRequest.env_for(@path))
+    @path_params = ActionController::Routing::Routes.recognize_path(temp_request.path)
+    @request = ActionController::TestRequest.new
+    @request.remote_addr = '123.231.12.3'
+    @response = ActionController::TestResponse.new
+    @controller = @path_params[:controller].to_controller.new
+    @controller.request = @request
+    @controller.params = temp_request.parameters
+    @controller.send(:initialize_current_url)
+  end
+end

data/lib/rtml/reverse_engineering/simulator.rb

@@ -0,0 +1,269 @@
+class Rtml::ReverseEngineering::Simulator
+  include Rtml::Rules::DomValidation
+  include Rtml::ReverseEngineering::Simulator::VariableLookup
+  attr_reader :tml
+
+  def initialize(tml = nil)
+    self.tml = tml if tml
+  end
+
+  def set(values)
+    variables.merge!(values.with_indifferent_access)
+  end
+
+  def route
+    @stack.last ? @stack.last[4] : []
+  end
+
+  # Visits the specified screen. Evaluates variable assignments and follows TML logical flow, but does not interact
+  # with hotkeys, hyperlinks, etc.
+  #
+  # Timeouts are not evaluated because they *usually* indicate that some interaction is required by the user.
+  #
+  # The return value is the last screen to be visited with the above exceptions. Circular paths return the last
+  # screen in the path before it would loop over; external references return the URL of the reference.
+  def visit(screen_name = nil)
+    raise Rtml::Errors::ScreenNotFound, "No screens found to visit in RTML document!" unless first_screen
+    screen_name = first_screen['id'] if screen_name.blank?
+    response = analyze screen_name, :ignore_pathlist => true, :interaction => :none
+    response.kind_of?(Symbol) ? route.last || response : response
+  end
+
+  # Analyzes the specified path (which can be one or more symbols and/or strings) and verifies
+  # that screens with the specified IDs are followed, in the specified order. If any screen is encountered
+  # which is NOT in the list, no error is raised as long as the next screen in the list is visited at some point.
+  # Returns one of the following values:
+  #
+  #   :completion - each screen was visited in the specified order.
+  #   :assertion  - a TML assertion error was raised in the form of the "assert" screen being visited.
+  #   :no_route   - The TML pathway did not result in the specified screens being visited in the expected order.
+  #   :dead_end   - The TML pathway ended abruptly, and did not visit all of the specified screens before doing so.
+  #   :circular   - The TML pathway was a circular route which never touched one or more nodes.
+  #   :error      - Processing ended abruptly, for an unknown reason.
+  #   a String    - The TML pathway encountered a link to an external document, and not an anchor. The String returned
+  #                 is the reference to the external document.
+  #
+  # This method also builds the #route up, so that you can analyze the order in which screens were visited.
+  #
+  def analyze(*path)
+    raise Rtml::Errors::ScreenNotFound, "No screens found to visit in RTML document!" unless first_screen
+    options = path.extract_options!
+    path.flatten!
+    raise ArgumentError, "Expected at least one screen ID as an argument" unless path.length > 0
+    @ignore_pathlist = path.empty? || options.delete(:ignore_pathlist)
+    @interaction = options.delete(:interaction) || options.delete(:interactions) || :all
+    @recursion_limit = options.delete(:recursion_limit) || options.delete(:max_depth) || 150
+
+    r = catch(:completion) do
+      current = path.shift || first_screen['id']
+      #route << current
+      @pathlist = path
+      catch(:abort) do
+        trace(find_screen(current))
+        :error
+      end
+    end
+    r
+  end
+
+  def tml=(value)
+    reset!
+    case value
+      when String        then @tml = Hpricot::XML(value).root
+      when Hpricot::Doc  then @tml = value.root
+      when Hpricot::Elem then @tml = value
+      else raise ArgumentError, "Expected TML to be a String, Hpricot::Doc or Hpricot::Elem"
+    end
+
+    parse_tml
+  end
+
+  def find_screen(id)
+    rt = screens.select { |scr| scr['id'] == id.to_s }
+    raise Rtml::Errors::ScreenNotFound, "Could not find screen with ID '#{id}'" if rt.empty?
+    scr = rt.shift
+    raise Rtml::Errors::ScreenNotFound, "Multiple ambiguous screens found with ID '#{id}'" unless rt.empty?
+    scr
+  end
+
+  private
+  # Returns all interactions that the simulator is allowed to perform in the form of an array.
+  def interactions
+    if @interaction.kind_of?(Symbol)
+      case @interaction
+        when :all then [:all, :key, :timeout, :href]
+        when :none then []
+        when :key, :timeout, :href then [@interaction]
+      end
+    else
+      @interaction
+    end
+  end
+
+
+  def trace(screen)
+    route << screen['id']
+    take_snapshot(screen)
+    unless @ignore_pathlist
+      @pathlist.shift if screen['id'] == @pathlist.first.to_s
+      throw :completion, :completion if @pathlist.empty?
+    end
+
+    process_variable_assignments(screen)
+
+    candidates = href_candidates(screen)
+    throw :completion, :completion unless candidates.empty? || interactions.include?(:href)
+    
+    candidates.concat next_screen_for(screen)
+    throw :abort, :dead_end if candidates.empty?
+
+    abort_with = nil
+    anchors_for(candidates).each do |next_screen|
+      if next_screen.kind_of?(String)# == :external
+        throw :abort, next_screen    #    :external
+      elsif next_screen['id'] == 'assert'
+        throw :abort, :assertion
+      else
+        push_stack
+        abort_with = catch(:abort) do
+          trace(next_screen)
+          nil
+        end
+        throw :abort, abort_with if @ignore_pathlist
+        pop_stack if abort_with
+      end
+    end
+    throw :abort, abort_with if abort_with
+  end
+
+  # Finds the various +setvar+ elements in the specified screen and updates the simulator's variable states to match.
+  def process_variable_assignments(screen)
+    setvars = screen / "setvar"
+    setvars.each do |setvar|
+      variables[setvar['name']] = Rtml::ReverseEngineering::Simulator::VariableValue.new(setvar, variables, vardecs).value
+    end
+  end
+
+  # Finds all hyperlinks within the given screen and returns them.
+  #
+  def href_candidates(screen)
+    (screen / "a").select { |elem| elem['href'] }.collect { |elem| elem['href'] }
+  end
+
+  # Takes a "snapshot" of the state of the simulator, with the given screen as the index.
+  # This is used to track visited screens; it is a safe assumption that if all variables are identical
+  # to a given snapshot with the given screen, then this will result in a circular TML path.
+  # This method will throw :abort, :circular if this condition is true.
+  def take_snapshot(screen)
+    snapshot = Rtml::ReverseEngineering::Simulator::Snapshot.new(screen, variables)
+    if snapshots.length > @recursion_limit
+      raise Rtml::Errors::ProcessingError, "Recursion error: Probable infinite loop (or :recursion_limit is too low)"
+    end
+    if snapshots.include?(snapshot)
+      throw :abort, :circular
+    end
+    snapshots << snapshot
+  end
+
+  # returns the list of possible screenflow branches following the specified screen.
+  def next_screen_for(screen)
+    candidates = screen['next'] ? [screen['next']] : []
+    next_element = (screen / "next").shift
+    if next_element
+      candidates = find_adequate_variants(next_element) + [next_element['uri']]
+    end
+
+    candidates
+  end
+
+  # Returns array containing the screen element for each string in the array, or the original string if it is not found.
+  def anchors_for(candidates)
+    candidates.collect do |screen_id|
+      if screen_id =~ /^#/
+        find_screen(screen_id[1..-1]) # to drop the '#'
+      else
+        screen_id
+        #:external
+      end
+    end
+  end
+
+  # Returns the first variant in the Hpricot::Elem which matches the current variable values, or nil if none match.
+  def find_adequate_variants(elem)
+    variants = elem / "variant"
+
+    candidates = []
+    variants.each do |variant|
+      uri, lo, op, ro, key, timeout =
+              variant['uri'], variant['lo'], variant['op'] || "equal", variant['ro'], variant['key'], variant['timeout']
+      %w(uri lo op ro key timeout).each { |lv| eval("#{lv} = resolve(#{lv}, variables, vardecs)") }
+      if (interactions.include?(:key) && key) || (interactions.include?(:timeout) && timeout)
+        candidates << uri
+      elsif key || timeout # if we're not interacting with them, pause to allow user interaction
+        throw :completion, :completion
+      else
+        # only follow if it's a match
+        ro = lo.kind_of?(Fixnum) ? ro.to_i : ro.to_s
+        
+        match = case op
+          when 'equal' then lo == ro
+          when 'not_equal' then lo != ro
+          when 'less' then lo < ro
+          when 'less_or_equal' then lo <= ro
+          when 'contains' then lo.to_s[ro.to_s]
+          else raise Rtml::InvalidOperation, "Invalid operation: #{op}"
+        end
+        candidates << uri and break if match
+      end
+    end
+
+    candidates #candidates.empty? ? nil : candidates
+  end
+
+  def first_screen
+    (tml / "screen").first
+  end
+  
+  # resets the various tracking variables
+  def reset!
+    @stack = [ ]
+    #@stack.clear
+    push_stack
+  end
+
+  def push_stack
+    @stack.push [ screens.dup, snapshots.dup, variables.dup, vardecs.dup, route.dup ]
+  end
+
+  def pop_stack
+    @stack.pop
+  end
+
+  def screens
+    @stack.last ? @stack.last[0] : []
+  end
+
+  def snapshots
+    @stack.last ? @stack.last[1] : []
+  end
+
+  def variables
+    @stack.last ? @stack.last[2] : {}
+  end
+
+  def vardecs
+    @stack.last ? @stack.last[3] : {}
+  end
+
+  # Validates the given TML, and then finds the +screen+ elements and tracks them. 
+  def parse_tml
+    validate_tml(@tml)
+    (@tml / "vardcl").each do |elem|
+      vardecs[elem['name']] = elem['type'].to_sym
+    end
+    
+    (@tml / "screen").each do |elem|
+      screens << elem
+    end
+  end
+end