rtml 1.2.2 → 2.0.0.alpha.1

data/PostInstall.txt

@@ -1,2 +1,7 @@
+After adding config.gem 'rtml' to your Rails app, don't forget to run
 
-For more information on RTML, see http://www.rubytml.com
+  script/generate rtml
+
+in order to generate rake tasks, etc.
+
+Further documentation is available at http://www.rubytml.com

data/README.rdoc

@@ -1,42 +1,127 @@
-= RTML
+= RubyTML v2.0
 
 * http://www.rubytml.com
-* http://github.com/sinisterchipmunk/rtml
 
 == DESCRIPTION:
 
-A Rails-based TML development framework for Ruby
+RubyTML (or just RTML) is a Ruby framework for communicating with Ingenico's Incendo-based payment devices.
+
+To really understand what RTML is about, you first have to understand what TML is. TML is an XML-like language called
+the "Terminal Markup Language" (yeah, we're really creative with our naming conventions around here). Essentially, it
+allows developers to write terminal applications using a syntax that is essentially XML. This is a step forward for
+terminal developers, who are used to writing their applications in embedded C.
+
+The Incendo architecture that runs all of this provides a gateway between an application server, which houses the TML,
+and the terminal. The TML is translated to byte code and then sent to the terminal via SSL. The terminal then executes
+this byte code, and only reconnects when it's ready to download a new TML application. This is another step forward
+from embedded C, because there's no longer any need to manually compile and then download applications to the terminal.
+
+However, at the end of the day it's still TML, and someone has to write that TML code. That's where I come in. I was
+brought into Ingenico to write this TML, and I found the task nothing less than daunting. I came from a Java
+background, so of course the first thing I did was start looking at ways to write Java and have it generate TML.
+Unfortunately, that was like drilling a hole with a sledgehammer, and it didn't work out too well. I quickly realized
+that I was going to spend more time writing the supporting Java code than I would on the TML itself, and given fairly
+ambitious deadlines, that just wasn't going to be an option.
+
+So I turned to Ruby. I'd been experimenting with Ruby on Rails over the past month or two, and was amazed at how
+brain-dead-simple it made standard Web development. I began to think -- what is a TML application except for a bunch of
+glorified Web services? What if Rails could do to TML and XML what it has already done to HTML?
+
+The biggest difference between HTML and TML is that the former is purely (or, in a Web 2.0 world, _almost_ purely) View
+oriented. That is, HTML is designed for marking up and displaying content, not for transforming it. TML is a bit of a
+misnomer in that respect, because it is very much about the transforming of data. It takes care of receiving and
+processing the swipe of magnetic cards, amounts, and so on. In fact, the only thing it doesn't really handle is
+actually processing a payment, which is a job left for the remote server.
+
+So the short answer to just what _is_ RTML? It's a giant DSL (Domain Specific Language), basically, designed for
+generating TML with a vast reduction in keystrokes and lines-of-code. Check out the RTML web site at www.rubytml.com
+for more information -- from tutorials to my RTML blog.
+
+== FEATURES:
+
+* It's AWESOME!
+* RTML 1.x reduced lines of code in comparison to raw TML by an average factor of 60-70%, (in some cases as much as
+  90%), and RTML 2.0 intends to improve this gain in coding efficiency even further by abstracting all repeatable tasks
+  into Widgets, which can now easily be published as Ruby Gems.
+* Widgets allow developers to write highly reusable blocks of RTML code which can then be called from an RTML
+  application as many times as needed.
+* Adapts the Rails MVC approach to TML, neatly separating TML logic from server-side Rails code, moving
+  display-oriented TML code into Views, and creating an Rtml::Transaction model which captures data sent back from a
+  TML application.
+
+
+== PROBLEMS:
+
+* RubyTML is not a total TML replacement :( You still have to follow the rules, and the overall design process isn't
+  significantly different. That's why a copy of the Incendo TML documentation is added to your Rails project when you
+  script/generate rtml.
+
+== SYNOPSIS:
+
+  Rtml.action :index, :controller => :my_app do
+    # cached document expires in 2 hours
+    expires_at { 2.hours.from_now }
+    integer :amount
+    layout 'index'                             # applies the layout in app/views/layouts/index.rtml.erb to every screen
+
+    screen :init, :next => :idle do
+      tml.amount = 0                           # sets the terminal client-side variable 'amount' to 0
+    end
+
+    screen :idle, :next => :idle do
+      display                                  # renders the view in app/views/my_app/index/idle.rtml.erb
+    end
+  end
+
+  You should also check the rdoc documentation for Rtml::Widget and the various built-in Widgets for more information
+  and usage examples. Also, don't forget to go to www.rubytml.com for many more examples and walkthroughs!
 
 == REQUIREMENTS:
 
-* Rails 2.3.5
-* Hpricot
+  * hpricot     - 0.8.2
+  * rails       - 2.3.5
+  * sc-core-ext - 1.1.1
+
+Test dependencies can be a bit of a question mark. RTML tests were actually written in rspec and make use of webrat
+for testing the TML output. There's nothing preventing you from using the standard Rails Test::Unit framework, and
+generated code will generate Test::Unit tests for you. But you need to install the following rspec-specific gems if you
+plan to run the in-application tests via "rake rtml:test" -- and enabling this will also generate rspec tests instead
+of Test::Unit ones. While there are a number of Test::Unit extensions for RTML, the unofficially official test
+framework for RTML is, obviously, rspec.
+
+  * rspec       - 1.3.0
+  * rspec-rails - 1.3.2
+  * webrat      - 0.7.0
+
+In order to activate these gems after installation, you'll also want to:
+
+  ruby script/generate rspec
 
 == INSTALL:
 
-* gem install rtml
+* sudo gem install rtml
+
+Then, Within Your Rails Application...
+
+  * config.gem 'rtml'      #=> marks RTML as an application dependency
+  * script/generate rtml   #=> generates the RTML migrations and supporting files
+  * rake rtml:test         #=> runs the entire RTML test suite within your app, to make sure all is peachy
 
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2010 FIXME full name
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2010 Colin MacKenzie IV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,33 +1,29 @@
-require 'rubygems'
-gem 'hoe', '>= 2.1.0'
-require 'hoe'
-require 'fileutils'
-require './lib/rtml'
-
-Hoe.plugin :newgem
-# Hoe.plugin :website
-# Hoe.plugin :cucumberfeatures
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.spec 'rtml' do
-  f = File.read(File.join(File.dirname(__FILE__), "app_generators/rtml/templates/rtml/lib/rtml/version.rb"))
-  f =~ /MAJOR\s*=\s*([0-9]+)/
-  maj = $~[1]
-  f =~ /MINOR\s*=\s*([0-9]+)/
-  min = $~[1]
-  f =~ /TINY\s*=\s*([0-9]+)/
-  tin = $~[1]
-  self.version = "#{maj}.#{min}.#{tin}"
-  self.developer 'Colin MacKenzie IV', 'sinisterchipmunk@gmail.com'
-  #self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
-  #self.rubyforge_name       = self.name # TODO this is default value
-  self.extra_deps = [['rails', '>= 2.3.5'], ['hpricot', '>= 0.8.2'], ['rubigen', '>= 1.5.2']]
-end
-
-require 'newgem/tasks'
-Dir['tasks/**/*.rake'].each { |t| load t }
-
-# TODO - want other tests/tasks run by default? Add them to the list
-# remove_task :default
-# task :default => [:spec, :features]
+#RTML_ROOT = File.expand_path(File.join(File.dirname(__FILE__)))
+#require 'rubygems'
+require './spec/support/rails'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'rtml' do
+  self.developer 'Colin MacKenzie IV', 'colin.mackenzie4@ingenico.com'
+  self.post_install_message = File.read('PostInstall.txt')
+  self.extra_deps           = [['rails','>= 2.3.5'], ['hpricot','>= 0.8.2'], ['sc-core-ext','>= 1.1.1'],
+                               ['rubigen','>= 1.5.2']]
+  self.extra_dev_deps       = [['rspec','>= 1.3.0'], ['rspec-rails','>= 1.3.2'], ['webrat', '>= 0.7.0']]
+  self.version              = Rtml::VERSION::STRING
+  self.readme_file          = "README.rdoc"
+end
+
+require 'newgem/tasks'
+Dir['./tasks/**/*.rake'].each { |t| load File.expand_path(t) }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]

data/app_generators/rtml/USAGE

@@ -1,5 +1,5 @@
 Description:
-  
+    
   
 Usage:
-  
+  rtml [app_name]

data/app_generators/rtml/rtml_generator.rb

@@ -32,7 +32,7 @@ class RtmlGenerator < RubiGen::Base
         end
       end
 
-      m.file "rails_template.rb", "rails_template.rb"
+      m.file "rtml_template.rb", "rtml_template.rb"
 
 #      m.dependency "install_rubigen_scripts", [destination_root, 'rtml'],
 #        :shebang => options[:shebang], :collision => :force
@@ -75,4 +75,4 @@ EOS
       test
       tmp
     )
-end
+end

data/app_generators/rtml/templates/rtml_template.rb

@@ -0,0 +1,26 @@
+#HELPERS
+def win_env?
+  RUBY_PLATFORM=~ /win32/
+end
+
+def rake(command, options = {})
+  env = options[:env] || 'development'
+  log 'rake', "#{command} in #{env} "
+  sudo = win_env? ? '' : (options[:sudo] ? 'sudo' : '')
+  rake_cmd = win_env? ? "rake.bat" : 'rake'
+  in_root { run("#{sudo} #{rake_cmd} #{command} RAILS_ENV=#{env}", false) }
+end
+
+# OPTIONS
+rake_migrations = yes?("Run migrations?")
+
+# GENERATE
+gem "rtml"
+rake "gems:install"
+
+run "ruby script/generate rtml"
+route 'map.connect_rtml :controller => "rtml"'
+
+if rake_migrations
+  rake "db:migrate"
+end

data/bin/rtml

@@ -27,10 +27,10 @@ RubiGen::Base.append_sources source
 RubiGen::Scripts::Generate.new.run(ARGV, :generator => 'rtml')
 
 Dir.chdir args.first do
-  result = system("rake#{ext} rails:template LOCATION=./rails_template.rb")
+  result = system("rake#{ext} rails:template LOCATION=./rtml_template.rb")
   if $?.to_i != 0 || result == false
     puts result || "Internal error executing command: is Rake installed?"
     exit
   end
-  File.delete("rails_template.rb")
+  File.delete("rtml_template.rb")
 end

data/builtin/controllers/rtml_controller.rb

@@ -0,0 +1,58 @@
+class RtmlController < (defined? Rails) ? ApplicationController : ActionController::Base
+  unless include?(Rtml::Controller::RenderHelpers)
+    include Rtml::Controller::BeforeFilters
+    include Rtml::Controller::RenderHelpers
+    include Rtml::Controller::RtmlHelpers
+    include Rtml::Controller::State
+    include Rtml::Controller::CacheHelpers
+    include Rtml::Controller::TemplateHelpers
+    include Rtml::Controller::UrlHelpers
+    extend Rtml::Controller::ClassMethods::RtmlActionHelpers
+  end
+
+  hide_action :rtml_document, :rtml_exception
+  hide_action :screen_layout, :embedded_app
+  helper_method :screen_layout, :embedded_app
+
+  rescue_from Exception, :with => :rtml_exception
+
+  def rtml_exception
+    add_view_path(File.expand_path(File.join(Rtml.root, 'builtin/views')))
+
+    method = (ENV['RAILS_ENV'] == 'production') ? 'rescue_action_in_public' : 'rescue_action_locally'
+
+    # to address the scenario "what if these methods were not defined due to a failing before_filter"
+    rtml = false
+    rtml = request.rtml? if request.respond_to?(:rtml?)
+    rtml = response.rtml? if response.respond_to?(:rtml?)
+
+    if (params[:error_mode] == 'rtml' || rtml) && rtml_helpers.respond_to?(method)
+      @exception = $!
+      rtml_document.reset!
+      erase_results
+      render :rtml => method
+    else
+      raise $!
+    end
+  end
+
+  def embedded_app
+    "emb://embedded.tml"
+  end
+
+  def screen_layout
+    "rtml/#{state[:model]}"
+  end
+
+  def rtml_document
+    @rtml_document ||= Rtml::Document.new(:name => "#{controller_name}/#{action_name}",
+                                          :view_paths => view_paths,
+                                          :controller => self)
+  end
+
+  protected
+  def add_view_path(path)
+    view_paths << path
+    rtml_document.view_paths << path
+  end
+end

data/builtin/models/rtml/document.rb

@@ -0,0 +1,150 @@
+class Rtml::Document < ActiveRecord::Base
+  @@ruleset_file = File.expand_path(File.join(defined?(Rails) ? Rails.root : ".", "config/tml_dom_ruleset.rb"))
+  @@ruleset_file = File.expand_path(File.join(Rtml.root, "rails_generators/rtml/templates/config/tml_dom_ruleset.rb")) unless File.file?(@@ruleset_file)
+  include Rtml::DSL
+  include Rtml::Widgets
+  include ActionController::Layout
+  layout :layout
+  
+  set_table_name 'rtml_documents'
+  has_one :root, :class_name => 'Rtml::Dom::Element', :as => :parent, :autosave => true
+  has_many :instructions, :class_name => 'Rtml::Instruction', :as => :source, :autosave => true
+  attr_reader :rules, :controller
+  delegate :render, :view_paths, :view_paths=, :to => :view
+  delegate :request, :response, :params, :flash, :to => :controller
+
+  validates_presence_of :name
+  validates_uniqueness_of :name
+
+  def initialize_with_default_document(attributes = nil)
+    if attributes
+      @controller = attributes.delete(:controller)
+      @initialize_to_empty = attributes.delete(:empty)
+      apply_document_options(attributes)
+    end
+    initialize_without_default_document(attributes)
+  end
+
+  include Rtml::InheritedInstanceVariables
+  protected_instance_variables.concat ["@controller", "@changed_attributes", "@view", "@new_record", "@initialize_to_empty", "@widget_instances", "@rules", "@root", "@attributes_cache", "@attributes"]
+  
+  def after_initialize
+    @rules = Rtml::Document.rules
+    if new_record? && !@initialize_to_empty
+      setup_default_document
+    end
+  end
+
+  # This calls root.target, because root is technically an Association object, and target retrieves the actual object.
+  # This resolves ambiguities such as root.build(), which exists as both an Association method (build a new root object)
+  # and as a Widget method (build a new RTML Element).
+  def root_with_target
+    root_without_target.nil? ? nil : root_without_target.target
+  end
+
+  alias_method_chain :root, :target
+
+  def layout(assignment = :_no_assignment)
+    if assignment != :_no_assignment
+      @layout_file = assignment
+    else
+      @layout_file
+    end
+  end
+
+  def default_template_format
+    :rtml
+  end
+
+  def cache(setting)
+    case setting
+      when :on, true, 'on', 'true', 'yes', 'allow', :yes, :allow
+        setting = 'allow'
+      when :off, false, 'off', 'false', 'no', 'deny', :no, :deny
+        setting = 'deny'
+    end
+    root.property('cache', setting)
+  end
+
+  # Resets this document so that it contains no elements, and then follows the instructions associated with this
+  # document.
+  def follow_instructions!
+    reset!
+    instructions.each { |instruction| instruction.follow(self) }
+    self
+  end
+
+  # Valid options include
+  #    :view_path => String
+  #    :view_paths => Array of Strings
+  # and are removed from the hash as they are processed.
+  #
+  # Invalid options are dropped silently.
+  #
+  def apply_document_options(options)
+    options.each do |key, value|
+      case key.to_s
+        when 'view_path', 'view_paths'
+          options.delete key
+          value = [value] unless value.kind_of?(Array)
+          self.view_paths = value.collect { |path| File.exist?(path) ? path : File.join(Rails.root, path) }
+        #else raise ArgumentError, "Key ungrecognized: #{key.inspect}"
+      end
+    end
+  end
+
+  alias_method_chain :initialize, :default_document
+
+  def reset!
+    #elements.destroy_all
+    #self.elements = []
+    root.destroy if root
+    self.root = nil
+    setup_default_document
+    self
+  end
+
+  def view
+    return @view if @view
+    @view = ActionView::Base.new(Rails.configuration.view_path, {}, @controller)
+    @view.helpers.send :include, @controller.class.master_helper_module if @controller
+    @view.template_format = 'rtml'
+    @view
+  end
+
+  def /(name)
+    if name == root.name then [root]
+    else root / name
+    end
+  end
+
+  def screens
+    root ? root.elements.select { |ele| ele.name == 'screen' } : []
+  end
+
+  def to_tml
+    during_finalization_blocks.each { |i| self.process(&i) }
+    ("<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>\n" + (root ? root.to_tml : '')).gsub(/\t/, '  ')
+  end
+
+  # You can associate a block with this method, and the block will be called as a callback when self#to_tml
+  # is called.
+  def during_finalization(&block)
+    during_finalization_blocks << block
+  end
+
+  class << self
+    def ruleset_file
+      @@ruleset_file
+    end
+
+    def rules
+      Rtml::Rules::DomRuleset.parse(ruleset_file)
+    end
+  end
+
+  private
+  def during_finalization_blocks
+    @during_finalization_blocks ||= []
+  end
+end