instrument 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Instrument, Copyright (c) 2008 Day Automation Systems, Inc.
+
+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/README

@@ -0,0 +1,97 @@
+== Instrument
+
+Homepage::  instrument.rubyforge.org[http://instrument.rubyforge.org/]
+Author::    Bob Aman  (mailto:bob@sporkmonger.com)
+Copyright:: Copyright © 2008 Day Automation Systems, Inc.
+License::   MIT
+
+== Description
+
+Instrument is a simple library for producing dynamically generated "controls"
+with various templating languages.
+
+== Features
+
+* Generate controls with Erb, Haml, Markaby, or XML Builder.  Instrument
+  doesn't care what template language you prefer.
+* Output XHTML, XML, or JSON.  Instrument doesn't care what your output
+  format is.
+
+== Example Usage
+
+  select_control = SelectControl.new(:name => "base", :selections => [
+    {:label => "One", :value => "1"},
+    {:label => "Two", :value => "2"},
+    {:label => "Three", :value => "3"},
+    {:label => "Four", :value => "4"}
+  ])
+  xhtml_output = select_control.to_xhtml
+
+or
+
+  include Instrument::ControlBuilder
+  
+  select_control(:name => "base", :selections => [
+    {:label => "One", :value => "1"},
+    {:label => "Two", :value => "2"},
+    {:label => "Three", :value => "3"},
+    {:label => "Four", :value => "4"}
+  ]).to_xhtml
+
+select_control.rb:
+
+  require "instrument"
+
+  class SelectControl < Instrument::Control
+    class Option
+      def initialize(label, value)
+        @label, @value = label, value
+      end
+  
+      attr_accessor :label
+      attr_accessor :value
+    end
+
+    def element_id
+      return self.options[:id] || self.options[:name]
+    end
+
+    def element_name
+      return self.options[:name]
+    end
+
+    def selections
+      if !defined?(@selections) || @selections == nil
+        @selections = []
+        for selection in self.options[:selections]
+          if selection.kind_of?(Hash)
+            @selections << Option.new(selection[:label], selection[:value])
+          else
+            @selections << Option.new(selection, selection)
+          end
+        end
+      end
+      return @selections
+    end
+  end
+  
+select.xhtml.haml:
+  
+  %select{:id => element_id, :name => element_name}
+    - for selection in selections
+      %option{:value => selection.value}
+        = selection.label
+
+== Requirements
+
+* Instrument has no explicit dependencies.  If you want to output Haml, you
+  will need the Haml library installed.  Same goes for any of the other
+  template languages.
+
+== Install
+
+* sudo gem install instrument
+* sudo gem install haml (optional)
+* sudo gem install erubis (optional)
+* sudo gem install markaby (optional)
+* sudo gem install builder (optional)

data/Rakefile

@@ -0,0 +1,45 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), "lib"))
+$:.unshift(lib_dir)
+$:.uniq!
+
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'spec/rake/spectask'
+
+require File.join(File.dirname(__FILE__), 'lib/instrument', 'version')
+
+PKG_DISPLAY_NAME   = 'Instrument'
+PKG_NAME           = PKG_DISPLAY_NAME.downcase
+PKG_VERSION        = Instrument::VERSION::STRING
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+
+RELEASE_NAME       = "REL #{PKG_VERSION}"
+
+RUBY_FORGE_PROJECT = PKG_NAME
+RUBY_FORGE_USER    = "sporkmonger"
+RUBY_FORGE_PATH    = "/var/www/gforge-projects/#{RUBY_FORGE_PROJECT}"
+RUBY_FORGE_URL     = "http://#{RUBY_FORGE_PROJECT}.rubyforge.org/"
+
+PKG_SUMMARY        = "Template-based Controls"
+PKG_DESCRIPTION    = <<-TEXT
+Instrument is a simple library for producing dynamically generated
+"controls" with various templating languages.
+TEXT
+
+PKG_FILES = FileList[
+    "lib/**/*", "spec/**/*", "vendor/**/*",
+    "tasks/**/*", "website/**/*",
+    "[A-Z]*", "Rakefile"
+].exclude(/database\.yml/).exclude(/[_\.]git$/)
+
+task :default => "spec:verify"
+
+WINDOWS = (RUBY_PLATFORM =~ /mswin|win32|mingw|bccwin|cygwin/) rescue false
+SUDO = WINDOWS ? '' : ('sudo' unless ENV['SUDOLESS'])
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/lib/instrument.rb

@@ -0,0 +1,27 @@
+# ++
+# Instrument, Copyright (c) 2008 Day Automation Systems, Inc.
+# 
+# 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.
+# --
+
+require "instrument/version"
+require "instrument/errors"
+require "instrument/control"
+require "instrument/control_builder"

data/lib/instrument/control.rb

@@ -0,0 +1,269 @@
+# ++
+# Instrument, Copyright (c) 2008 Day Automation Systems, Inc.
+# 
+# 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.
+# --
+
+require "instrument/version"
+require "instrument/errors"
+
+# This variable stores a list of all paths to search for when locating a
+# named control.
+$CONTROL_PATH = ["."]
+if defined?(RAILS_ROOT)
+  $CONTROL_PATH.unshift(File.join(RAILS_ROOT, "app/controls"))
+end
+
+module Instrument
+  ##
+  # The Instrument::Control class provides a simple way to render nested
+  # templates.
+  #
+  # == Example
+  #
+  #   select_control = SelectControl.new(:name => "base", :selections => [
+  #     {:label => "One", :value => "1"},
+  #     {:label => "Two", :value => "2"},
+  #     {:label => "Three", :value => "3"},
+  #     {:label => "Four", :value => "4"}
+  #   ])
+  #   xhtml_output = select_control.to_xhtml
+  class Control
+    ##
+    # Registers a template type.  Takes a symbol naming the type, and a
+    # block which takes a String as input and an Object to use as the
+    # execution context and returns the rendered template output as a
+    # String.  The block should ensure that all necessary libraries are
+    # loaded.
+    # 
+    #  @param [Array] type_list the template types being registered
+    #  @yield the block generates the template output
+    #  @yieldparam [String] the template input
+    #  @yieldparam [Object] the execution context for the template
+    def self.register_type(*type_list, &block)
+      # Ensure the @@type_map is initialized.
+      self.types
+      
+      for type in type_list
+        # Normalize to symbol
+        type = type.to_s.to_sym
+        @@type_map[type] = block
+      end
+      return nil
+    end
+    
+    ##
+    # Returns a list of registered template types.
+    #
+    #  @return [Array] a list of Symbols for the registered template types
+    #  @see Instrument::Control.register_type
+    def self.types
+      if !defined?(@@type_map) || @@type_map == nil
+        @@type_map = {}
+      end
+      return @@type_map.keys
+    end
+
+    ##
+    # Returns the processor Proc for the specified type.
+    #
+    #  @param [Array] type_list the template types being registered
+    #  @raise ArgumentError raises an error if the type is invalid.
+    #  @return [Proc] the proc that handles template execution
+    #  @see Instrument::Control.register_type
+    def self.processor(type)
+      # Normalize to symbol
+      type = type.to_s.to_sym
+
+      if !self.types.include?(type)
+        raise ArgumentError,
+          "Unrecognized template type: #{type.inspect}\n" +
+          "Valid types: " +
+          "#{(self.types.map {|t| t.inspect}).join(", ")}"
+      end
+
+      return @@type_map[type]
+    end
+
+    ##
+    # Registers subclasses with the Control base class.  Called automatically.
+    #
+    #  @param [Class] klass the subclass that is extending Control
+    def self.inherited(klass)
+      if !defined?(@@control_subclasses) || @@control_subclasses == nil
+        @@control_subclasses = []
+      end
+      @@control_subclasses << klass
+      @@control_subclasses.uniq!
+      super
+    end
+    
+    ##
+    # Looks up a Control by name.
+    #
+    #  @param [String] control_name the control name of the Control
+    #  @return [Instrument::Control, NilClass] the desired control or nil
+    #  @see Instrument::Control.control_name
+    def self.lookup(control_name)
+      for control_subclass in (@@control_subclasses || [])
+        if control_subclass.control_name == control_name
+          return control_subclass
+        end
+      end
+      return nil
+    end
+    
+    ##
+    # Creates a new Control object.  Subclasses should not override this.
+    #
+    #  @param [Hash] options a set of options required by the control
+    #  @return [Instrument::Control] the instanitated control
+    def initialize(options={})
+      @options = options
+    end
+    
+    ##
+    # Returns the options that were used to create the Control.
+    #
+    #  @return [Hash] a set of options required by the control
+    attr_reader :options
+    
+    ##
+    # Returns the Control's name.  By default, this is the control's class
+    # name, tranformed into   This method may be overridden by a Control.
+    #
+    #  @return [String] the control name
+    def self.control_name
+      return nil if self.name == "Instrument::Control"
+      return self.name.
+        gsub(/^.*::/, "").
+        gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2").
+        gsub(/([a-z\d])([A-Z])/, "\\1_\\2").
+        tr("-", "_").
+        downcase
+    end
+    
+    ##
+    # Relays to_format messages to the render method.
+    #
+    #  @param [Symbol] method the method being called
+    #  @param [Array] params the method's parameters
+    #  @param [Proc] block the block being passed to the method
+    #  @return [Object] the return value
+    #  @raise NoMethodError if the method wasn't handled
+    #  @see Instrument::Control#render
+    def method_missing(method, *params, &block)
+      if method.to_s =~ /^to_/
+        format = method.to_s.gsub(/^to_/, "")
+        self.send(:render, format, *params, &block)
+      else
+        control_class = self.class.lookup(method.to_s)
+        if control_class != nil
+          control_class.new(*params, &block)
+        else
+          raise NoMethodError,
+            "undefined method `#{method}' for " +
+            "#{self.inspect}:#{self.class.name}"
+        end
+      end
+    end
+    
+    ##
+    # Renders a control in a specific format.
+    #
+    #  @param [String] format the format name for the template output
+    #  @return [String] the rendered output in the desired format
+    #  @raise Instrument::ResourceNotFoundError if the template is missing
+    #  @raise Instrument::InvalidTemplateEngineError if type isn't registered
+    def render(format)
+      # Locate the template.
+      path = nil
+      for load_path in $CONTROL_PATH
+        full_name = File.expand_path(
+          File.join(load_path, self.class.control_name))
+
+        # Check to make sure the requested template is within the load path
+        # to avoid inadvertent rendering of say, /etc/passwd
+        next if full_name.index(File.expand_path(load_path)) != 0
+
+        templates = Dir.glob(full_name + ".#{format}.*")
+        
+        # Select the first template matched.  If there's more than one,
+        # the extras will be ignored.
+        template = templates.first
+        if template != nil
+          path = template
+          break
+        end
+      end
+
+      if path == nil
+        raise Instrument::ResourceNotFoundError,
+          "Template not found: '#{self.class.control_name}.#{format}.*'"
+      elsif File.directory?(path)
+        raise Instrument::ResourceNotFoundError,
+          "Template not found: '#{self.class.control_name}.#{format}.*'"
+      end
+
+      # Normalize to symbol
+      type = File.extname(path).gsub(/^\./, "").to_s
+      if type != "" && !self.class.types.include?(type.to_sym)
+        raise Instrument::InvalidTemplateEngineError,
+          "Unrecognized template type: #{type.inspect}\n" +
+          "Valid types: [" +
+          "#{(self.class.types.map {|t| t.inspect}).join(", ")}]"
+      end
+      raw_content = File.open(path, "r") do |file|
+        file.read
+      end
+
+      begin
+        return self.class.processor(type).call(raw_content, self)
+      rescue Exception => e
+        e.message <<
+          "\nError occurred while rendering " +
+          "'#{self.class.control_name}.#{format}.#{type}'"
+        raise e
+      end
+    end
+  end
+end
+
+# Register the default types.
+Instrument::Control.register_type(:haml) do |input, context|
+  require "haml"
+  Haml::Engine.new(input, {:attr_wrapper => "\""}).render(context)
+end
+Instrument::Control.register_type(:erb, :rhtml) do |input, context|
+  begin; require "erubis"; rescue LoadError; require "erb"; end
+  erb = Erubis::Eruby.new(input) rescue ERB.new(input)
+  erb.result(context.send(:binding))
+end
+Instrument::Control.register_type(:mab) do |input, context|
+  require "markaby"
+  Markaby::Builder.new({}, context).capture do
+    eval(input)
+  end
+end
+Instrument::Control.register_type(:rxml) do |input, context|
+  require "builder"
+  xml = Builder::XmlMarkup.new(:indent => 2)
+  eval(input, context.send(:binding))
+end