rturk 1.0.5 → 2.0.0

data/lib/rturk/builders/qualification_builder.rb

@@ -0,0 +1,68 @@
+module RTurk
+
+  class Qualification
+
+    # For more information about qualification requirements see:
+    # http://docs.amazonwebservices.com/AWSMturkAPI/2008-08-02/index.html?ApiReference_QualificationRequirementDataStructureArticle.html
+    #
+
+    COMPARATORS = {:gt => 'GreaterThan', :lt => 'LessThan', :gte => 'GreaterThanOrEqualTo',
+                   :lte => 'LessThanOrEqualTo', :eql => 'EqualTo', :not => 'NotEqualTo', :exists => 'Exists'}
+
+    TYPES = {:approval_rate => '000000000000000000L0', :submission_rate => '00000000000000000000',
+             :abandoned_rate => '0000000000000000007', :return_rate => '000000000000000000E0',
+             :rejection_rate => '000000000000000000S0', :hits_approved => '00000000000000000040',
+             :adult => '00000000000000000060', :country => '00000000000000000071'}
+
+    attr_accessor :qualifier
+
+    # Builds the basic requirements for a qualification
+    # needs at the minimum
+    #  type_id, :comparator => :value
+    #  or
+    #  type_id, true
+    #  or
+    #  type_id, :exists
+    #
+    def initialize(type, opts)
+      # If the value is a string, we can assume it's the country since,
+      # Amazon states that there can be only integer values and countries
+      self.qualifier = {}
+      if type.is_a?(String)
+        qualifier[:QualificationTypeId] = type
+      elsif type.is_a?(Symbol)
+        qualifier[:QualificationTypeId] = types[type]
+      end
+      if opts.is_a?(Hash)
+        qualifier[:Comparator] = COMPARATORS[opts.keys.first]
+        value = opts.values.first
+        if value.to_s.match(/[A-Z]./)
+          qualifier[:Country] = value
+        else
+          qualifier[:IntegerValue] = value
+        end
+      elsif opts == true || opts == false
+         qualifier[:IntegerValue] = opts == true ? 1 : 0
+         qualifier[:Comparator] = COMPARATORS[:eql]
+       end
+      qualifier
+    end
+
+    def to_params
+      params = {}
+      params["QualificationTypeId"] = qualifier[:QualificationTypeId]
+      params["Comparator"] = qualifier[:Comparator]
+      params["IntegerValue"] = qualifier[:IntegerValue] if qualifier[:IntegerValue]
+      params["LocaleValue.Country"] = qualifier[:Country] if qualifier[:Country]
+      params["RequiredToPreview"] = qualifier[:RequiredToPreview] || 'true'
+      params
+    end
+
+    def types
+      # Could use this later to add other TYPES programatically
+      TYPES
+    end
+
+  end
+
+end

data/lib/rturk/builders/qualifications_builder.rb

@@ -0,0 +1,43 @@
+module RTurk
+
+  class Qualifications
+
+    # For more information about qualification requirements see:
+    # http://docs.amazonwebservices.com/AWSMturkAPI/2008-08-02/index.html?ApiReference_QualificationRequirementDataStructureArticle.html
+    #
+
+    def to_params
+      params = {}
+      qualifications.each_with_index do |qualification, i|
+        qualification.to_params.each_pair do |k,v|
+          params["QualificationRequirement.#{i+1}.#{k}"] = v
+        end
+      end
+      params
+    end
+
+    # Can use this to manually add custom requirement types
+    # Needs a type name(you can reference this later)
+    # and the operation as a hash: ':gt => 85'
+    # Example
+    # qualifications.add('EnglishSkillsRequirement', :gt => 66, :type_id => '1234567890123456789ABC')
+    #
+    def add(type, opts)
+      qualifications << RTurk::Qualification.new(type, opts)
+    end
+    
+    def qualifications
+      @qualifications ||= []
+    end
+
+
+    def method_missing(method, *args)
+      if RTurk::Qualification::TYPES.include?(method)
+        self.add(method, *args)
+      end
+    end
+
+  end
+
+
+end

data/lib/rturk/builders/question_builder.rb

@@ -0,0 +1,51 @@
+require 'cgi'
+require 'uri'
+
+module RTurk
+  class Question
+    
+    attr_accessor :url, :url_params, :frame_height
+    
+    def initialize(url, opts = {})
+      @url = url
+      self.frame_height = opts.delete(:frame_height) || 400
+      self.url_params = opts
+    end
+    
+    def querystring
+      @url_params.collect { |key, value| [CGI.escape(key.to_s), CGI.escape(value.to_s)].join('=') }.join('&')
+    end
+    
+    def url
+      unless querystring.empty?
+        # slam the params onto url, if url already has params, add 'em with a &
+        @url.index('?') ? "#{@url}&#{querystring}" : "#{@url}?#{querystring}" 
+      else
+        @url
+      end
+    end
+    
+    def params
+      @url_params
+    end
+    
+    def params=(param_set)
+      @url_params = param_set
+    end
+    
+    def to_params
+      raise RTurk::MissingParameters, "needs a url to build an external question" unless @url
+      # TODO: update the xmlns schema... maybe
+      xml = <<-XML
+<ExternalQuestion xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2006-07-14/ExternalQuestion.xsd">
+  <ExternalURL>#{url}</ExternalURL>	
+  <FrameHeight>#{frame_height}</FrameHeight>
+</ExternalQuestion>
+      XML
+      xml
+    end
+    
+  end
+  
+  
+end

data/lib/rturk/errors.rb

@@ -0,0 +1,5 @@
+module RTurk
+  class RTurkError < StandardError; end;
+  class MissingParameters < RTurkError; end;
+  class InvalidRequest < RTurkError; end;
+end

data/lib/rturk/logger.rb

@@ -0,0 +1,20 @@
+require 'logger'
+
+module RTurk
+  class Logger
+    class << self
+      def logger=(logger_obj)
+        @logger = logger_obj
+      end
+
+      def logger
+        unless @logger
+          @logger = ::Logger.new(STDOUT)
+          @logger.level = ::Logger::INFO
+        end
+        @logger
+      end
+    end
+  end
+  
+end

data/lib/rturk/macros.rb

@@ -0,0 +1,35 @@
+module RTurk::Macros
+
+  # Attempt to expire hit, then approve assignments, and finally dispose of
+  def kill_hit(hit_id)
+    forceExpireHIT(:HITId => hit_id)
+    get_assignments_for_hit(hit_id).each do |assignment|
+      approveAssignment(:AssignmentId => assignment[:AssignmentId])
+    end
+    disposeHIT(:HITId => hit_id)
+  end
+
+  # Wipe out all HIT's associated with this account
+  def blank_slate
+    search_response = searchHITs(:PageSize => 100)
+    if search_results = search_response['SearchHITsResult']['HIT']
+      search_results.each do |hit|
+        kill_hit(hit['HITId'])
+      end
+    end
+  end
+
+  def url_for_hit(hit_id)
+    url_for_hit_type(getHIT(:HITId => hit_id)[:HITTypeId])
+  end
+
+  def url_for_hit_type(hit_type_id)
+    if @host =~ /sandbox/
+      "http://workersandbox.mturk.com/mturk/preview?groupId=#{hit_type_id}" # Sandbox Url
+    else
+      "http://mturk.com/mturk/preview?groupId=#{hit_type_id}" # Production Url
+    end
+  end
+
+
+end

data/lib/rturk/operation.rb

@@ -0,0 +1,86 @@
+module RTurk
+  class Operation
+
+    class << self
+
+      def default_params
+        @default_params ||= {}
+      end
+
+      def required_params
+        @required_params || []
+      end
+
+      def require_params(*args)
+        @required_params ||= []
+        @required_params.push(*args)
+      end
+
+      def operation(op)
+        default_params.merge!('Operation' => op)
+      end
+
+      def create(opts = {}, &blk)
+        hit = self.new(opts, &blk)
+        response = hit.request
+      end
+
+    end
+
+    ########################
+    ### Instance Methods ###
+    ########################
+
+    def initialize(opts = {})
+      opts.each_pair do |k,v|
+        if self.respond_to?("#{k.to_sym}=")
+          self.send "#{k}=".to_sym, v
+        elsif v.is_a?(Array)
+          v.each do |a|
+            (self.send k.to_s).send a[0].to_sym, a[1]
+          end
+        elsif self.respond_to?(k.to_sym)
+          self.send k.to_sym, v
+        end
+      end
+      yield(self) if block_given?
+      self
+    end
+
+    def default_params
+      self.class.default_params
+    end
+
+    def parse(xml)
+      # Override this in your operation if you like
+      RTurk::Response.new(xml)
+    end
+    
+    def to_params
+      {}# Override to include extra params
+    end
+
+    def request
+      if self.respond_to?(:validate)
+        validate
+      end
+      check_params
+      params = self.default_params
+      params = to_params.merge(params)
+      response = RTurk.Request(params)
+      parse(response)
+    end
+
+    def check_params
+      self.class.required_params.each do |param|
+        if self.respond_to?(param)
+          raise MissingParameters, "Parameter '#{param.to_s}' cannot be blank" if self.send(param).nil?
+        else
+          raise MissingParameters, "The parameter '#{param.to_s}' was required and not available"
+        end
+      end
+    end
+
+
+  end
+end

data/lib/rturk/operations/approve_assignment.rb

@@ -0,0 +1,28 @@
+# Operation to approve an assignment
+#
+# http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
+# &AWSAccessKeyId=[the Requester's Access Key ID]
+# &Version=2008-08-02
+# &Operation=ApproveAssignment
+# &Signature=[signature for this request]
+# &Timestamp=[your system's local time]
+# &AssignmentId=123RVWYBAZW00EXAMPLE456RVWYBAZW00EXAMPLE
+
+module RTurk
+  class ApproveAssignment < Operation
+
+    operation 'ApproveAssignment'
+    attr_accessor :assignment_id, :feedback
+    require_params :assignment_id
+    
+    def to_params
+      {'AssignmentId' => self.assignment_id,
+        'RequesterFeedback' => self.feedback}
+    end
+    
+  end
+  def self.ApproveAssignment(*args)
+    RTurk::ApproveAssignment.create(*args)
+  end
+
+end

data/lib/rturk/operations/create_hit.rb

@@ -0,0 +1,77 @@
+module RTurk
+  class CreateHIT < Operation
+    
+    operation 'CreateHIT'
+
+    attr_accessor :title, :keywords, :description, :reward, :currency, :assignments
+    attr_accessor :lifetime, :duration, :auto_approval, :note, :hit_type_id
+
+    # @param [Symbol, Hash] qualification_key opts The unique qualification key
+    # @option opts [Hash] :comparator A comparator and value e.g. :gt => 80
+    # @option opts [Boolean] :boolean true or false
+    # @option opts [Symbol] :exists A comparator without a value
+    # @return [RTurk::Qualifications]
+    def qualifications
+      @qualifications ||= RTurk::Qualifications.new
+    end
+    
+    # Gives us access to a question builder attached to this HIT
+    #
+    # @param [String, Hash] URL Params, if none is passed, simply returns the question
+    # @return [RTurk::Question] The question if instantiated or nil
+    def question(*args)
+      unless args.empty?
+        @question ||= RTurk::Question.new(*args)
+      else
+        @question
+      end
+    end
+    
+    # Returns parameters specific to this instance
+    #
+    # @return [Hash]
+    #   Any class level default parameters get loaded in at
+    #   the time of request
+    def to_params
+      params = map_params.merge(qualifications.to_params)
+    end
+
+    def parse(response)
+      RTurk::CreateHITResponse.new(response)
+    end
+    
+    # More complicated validation run before request
+    #
+    def validate
+      if hit_type_id
+        unless question && lifetime
+          raise RTurk::MissingParameters, "When you specify a HitTypeID, you must incude a question and lifetime length"
+        end
+      else
+        unless  title && reward && question && description
+          raise RTurk::MissingParameters, "You're missing some required parameters"
+        end
+      end
+    end
+
+    private
+
+      def map_params
+        {'Title'=>self.title,
+         'MaxAssignments' => (self.assignments || 1),
+         'LifetimeInSeconds'=> (self.lifetime || 3600),
+         'AssignmentDurationInSeconds' => (self.duration || 86400),
+         'Reward.Amount' => self.reward,
+         'Reward.CurrencyCode' => (self.currency || 'USD'),
+         'Keywords' => self.keywords,
+         'Description' => self.description,
+         'Question' => self.question.to_params,
+         'RequesterAnnotation' => note}
+      end
+
+  end
+  def self.CreateHIT(*args, &blk)
+    RTurk::CreateHIT.create(*args, &blk)
+  end
+
+end

data/lib/rturk/operations/disable_hit.rb

@@ -0,0 +1,19 @@
+# http://docs.amazonwebservices.com/AWSMturkAPI/2008-08-02/ApiReference_DisposeHITOperation.html
+module RTurk
+  class DisableHIT < Operation
+    
+    operation 'DisableHIT'
+    require_params :hit_id
+    attr_accessor :hit_id
+    
+    def to_params
+      {'HITId' => self.hit_id}
+    end
+    
+  end
+  
+  def self.DisableHIT(*args, &blk)
+    RTurk::DisableHIT.create(*args, &blk)
+  end
+  
+end