rtml 1.2.2 → 2.0.0.alpha.1

data/{app_generators/rtml/templates/rtml/lib/rtml → lib/rtml/rules}/tml_param_parser.rb

@@ -5,38 +5,38 @@
 # application/x-www-form-urlencoded data instead of XML, which would
 # render this class unnecessary overhead.
 #
-class Rtml::TmlParamParser
+class Rtml::Rules::TmlParamParser
   attr_reader :params
-  
+
   def initialize(data)
     tml = Hpricot.XML(data)
     tmlpost = tml.at('tmlpost')
     postvars = tml.search("//postvar")
     @params = {}.with_indifferent_access
-    
+
     if tmlpost and postvars
       params[:post_id] = tmlpost['post_id'].to_i
-      params[:date]    = Date.parse(tmlpost['date'])
-      params[:itid]    = tmlpost['itid']
-      params[:xmlns]   = tmlpost['xmlns']
+      params[:date] = Date.parse(tmlpost['date'])
+      params[:itid] = tmlpost['itid']
+      params[:xmlns] = tmlpost['xmlns']
       p = {}
       postvars.each do |postvar|
         name, value = name_and_value_of postvar
         p[name] = value
       end
-      
+
       # The reason this is broken into two phases is because if we don't, there's a chance we'll
       # miss a value that looks like (but isn't) a namespace. Example:
       #
-      #  card.pin      = '3C30E0EEB1978A58' # this is actually the pin block itself
-      #  card.pin.smid = '00000E0001E000CB' # this is the smid
+      # card.pin = '3C30E0EEB1978A58' # this is actually the pin block itself
+      # card.pin.smid = '00000E0001E000CB' # this is the smid
       #
       # When parsed from parmstr, card.pin.smid would normally create params[:card][:pin] = {:smid => '...'}
       # But this would overwrite card.pin = '3C30E0EEB1978A58', and we'd lose the pin block. It'd probably
       # be more correct to fix this at the TML level, but we can't expect every TML developer to figure that
       # out, and RTML can only help so much. It breaks the convention, but I think it's safer in the
       # long run to turn this into params[:card][:pin] and params[:card]['pin.smid']. Even though it
-      # will doubtlessly add confusion to a developer who has to work with it, at least this confusion 
+      # will doubtlessly add confusion to a developer who has to work with it, at least this confusion
       # should be rare in RTML (because RTML sorts all this info into its Transaction model and expects
       # the developer to deal with transactions through the model, and not the params themselves).
       #
@@ -52,7 +52,7 @@ class Rtml::TmlParamParser
       end
     end
   end
-  
+
   private
   def sort_and_assign(name, value, p = params)
     if name =~ /\./
@@ -67,7 +67,7 @@ class Rtml::TmlParamParser
       p[name] = value
     end
   end
-  
+
   def name_and_value_of(postvar)
     type = postvar['type']
     name = postvar['name']
@@ -79,12 +79,11 @@ class Rtml::TmlParamParser
           when 'date'    then DateTime.strptime(value, "%d %m %Y %H:%M:%S").to_time
           when 'integer' then value.to_i
           when 'string'  then value
-          # TODO: this is actually hex; maybe unpack into true binary at some point?
-          when 'opaque'  then value
+          when 'opaque'  then value.hex_to_bin
           # Decided to simply assign string value instead of raising error on unknown types, so that user
           # can handle it without having to hack the framework.
           else value
-          #else raise "Unknown TML type: #{type}"
+          #else raise ArgumentError, "Unknown TML type: #{type}"
         end
       rescue
         warn "Error #{$!.message} while parsing value #{value.inspect} for TML param #{name.inspect} (#{type})"

data/lib/rtml/test/spec.rb

@@ -0,0 +1,14 @@
+begin
+  require 'webrat'
+rescue LoadError
+  # optional. Or should it be?
+end
+
+class RtmlExampleGroup < (defined?(Test::Unit::TestCase) ? Test::Unit::TestCase : Object)
+  extend Spec::Example::ExampleGroupMethods
+  include Spec::Example::ExampleMethods
+  include(Webrat::Matchers) if defined?(Webrat)
+  include(Rtml::Rules::DomValidation)
+end
+
+Spec::Example::ExampleGroupFactory.register(:rtml, RtmlExampleGroup)

data/lib/rtml/tmlized_conditions.rb

@@ -0,0 +1,37 @@
+# This module provides helpers to "TML-ize" conditions.
+module Rtml::TmlizedConditions
+  # returns [lo, op, ro] such that each are valid within a <variant> element.
+  #
+  # Condition can be :if or :unless.
+  #
+  def tmlize_condition(lo, op, ro, condition = :if)
+    raise ArgumentError, "Expected condition to be :if or :unless" unless [:if, :unless].include? condition
+    case op
+      when '<',  'less',             'less_than'                then lo, op, ro = lo, 'less', ro
+      when '<=', 'less_or_equal',    'less_than_or_equal_to'    then lo, op, ro = lo, 'less_or_equal', ro
+      when '>=', 'greater_or_equal', 'greater_than_or_equal_to' then lo, op, ro = ro, 'less', lo
+      when '>',  'greater',          'greater_than'             then lo, op, ro = ro, 'less_or_equal', lo
+      when '==', 'equal',            'equal_to'                 then lo, op, ro = lo, 'equal', ro
+      when '!=', 'not_equal',        'not_equal_to'             then lo, op, ro = lo, 'not_equal', ro
+      when '=~'                                                 then op = 'contains'
+      when '+',  'plus'                                         then op = 'plus'
+      when '-',  'minus'                                        then op = 'minus'
+    end
+    op = invert_condition(op) if condition == :unless
+    [lo, op, ro]
+  end
+
+  # Returns the operation that is the opposite of the specified operation.
+  def invert_condition(op)
+    case op
+      when 'less'              then 'greater'
+      when 'less_or_equal'     then 'greater_or_equal'
+      when 'greater_or_equal'  then 'less_or_equal'
+      when 'greater'           then 'less'
+      when 'equal'             then 'not_equal'
+      when 'not_equal'         then 'equal'
+      when 'plus'              then 'minus'
+      when 'minus'             then 'plus'
+    end
+  end
+end

data/lib/rtml/version.rb

@@ -0,0 +1,10 @@
+module Rtml
+  module VERSION
+    MAJOR = 2
+    MINOR = 0
+    TINY  = 0
+    PRE   = 'alpha.1'
+
+    STRING = (defined?(PRE) ? [MAJOR, MINOR, TINY, PRE] : [MAJOR, MINOR, TINY]).join('.')
+  end
+end

data/lib/rtml/widget.rb

@@ -0,0 +1,150 @@
+# The Widget is the driving force behind RubyTML. It is interaction with Widgets of all shapes and sizes that produces
+# a document model and, finally, the TML document itself. A Widget is so named because it is a generic class that can
+# be made to encapsulate any desired functionality. The Rtml::Widget base class takes care of interfacing content
+# generation code with the RTML project as a whole.
+#
+# If you've done any RTML programming at all, you've been using Widgets. Does the following code look familiar?
+#
+#  screen :idle, :next => :main, :timeout => 3 do
+#    display
+#  end
+#
+# Even core functionality such as the "screen" method is traced back to a Widget -- in this case,
+# +Rtml::Widgets::Screens+.
+#
+# Since interfacing with the various components of RTML is handled by the base class, writing a Widget is easy:
+#
+#  class Rtml::Widgets::CardParser < Rtml::Widget
+#    affects :screen
+#    entry_point :card
+#    
+#    def card(options = {})
+#      raise ":parser must be provided" unless options[:parser]
+#      parent.build :card, :parser => options[:parser], :parser_params => (options[:params] || 'read_data')
+#    end
+#  end
+#
+# When invoked from a Screen, this code will produce a TML card parser element:
+#  screen . . . do
+#    card :parser => :mag   #=> <card parser='mag' params='read_data' />
+#  end
+#
+# If you are just interested in using the Widgets, you are encouraged to read the documentation for the various Widgets
+# themselves. If you find that you need to program a new Widget in order to address some missing functionality, you can
+# generate one easily with the command line generator:
+#   ruby script/generate widget my_widget [entry_point1 entry_point2 . . .]
+#
+class Rtml::Widget
+  # These are the accessors that RDoc uses to define what a particular RTML-specific attribute maps to.
+  #
+  # There are 3 kinds of accessors:
+  # - Shared variable
+  #   * These are used to create variables that are different across parent objects, but which are shared between
+  #     multiple Widgets (whether totally separate, or instances of the same) on the same instantiated parent.
+  #     It's a little complicated, but it's critical in (for example) tracking TML variable definitions.
+  # - Valid parent
+  #   * These are the names of TML elements (or "document" for document-level Widgets) that are allowed to instantiate
+  #     the Widget in question by calling its entry points.
+  # - Entry point
+  #   * These are instance methods defined by the Widget which are proxied into potential parent objects. Calling an
+  #     entry point results in the configuration and eventual instantiation of the Widget which declared the entry
+  #     point.
+  #
+  RDOC_ACCESSORS = {
+    :shared => 'shared variable',
+    :affects => 'valid parent',
+    :entry_point => "entry point",
+  }
+
+  @@widget_id_tracker = 0
+  class_inheritable_array :targets
+  class_inheritable_array :shared_variables
+  class_inheritable_array :entry_points
+  read_inheritable_attribute(:targets)          || write_inheritable_attribute(:targets,          [])
+  read_inheritable_attribute(:shared_variables) || write_inheritable_attribute(:shared_variables, [])
+  read_inheritable_attribute(:entry_points)     || write_inheritable_attribute(:entry_points,     [])
+  attr_reader :parent
+  attr_reader :source_type
+  extend Rtml::WidgetCore::ClassMethods
+
+  def validate_parent(*options)
+    options = options.flatten.collect { |o| o.kind_of?(String) ? o : o.to_s }
+    unless options.include?(parent.name)
+      raise ArgumentError, "Expected parent to be one of #{options.to_sentence(:language => :en)}; found #{parent.name}"
+    end
+  end
+
+  def document
+    @document ||= (parent.kind_of?(Rtml::Document) || !parent.respond_to?(:document) ? parent : parent.document)
+  end
+
+  # A guaranteed unique ID for this Widget.
+  def widget_id
+    @widget_id ||= (@@widget_id_tracker += 1)
+  end
+
+  def initialize(parent)
+    @parent = parent
+    set_source_type!
+    parent.widget_instances << self
+    # proxy parent methods into parent, unless they exist for widget already
+    singleton_class = (class << self; self; end)
+    (@parent.public_methods - self.public_methods).each do |proxy_method|
+      # don't delegate entry points -- this addresses the infinite loop issue in which calling a method that's been
+      # defined as an entry point but hasn't been created in the Widget itself would recurse back into the parent
+      # object forever.
+      unless entry_points.include? proxy_method
+        singleton_class.send(:delegate, proxy_method, :to => :parent)
+      end
+    end
+
+
+    self.class.shared_variables.each do |sv|
+      unless @parent.instance_variable_get("@#{sv[:name]}")
+        if sv[:default_value]
+          if sv[:default_value].kind_of?(Class)
+            @parent.instance_variable_set("@#{sv[:name]}", sv[:default_value].new)
+          else
+            @parent.instance_variable_set("@#{sv[:name]}", sv[:default_value].dup)
+          end
+        end
+      end
+    end
+  end
+
+  # Returns true if subprocessing has been disabled. See also #disable_subprocessing!
+  def subprocessing_disabled?
+    @disable_subprocessing = self.class.disable_subprocessing? unless defined?(@disable_subprocessing)
+    @disable_subprocessing
+  end
+  alias disable_subprocessing? subprocessing_disabled?
+
+  # Use this to enable subprocessing after it has already been disabled. See #disable_subprocessing!
+  def enable_subprocessing!
+    @disable_subprocessing = false
+  end
+
+  # By default, if a Widget's entry point is called with a block argument, it will be passed into the #process method
+  # of the entry point's return value. This is called subprocessing -- that is, processing the element to be returned
+  # at a lower level. This method disables subprocessing and its related assertions. It's useful, for instance, if you
+  # want to manually control how or when the block argument is processed, or if you want to ignore it entirely.
+  #
+  # There is a class method of the same name that has the same effect for the entire class; this instance method can
+  # disable subprocessing for particular instances, and is useful if you only want subprocessing under certain
+  # conditions.
+  def disable_subprocessing!
+    @disable_subprocessing = true
+  end
+
+  alias parent_type source_type
+
+  private
+  def set_source_type!
+    case parent
+      when Rtml::Document
+        @source_type = :document
+      else
+        @source_type = parent.name.to_sym
+    end
+  end
+end

data/lib/rtml/widget_core/class_methods.rb

@@ -0,0 +1,193 @@
+module Rtml::WidgetCore::ClassMethods
+  @@gui_enabled_widgets = {}
+
+  def proxy_module
+    return @proxy_module if @proxy_module
+    @proxy_module = Module.new
+    @proxy_module.instance_variable_set("@shared_variables", shared_variables)
+    @proxy_module.instance_eval do
+      def included(base)
+        @shared_variables.each do |sv|
+          base.send(:attr_accessor, sv[:name])
+        end
+      end
+    end
+
+    @proxy_module
+  end
+
+  # Yields this Widget's GUI configuration to the supplied block, allowing you to set up your Widget to be accessible
+  # from the RTML Application Builder. Note that if this method is never called, your Widget will not be available to
+  # the GUI.
+  def gui
+    yield(gui_configuration)
+  end
+
+  # Returns the +Rtml::WidgetCore::GuiConfiguration+ instance for this Widget.
+  # Shorthand for:
+  #   widget.gui_enabled_widgets[widget]
+  def gui_configuration
+    gui_enabled_widgets[self] ||= Rtml::WidgetCore::GuiConfiguration.new(self)
+  end
+
+  ## Returns the array of Widgets that have called the #gui method, thereby marking themselves as accessible to the
+  ## RTML Application Builder.
+  def gui_enabled_widgets
+    @@gui_enabled_widgets
+  end
+
+  # Creates a "shared" variable for the parent object with the specified default value, if any. This is much like
+  # a class variable, except that it is unique to the parent object in question. Multiple calls to a Widget's
+  # entry point will result in multiple Widgets being instantiated. If you use an instance variable to hold data,
+  # then that instance variable will be different for every entry point called. However, sometimes you need to share
+  # data across multiple instances of the same Widget, but not across *all* instances of the same Widget. For
+  # instance, your Widget may want to track references to variables in an individual Screen, but not across multiple
+  # Screens. To accomplish this, you essentially need an instance variable for the Screen. The "shared" method
+  # manages these variables for you.
+  #
+  # Examples:
+  #   shared :tml_variables
+  #   shared :variable_definitions, :variable_declarations
+  #   shared :tml_variables => []                          # initializes #tml_variables to [].dup
+  def shared(*names)
+    names.each do |name|
+      if name.kind_of? Hash
+        value = name.values.first
+        name = name.keys.first.to_s
+        shared_variables << { :name => name, :default_value => value }
+      else
+        name = name.to_s
+        shared_variables << { :name => name, :default_value => nil }
+      end
+      delegate name, "#{name}=", :to => :parent
+    end
+    reinclude_proxy_module
+  end
+
+  # By default, if a Widget's entry point is called with a block argument, it will be passed into the #process method
+  # of the entry point's return value. This is called subprocessing -- that is, processing the element to be returned
+  # at a lower level. This method disables subprocessing and its related assertions. It's useful, for instance, if you
+  # want to manually control how or when the block argument is processed, or if you want to ignore it entirely.
+  #
+  # If you want to disable subprocessing only under certain conditions, see the instance method of the same name.
+  def disable_subprocessing!
+    @disable_subprocessing = true
+  end
+
+  # Use this to enable subprocessing after it has already been disabled. See #disable_subprocessing!
+  def enable_subprocessing!
+    @disable_subprocessing = false
+  end
+
+  # Returns true if subprocessing has been disabled. See also #disable_subprocessing!
+  def subprocessing_disabled?
+    @disable_subprocessing ||= false
+  end
+  alias disable_subprocessing? subprocessing_disabled?
+
+  # Specifies the targets that this Widget will affect. A target can be a name of a model or the name of a TML tag,
+  # which matches that model's "name" attribute.
+  #
+  # Examples:
+  #   affects :document, :element, :property # names of models
+  #   affects :tml, :head, :screen           # names of TML tags
+  #
+  def affects(*targets)
+    targets.flatten.each do |target|
+      target = target.to_s unless target.kind_of?(String)
+      unless self.targets.include? target
+        self.targets << target
+        map = Rtml::Widgets.mapping(target)
+        map.proxied_widgets << self
+        map.imbue(proxy_module)
+      end
+    end
+  end
+
+  # Goes through each of the targets of this Widget, looks up its mapping in Rtml::Widgets.mapping, and calls
+  # proxy_module.append_features(mapping) for each of those mappings.
+  def reinclude_proxy_module
+    targets.each do |target|
+      Rtml::Widgets.mapping(target).imbue(proxy_module)
+    end
+  end
+
+  # Specifies entry points, which are names of methods that can be called from the targets to invoke this Widget.
+  #
+  # Examples:
+  #   entry_point :screen
+  #
+  def entry_point(*names)
+    names.each do |name|
+      name = name.to_s
+      unless entry_points.include?(name)
+        entry_points << name
+        add_entry_point(name)
+      end
+    end
+  end
+
+  # Adds the specified entry point to this Widget's proxy module.
+  def add_entry_point(entry_point)
+    # This validation doesn't work because it's not this proxy module, it's those of the OTHER Widgets
+    # that should be checked. Not sure of the best way to do that yet.
+#    if proxy_module.public_instance_methods.include?(entry_point)
+#      raise Rtml::Errors::RulesViolationError,
+#            "Widget entry point #{entry_point} cannot be defined because it already exists!"
+#    end
+    entry_point = entry_point.to_s if entry_point.is_a?(Symbol)
+    
+    enter_from_hash = "#{entry_point}_from_hash"
+    ['?','!'].each do |i|
+      enter_from_hash = enter_from_hash.gsub(/#{Regexp::escape(i)}/, '') + i if enter_from_hash[i]
+    end
+
+    line = __LINE__ + 2
+    code = <<-end_code
+      def #{entry_point}(*args, &block)               # def screen(*args, &block)
+        widget = #{self.name}.new(self)               #   widget = Rtml::Widgets::Screens.new(self)
+        r = widget.#{entry_point}(*args, &block)      #   r = widget.screen(*args, &block)
+
+        unless widget.disable_subprocessing? || !block_given?
+          unless r.respond_to?(:process)
+            raise Rtml::Errors::SubprocessingNotSupported, "Return value \#{r} does not support subprocessing"
+          end
+          r.process &block
+        end
+        r
+      rescue ArgumentError => ae
+        if ae.backtrace[0] =~ /#{Regexp::escape entry_point}/
+          raise ArgumentError, ae.message, caller
+        else raise ae
+        end
+      end                                             # end
+
+      # Calls the entry point after reformatting the arguments in hash to fit the entry point's requirements
+      # per +Rtml::WidgetCore::GuiConfiguration#construct_arguments+
+      #
+      # This is primarily for interfacing with the RTML GUI.
+      #
+      def #{enter_from_hash}(hash, &block)
+        arguments = #{self}.gui_configuration.construct_arguments(hash || {})
+        self.#{entry_point} *arguments, &block
+      end
+    end_code
+    proxy_module.class_eval code, __FILE__, line
+    reinclude_proxy_module
+  end
+
+  # Returns true if the specified class is a valid target of this Widget
+  def target?(base)
+    if base.respond_to?(:name)
+      name = base.name.underscore.sub(/^.*\//, '')
+      targets.each do |target|
+        if base.kind_of?(ActiveRecord::Base) # it's an instance, so we should check the tag name, not the class name
+          return true if target == base.name
+        else
+          return true if target == name
+        end
+      end
+    end
+    false
+  end
+end