rtml 1.2.2 → 2.0.0.alpha.1

data/builtin/widgets/frontend.rb

@@ -0,0 +1,71 @@
+class Rtml::Widgets::Frontend < Rtml::Widget
+  affects 'screen'
+  entry_point :display, :print
+  #disable_subprocessing!
+
+  gui do |config|
+    config.fields[:content] = :string
+    config.tooltip_message = "Add content to a screen"
+    config.initializer_arguments { |fields| [fields] }
+  end
+
+  # call-seq:
+  #    display :partial => 'path/to/partial'    #=> <display>[partial content]</display>
+  #    display :file    => 'path/to/file'       #=> <display>[file content]</display>
+  #    display "hello"                          #=> <display>hello</display>
+  #    display                                  #=> <display>[view content]</display>
+  #
+  #    print :partial => 'path/to/partial'    #=> <print>[partial content]</print>
+  #    print :file    => 'path/to/file'       #=> <print>[file content]</print>
+  #    print "hello"                          #=> <print>hello</print>
+  #    print                                  #=> <print>[view content]</print>
+  #
+  # Causes the specified content to be displayed on the screen or printed to the device's internal printer.
+  # 
+  def display(options = {}, &block)
+  end
+
+  [:print, :display].each do |method_name|
+    line = __LINE__ + 2
+    other = ([:print,:display] - [method_name]).first
+    code = <<-end_code
+      def #{method_name}(options = {}, &block)            # def display(options = {}, &block)
+        content = content_for options                     #   content = content_for options
+        options = {} unless options.kind_of?(Hash)        #   options = {} unless options.kind_of?(Hash)
+        raise_if_parent_contains('#{other}')              #   raise_if_parent_contains('print')
+        this = find_or_create(:#{method_name}, {})        #   this = find_or_create(:display, {})
+        this.elements.destroy_all                         #   this.elements.destroy_all
+        if !block_given?                                  #   if !block_given?
+          this.static_content content                     #     this.static_content content
+        end                                               #   end
+        this                                              #   this
+      end                                                 # end
+    end_code
+    eval code, binding, __FILE__, line
+  end
+
+  private
+  def find_or_create(tag_name, options)
+    this = (parent / "#{tag_name}").first
+    if this.nil?
+      this = parent.build(tag_name, options)
+    end
+    this
+  end
+
+  def raise_if_parent_contains(tag_name)
+    if parent.contains?(tag_name)
+      raise Rtml::Errors::RulesViolationError, "A screen cannot display and print simultaneously"
+    end
+  end
+
+  def content_for(object)
+    if object.kind_of?(Hash) && object.key?(:content)
+      object.delete(:content)
+    #elsif object.kind_of?(Symbol)
+      #object #{ :action => object.to_s }
+    else
+      object
+    end
+  end
+end

data/builtin/widgets/highlevel_variable_processing.rb

@@ -0,0 +1,130 @@
+class Rtml::Widgets::HighlevelVariableProcessing < Rtml::Widget
+  affects :screen
+  entry_point :terminal_variables, :tvars, :_if, :_elsif, :_else, :_end
+  shared :setvars => Rtml::HighLevel::VariableManager.new
+  disable_subprocessing!
+
+  # Provides a higher-level conditional construct as an alternative to using next and variant tags to generate
+  # a TML branch.
+  #
+  # Examples:
+  #   screen :main do
+  #     _if(tvars[:amount] == 0) { goto :amount_too_low }
+  #     _elsif(tvars[:amount] > 10000) { goto :amount_too_high }
+  #     _else { goto :swipe_card }
+  #   end
+  #
+  def _if(condition, &block)
+    scrid = "#{parent.property('id')}_if"
+    conditional_goto(scrid, condition, &block)
+  end
+
+  # Provides a higher-level conditional construct as an alternative to using next and variant tags to generate
+  # a TML branch.
+  #
+  # Examples:
+  #   screen :main do
+  #     _if(tvars[:amount] == 0) { goto :amount_too_low }
+  #     _elsif(tvars[:amount] > 10000) { goto :amount_too_high }
+  #     _else { goto :swipe_card }
+  #   end
+  #
+  def _elsif(condition, &block)
+    scrid = "#{parent.property('id')}_elsif"
+    conditional_goto(scrid, condition, &block)
+  end
+  alias _elseif _elsif
+
+  # Provides a higher-level conditional construct as an alternative to using next and variant tags to generate
+  # a TML branch.
+  #
+  # Examples:
+  #   screen :main do
+  #     _if(tvars[:amount] == 0) { goto :amount_too_low }
+  #     _elsif(tvars[:amount] > 10000) { goto :amount_too_high }
+  #     _else { goto :swipe_card }
+  #   end
+  #
+  def _else(&block)
+    scrid = "#{parent.property('id')}_else"
+    conditional_goto(scrid, nil, &block)
+  end
+
+  # Returns a handle to the list of TML variables. Follow this with an array operator to access and manipulate
+  # the variable assignments for this screen.
+  #
+  # You can use the alias #tvars for shorthand access to this method.
+  #
+  # Examples:
+  #   screen :init do                                            => <screen id="init">
+  #     terminal_variables[:amount] = 0                          =>   <setvar name="amount" lo="0" />
+  #     terminal_variables[:first_name] = 'John'                 =>   <setvar name="first_name" lo="John" />
+  #     terminal_variables[:last_name] = 'Smith'                 =>   <setvar name="last_name" lo="Smith" />
+  #     terminal_variables[:full_name] = tvars[:first_name] +    =>   <setvar name="full_name" lo="tmlvar:first_name"
+  #                                      tvars[:last_name]       =>           op="plus"        ro="tmlvar:last_name" />
+  #   end                                                        => </screen>
+  #
+  # You can also use periods instead of array operators to do the same thing:
+  #
+  # Examples:
+  #   screen :init do                                            => <screen id="init">
+  #     terminal_variables.amount = 0                            =>   <setvar name="amount" lo="0" />
+  #     terminal_variables.first_name = 'John'                   =>   <setvar name="first_name" lo="John" />
+  #     terminal_variables.last_name = 'Smith'                   =>   <setvar name="last_name" lo="Smith" />
+  #     terminal_variables.full_name = tvars.first_name +        =>   <setvar name="full_name" lo="tmlvar:first_name"
+  #                                    tvars.last_name           =>           op="plus"        ro="tmlvar:last_name" />
+  #   end                                                        => </screen>
+  def terminal_variables
+    setvars.screen ||= parent
+    setvars
+  end
+
+  alias tvars terminal_variables
+  alias tml   terminal_variables
+
+  private
+  def conditional_goto(scrid, condition, &blk)
+    unless (document.root / "screen[id='#{scrid}']").empty?
+      scrid = "#{scrid}_#{widget_id}"
+    end
+    destination = parent.property('next') || ((c = parent / 'next').empty? ? 'assert' : c.first.property('uri'))
+    if condition.nil?
+      parent.goto scrid
+      parent.property('next', nil)
+    else
+      parent.goto scrid, :if => condition
+    end
+    r = document.screen(scrid, :next => destination)
+
+
+    method_name = "method_wrapper_for_#{scrid}"
+    block = blk
+
+    (class << r; self; end).instance_eval do
+      define_method method_name, &block
+      new_method = instance_method(method_name)
+      define_method method_name do
+        new_method.bind(self).call
+      end
+    end
+
+    ret = r.send(method_name)
+    if r.elements.length == 1 && (nxt = r.elements.first).name == 'next' && nxt.elements.empty?
+      # all user did was "goto" -- that should result in a variant in parent, not a whole new screen.
+      # This is mostly for TML legibility.
+      if condition.blank?
+        parent.goto nxt.property('uri')
+      else
+        parent.goto nxt.property('uri'), :if => condition
+      end
+      document.remove_screen(r)
+    end
+    
+    ret
+#    r
+  end
+
+  def document
+    @document ||= parent.document
+  end
+end

data/builtin/widgets/screen_variable_processing.rb

@@ -0,0 +1,63 @@
+class Rtml::Widgets::ScreenVariableProcessing < Rtml::Widget
+  include Rtml::TmlizedConditions
+  affects :screen
+  entry_point :set
+
+  # Sets one or more TML variables to specified values.
+  # Examples:
+  #   screen :main do
+  #     set :counter => 'tmlvar:counter + 1',
+  #         :amount => 100
+  #   end
+  #
+  def set(assignments)
+    variables = parent.document.variable_definitions(:all).collect { |c| c[:name] }
+    format = assignments.delete(:format)
+
+    assignments.each do |key, value|
+      if variables.include?(key.to_s)
+        options = options_for(value_or_condition(value)).merge(:name => key, :format => format)
+        #options.each { |key, value| options.delete(key) if value.nil? }
+        build :setvar, validate_options(options)
+      else
+        raise Rtml::Errors::InvalidOptionError, "Variable named #{key} is not defined"
+      end
+    end
+  end
+
+  private
+  def validate_options(hash)
+    hash.each do |key, value|
+      if key == :lo || key == :ro
+        case value
+          when Numeric, String, Symbol, TrueClass, FalseClass, NilClass
+          else
+            raise ArgumentError, "Incompatible type: #{value}"
+        end
+      end
+    end
+    hash
+  end
+
+  def options_for(value_or_array)
+    if value_or_array.kind_of? Array
+      value_or_array = tmlize_condition(*value_or_array)
+      { :lo => value_or_array[0], :op => value_or_array[1], :ro => value_or_array[2] }
+    else
+      { :lo => value_or_array }
+    end
+  end
+
+  def value_or_condition(value)
+    if value.kind_of? String
+      operands = value.split
+      if operands.length == 3
+        operands
+      else
+        value
+      end
+    else
+      value
+    end
+  end
+end

data/builtin/widgets/screen_variants.rb

@@ -0,0 +1,110 @@
+class Rtml::Widgets::ScreenVariants < Rtml::Widget
+  include Rtml::TmlizedConditions
+  affects :screen
+  entry_point :variant, :next, :next_screen, :goto
+  disable_subprocessing! # we don't support it
+
+  # Builds a TML next element. If the element already exists, its URI is changed.
+  # If an :if or :unless option is provided, builds a variant instead.
+  # See Rtml::Rules::ExpressionProcessing for information about the :if and :unless options.
+  # Other options include :timeout, which specifies a timeout interval, or :key, which specifies
+  # a trigger key.
+  # Examples:
+  #   screen :main do
+  #     next_screen :terminate_loop
+  #     next_screen :loop_again, :if => 'tmlvar:counter < tmlvar:loop_count'
+  #   end
+  def next(uri, options = {})
+    unless options.empty?
+      variant process_variant_options(options.merge(:uri => uri))
+    else
+      next_element = (parent / 'next').first
+      if next_element
+        next_element.property('uri',  uri)
+      else
+        next_opts = { :uri => uri }
+        next_opts[:timeout] = options[:timeout] if options.key?(:timeout)
+        parent.property('next', '')
+        parent.build(:next, next_opts)
+      end
+    end
+  end
+  alias next_screen next
+  alias goto next
+
+  # Builds a TML variant element. If the corresponding NEXT element does not exist, then it is created. Its
+  # attributes are inferred from the screen's NEXT property, if any. If the NEXT element neither exists nor
+  # can be inferred, its URI will be set to raise an assertion error (#assert). If a variant already exists
+  # with the same conditions, its URI will be replaced.
+  # Examples:
+  #   screen :main, :next => :terminate_loop do
+  #     variant :uri => :loop_again, :lo => 'tmlvar:counter', :op => 'less', :ro => 'tmlvar:loop_count'
+  #   end
+  def variant(options)
+    options = options.with_indifferent_access
+    validate_options(options, :variant)
+    default_next = parent.property('next')
+    next_element = (parent / 'next').first
+    unless next_element
+      if default_next.blank?
+        next_element = parent.build(:next, :uri => 'assert')
+#        raise Rtml::Errors::ScreenVariantError, "NEXT element does not exist, and could not infer destination"
+      else
+        next_element ||= parent.build(:next, :uri => default_next) # if it doesn't exist, create it.
+      end
+    end
+    variants = (next_element / "variant")
+    variants.each do |variant|
+      # If variant contains the same conditions, replace the URI and return.
+      if (variant.property('lo') == options[:lo] && variant.property('ro') == options[:ro] && variant.property('op') == options[:op]) ||
+          (options.key?('key') && variant.property('key') == options[:key]) ||
+          (options.key?('timeout') && variant.property('timeout') == options[:timeout])
+        variant.property('uri', options[:uri])
+        return variant
+      end
+    end
+    next_element.build(:variant, options)
+  end
+
+  private
+  def process_variant_options(options)
+    ret = {}
+    if options[:lo] || options[:ro] || options[:op]
+      options.delete(:unless)
+      options[:if] = [options.delete(:lo), options.delete(:op), options.delete(:ro)]
+    end
+    if options[:unless] || options[:if]
+      ret[:lo], ret[:op], ret[:ro] = process_condition((options[:unless] ? :unless : :if),
+                                                       options[:unless] || options[:if])
+    end
+    [:uri, :timeout, :key, :format].each { |k| ret[k] = options[k] if options.key?(k) }
+    ret
+  end
+
+  def process_condition(condition_type, condition)
+    condition = condition.split if condition.kind_of?(String)
+    tmlize_condition(*(condition + [condition_type]))
+  end
+
+  def validate_options(options, type)
+    case type
+      when :variant
+        if options.key?(:uri)
+          options_valid = if options.key?(:lo) && options.key?(:ro) && options.key?(:op)
+            true
+          elsif not options.key?(:lo) && options.key?(:ro) && options.key?(:op)
+            options.key?(:key) || options.key?(:timeout)
+          end
+          unless options_valid
+            if options.key?(:lo) || options.key?(:op) || options.key?(:op)
+              raise ArgumentError, "Expected :lo, :ro, :op options; see TML docs"
+            else
+              raise ArgumentError, "Expected condition or :key or :timeout options; see TML docs"
+            end
+          end
+        else
+          raise ArgumentError, "All variants must include a :uri option"
+        end
+    end
+  end
+end

data/builtin/widgets/screens.rb

@@ -0,0 +1,73 @@
+class Rtml::Widgets::Screens < Rtml::Widget
+  affects :document
+  entry_point :screen, :remove_screen
+
+  gui do |config|
+    config.entry_points = :screen
+    config.fields[:name] = :string
+    config.fields[:next] = { :caption => "Next Screen", :type => :screen_ref }
+    config.tooltip_message = "Create a basic TML Screen"
+    config.initializer_arguments { |fields| [ fields.delete(:name), fields ] }
+  end
+
+  # Creates or modifies a screen with the specified name.
+  # If a second argument is specified, it is expected to be the ID of the next screen in the flow.
+  # Various configuration options may also be supplied as the last argument.
+  #
+  # Examples:
+  #  document.process do
+  #    screen :init, :idle do
+  #      . . .
+  #    end
+  #
+  #    screen :idle, :main, :timeout => 3 do
+  #      . . .
+  #    end
+  #
+  #    screen :main, :on => { :cancel => :init } do
+  #      . . .
+  #    end
+  #  end
+  #
+  def screen(name, *args)
+    options = args.extract_options!
+    raise ArgumentError, "Too many arguments" if args.length > 1
+    next_screen = args.shift || options.delete(:next_screen) || options.delete(:next)
+    next_screen = next_screen.property('id') if next_screen.kind_of?(Rtml::Dom::ScreenElement)
+
+    properties = { :next => next_screen,
+                   :timeout => options.delete(:timeout)
+                 }
+    # remove nil properties so they aren't generated
+    [:next, :timeout].each { |p| properties.delete(p) unless properties[p] }
+    properties[:id] = name
+
+    if scr = document.screens.select { |s| s.property('id').to_s == name.to_s }.first
+      scr.update_properties(properties)
+      scr
+    else
+      raise "No root element within document!" if parent.root.blank?
+      parent.root.build :screen, properties
+    end
+  end
+
+  # Removes the specified screen or any screen with the specified screen ID.
+  # Examples:
+  #   remove_screen :main
+  #
+  #   main = document.screen(:main) { . . . }
+  #   remove_Screen main
+  #
+  def remove_screen(scr_or_id)
+    case scr_or_id
+      when String, Symbol
+        (parent / "screen[id=#{scr_or_id}]").each do |ele|
+          root.elements.delete(ele)
+        end
+      else
+        root.elements.select { |ele| ele.name == 'screen' && ele.property('id') == scr_or_id.property('id') }.each do |ele|
+          root.elements.delete ele
+        end
+    end
+  end
+end