hotwire 0.0.0 → 0.1.0

data/README.markdown

@@ -0,0 +1,82 @@
+# Hotwire
+
+Hotwire is designed to ease the pain of creating Google Wire Protocol compatible data source in Ruby. Specifically, Hotwire can make it dead simple to provide data for the Google Visualization API.
+
+This class implements a Google Visualization API Wire Protocal Datasource, as defined [here](http://code.google.com/intl/it/apis/visualization/documentation/dev/implementing_data_source.html).
+
+You can use it to wrap your custom data into a json, csv, or html output compliant with the Google Visualization APIs specifications.
+
+Google Visualization APIs define a standard format to express tabular data with typed columns. By exposing your data in such format, you can use all the existing visualizations conforming to the specification out-of-the-box to represent and analyze your data.
+
+You can read more about the GViz API here: http://code.google.com/apis/visualization.
+
+It implements most of the standard with the exclusion of:
+  * Query language (tq parameters)
+  * Caching (sig parameters)
+  * some warnings and error types in the JSON response
+
+It supports version 0.5 of the APIs.
+
+## Basic Use
+The basic use follows this pattern:
+
+* create an instance from the request params using the Hotwire::Request.from_paramsfactory method.
+* verify that the instance is valid
+* create a response object using the request.build_response method
+* add columns to the response using add_column.
+* add a dataset to the response using set_data.
+* invoke the body method to return the datasource formatted according to the Wire Protocol in the requested format.
+
+Depending on the request parameters, the body method will either return a json or csv string. When an html response is requested, nothing is returned by this class itself can be passed to a view to generate the HTML report.
+
+The dataset is expected to be a 2-dimensional array (the first index referencing the rows, the second the columns). More generally, it can be anything that supports a 2 nested iteration cycles: the first on rows, the second on columns.
+
+The columns ordering in the dataset must match the order used to add them via the add_column method. Aka, add_column must be invoked for each column in the same order used by the dataset (and expected in the produced output).
+
+## Example
+The following is a basic example of use. 
+
+    class YourController < ApplicationController
+        def yourmethod
+            data = [
+                [ Date.today, 'hello', 10 ],
+                [ Date.today - 1, 'world', 20 ]
+            ]
+            respond_to do |wants|
+                wants.json do
+                if wire_request = Hotwire::Request.from_param(params)
+                    wire_response = wire_request.build_response
+                    wire_response.add_col('date', :id => 'A' , :label => 'Date').
+                                  add_col('string', :id => 'B' , :label => 'Name').
+                                  add_col('number', :id => 'C', :label => 'Count').
+                                  set_data(data) if wire_req.valid?
+                    wire_request.body
+                else
+                    data.to_json
+                end
+            end
+        end
+    end
+
+## ToDo
+TODO: should be updated to handle version 0.6 of the API
+
+## Author ##
+Les Kiger [les@codebenders.com]
+
+## Acknowledgements
+This code is heavily based on the GVis class by Riccardo Govoni [battlehorse@gmail.com].
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Les Freeman. See LICENSE for details.

data/Rakefile

@@ -10,9 +10,10 @@ begin
     gem.email = "les@codebenders.com"
     gem.homepage = "http://github.com/lesfreeman/hotwire"
     gem.authors = ["Les Freeman"]
-    gem.add_dependency "activesupport", ">= 0"
+    # gem.add_dependency "activesupport", ">= 0"
     gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
     gem.add_development_dependency "redgreen", ">= 0"
+    gem.add_development_dependency "mocha", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/hotwire.gemspec

@@ -5,39 +5,44 @@
 
 Gem::Specification.new do |s|
   s.name = %q{hotwire}
-  s.version = "0.0.0"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Les Freeman"]
-  s.date = %q{2010-10-20}
+  s.date = %q{2010-10-25}
   s.description = %q{Hotwire is designed to ease the pain of creating Google Wire protocol compatible data source in Ruby.}
   s.email = %q{les@codebenders.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.makrdown"
+     "README.markdown"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
-     "README.makrdown",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "hotwire.gemspec",
      "lib/hotwire.rb",
-     "lib/hotwire/active_record_mixins.rb",
-     "lib/hotwire/column_headers.rb",
-     "lib/hotwire/core_extensions.rb",
-     "lib/hotwire/row.rb",
-     "lib/hotwire/table.rb",
-     "test/active_record_test_helper.rb",
+     "lib/hotwire/base.rb",
+     "lib/hotwire/request.rb",
+     "lib/hotwire/response.rb",
+     "lib/hotwire/response/base.rb",
+     "lib/hotwire/response/csv.rb",
+     "lib/hotwire/response/html.rb",
+     "lib/hotwire/response/invalid.rb",
+     "lib/hotwire/response/json.rb",
      "test/hotwire_test.rb",
+     "test/response/test_base.rb",
+     "test/response/test_csv.rb",
+     "test/response/test_html.rb",
+     "test/response/test_invalid.rb",
+     "test/response/test_json.rb",
      "test/test_active_record_mixins.rb",
-     "test/test_column_headers.rb",
-     "test/test_core_extensions.rb",
      "test/test_helper.rb",
-     "test/test_row.rb",
-     "test/test_table.rb"
+     "test/test_request.rb",
+     "test/test_response.rb"
   ]
   s.homepage = %q{http://github.com/lesfreeman/hotwire}
   s.rdoc_options = ["--charset=UTF-8"]
@@ -45,14 +50,16 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.6}
   s.summary = %q{Under the hood data transformations for the Google Wire protocol.}
   s.test_files = [
-    "test/active_record_test_helper.rb",
-     "test/hotwire_test.rb",
+    "test/hotwire_test.rb",
+     "test/response/test_base.rb",
+     "test/response/test_csv.rb",
+     "test/response/test_html.rb",
+     "test/response/test_invalid.rb",
+     "test/response/test_json.rb",
      "test/test_active_record_mixins.rb",
-     "test/test_column_headers.rb",
-     "test/test_core_extensions.rb",
      "test/test_helper.rb",
-     "test/test_row.rb",
-     "test/test_table.rb"
+     "test/test_request.rb",
+     "test/test_response.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -60,18 +67,18 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
       s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
       s.add_development_dependency(%q<redgreen>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
     else
-      s.add_dependency(%q<activesupport>, [">= 0"])
       s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
       s.add_dependency(%q<redgreen>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
     end
   else
-    s.add_dependency(%q<activesupport>, [">= 0"])
     s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
     s.add_dependency(%q<redgreen>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
   end
 end
 

data/lib/hotwire.rb

@@ -1,8 +1,14 @@
-require 'hotwire/core_extensions'
-require 'hotwire/column_headers'
-require 'hotwire/row'
-require 'hotwire/table'
+module Hotwire
+  def self.supported_api_versions
+    ["0.5"]
+  end
+end
 
-if defined? ActiveRecord::Base
-  require 'hotwire/active_record_mixins.rb'
-end
+require 'hotwire/base'
+require 'hotwire/request'
+require 'hotwire/response'
+require 'hotwire/response/base'
+require 'hotwire/response/csv'
+require 'hotwire/response/json'
+require 'hotwire/response/html'
+require 'hotwire/response/invalid'

data/lib/hotwire/base.rb

@@ -0,0 +1,44 @@
+require 'set'
+require 'csv'
+
+module Hotwire
+  class Base
+    @@error_reasons = Set.new([
+      :not_modified, :user_not_authenticated, :unknown_data_source_id, 
+      :access_denied, :unsupported_query_operation, :invalid_query, 
+      :invalid_request, :internal_error, :not_supported, 
+      :illegal_formatting_patterns, :other
+    ])
+    attr_reader :errors
+    
+    def initialize *args
+      @errors = []
+    end
+    
+    # Checks whether this instance is valid (in terms of configuration parameters)
+    # or not.
+    def valid?
+      validate
+      @errors.size == 0
+    end
+    
+    # Placeholder to be overwritten by subclasses
+    def validate
+    end
+
+    # Manually adds a new validation error. +reason+ should be a symbol detailing
+    # the cause of the errors and should be one of the +ERROR_REASONS+. 
+    # +message+ is a short descriptive message, while +detailed_message+, if 
+    # provided, can be a longer message that can include minimal html formatting
+    # (anchor tags with a single href attribute).
+    def add_error(reason, message, detailed_message=nil)
+      unless @@error_reasons.include?(reason)
+        raise ArgumentError.new("Invalid error reason: #{reason}")
+      end
+      error = {:reason => reason.to_s, :message => message}
+      error[:detailed_message] = detailed_message if detailed_message
+      @errors << error
+      return self
+    end
+  end
+end

data/lib/hotwire/request.rb

@@ -0,0 +1,60 @@
+module Hotwire
+  class Request < Hotwire::Base
+    
+    # Factory method to create a Request instance from the request parameters.
+    # +tqx:out+ is used to determine the specific class instance returned
+    # by this method, depending on the requested output format.
+    def self.from_params(params)
+      # Exract Wire params from the request.
+      wire_params = {}
+      tqx = params[:tqx]
+      return false if not tqx or tqx.blank?
+      
+      wire_params[:tqx] = true
+      tqx.split(';').each do |kv|
+        key, value = kv.split(':')
+        wire_params[key.to_sym] = value
+      end
+    
+      # Create the appropriate Wire instance from the gviz-specific parameters
+      wire_params[:out] ||= "json"    
+      self.new(wire_params)
+    end 
+  
+    # Creates a new instance and validates it. 
+    def initialize(wire_params)
+      super
+      @params = wire_params
+    end
+    protected :initialize
+    
+    # Builds a new response object from the request
+    def build_response
+      Hotwire::Response.from_request(self)
+    end
+    
+    # Validates this instance by checking that the configuration parameters
+    # conform to the official specs.
+    def validate
+      @errors.clear
+      if @params[:tqx]
+        add_error(:invalid_request, 
+                  "Missing required parameter reqId") unless @params[:reqId]
+      
+        if @params[:version] && !Hotwire.supported_api_versions.include?(@params[:version])
+          add_error(:invalid_request, "Unsupported version #{@params[:version]}")
+        end
+      end
+    end
+    
+    # Access a Wire parameter. +k+ must be symbols, like +:out+, +:reqId+.
+    def [](k)
+      @params[k]
+    end
+  
+    # Sets a Wire parameter. +k+ must be symbols, like +:out+, +:reqId+.
+    def []=(k, v)
+      @params[k] = v
+    end
+  end
+end

data/lib/hotwire/response.rb

@@ -0,0 +1,18 @@
+module Hotwire
+  module Response
+    # Factory method to create a Hotwire::Response instance from a Hotwire::Request
+    # object
+    def self.from_request(request)
+      case request[:out]
+      when "json"
+        Hotwire::Response::Json.new(request)
+      when "html"
+        Hotwire::Response::Html.new(request)
+      when "csv"
+        Hotwire::Response::Csv.new(request)
+      else
+        Hotwire::Response::Invalid.new(request)
+      end
+    end
+  end
+end

data/lib/hotwire/response/base.rb

@@ -0,0 +1,54 @@
+module Hotwire
+  module Response
+    class Base < Hotwire::Base
+      attr_reader :data, :columns
+      # Creates a new instance and validates it. 
+      def initialize(request)
+        super
+        @request = request
+        @columns = []
+        @data = []
+        @version = "0.5"
+        @coltypes = [ "boolean", "number", "string", "date", "datetime", "timeofday"]
+        @colkeys = [ :type, :id, :label, :pattern]
+      end
+    
+      # Adds a new column to the visualization. This method can be invoked as many
+      # times as the number of columns to export in the visualiation. Invocations can
+      # be chained.
+      #
+      # Invocation order is important! The same order will be expected when setting
+      # the actual data and to produce the response.
+      #
+      # +type+ must be one of the supported Wire datatypes, or an +ArgumentError+ will
+      # be raised. +params+ is an optional map to define extra column attributes. 
+      # These include: +:id+, +:label+ and +:pattern+.
+      def add_column(type, params=nil)
+        raise ArgumentError.new("Invalid column type: #{type}") if !@coltypes.include?(type)
+        params ||= {}
+        params[:type] = type
+    
+        # TODO: passing a wront type in params bypasses the previous type check.
+        @columns << params.delete_if { |k,v| !@colkeys.include?(k) }
+        return self
+      end
+      alias_method :add_col, :add_column
+  
+      # Sets the data to be exported. +data+ should be a 2-dimensional array. The 
+      # first index should iterate over rows, the second over columns. Column 
+      # ordering must be the same used in +add_col+ invokations.
+      #
+      # Anything that behaves like a 2-dimensional array and supports +each+ is
+      # a perfectly fine alternative.
+      def set_data(data)
+        @data = data
+        return self
+      end
+      
+      # Placeholder method for the subclasses to overwrite
+      def body
+      end
+    end
+    
+  end
+end

data/lib/hotwire/response/csv.rb

@@ -0,0 +1,17 @@
+module Hotwire
+  module Response
+    # Specialization responsible for producing responses in CSV format.
+    class Csv < Hotwire::Response::Base
+      def body
+        rsp = []
+        CSV::Writer.generate(rsp) do |csv|
+          csv << columns.map { |col| col[:label] || col[:id] || col[:type] }
+          data.each do |datarow|
+            csv << datarow
+          end
+        end
+        return rsp.join
+      end
+    end
+  end
+end

data/lib/hotwire/response/html.rb

@@ -0,0 +1,11 @@
+module Hotwire
+  module Response
+    # Specialization responsible for producing responses in HTML format.
+    # Invoking +response+ on this class doesn't do anything, as this class
+    # should be passed to a view and generate HTML over there.
+    class Html < Hotwire::Response::Base
+      # no need to answer anything ... response rendering is handled by
+      # an erb template.
+    end
+  end
+end

data/lib/hotwire/response/invalid.rb

@@ -0,0 +1,16 @@
+module Hotwire
+  module Response
+    # Represents an invalid set of parameters. This is used only to guarantee
+    # a return value from the factory methods, even when parameters are wrong.
+    #
+    # Invoking +valid?+ on this class will sistematically return +false+. 
+    class Invalid < Hotwire::Response::Base
+      def initialize(request)
+        super(request)
+        add_error(:invalid_request, 
+                  "Invalid output format: #{request[:out]}. " +
+                  "Valid ones are json,csv,html")
+      end
+    end
+  end
+end