wordnik 4.06.05 → 4.06.06

data/lib/wordnik/configuration.rb

@@ -1,6 +1,7 @@
 module Wordnik
 
   class Configuration
+    require 'wordnik/version'
 
     # Wordnik credentials
     attr_accessor :api_key
@@ -18,23 +19,37 @@ module Wordnik
     attr_accessor :resource_names
     
     # The URL of the API server
-    attr_accessor :base_uri
+    attr_accessor :scheme
+    attr_accessor :host
+    attr_accessor :base_path
+    
+    attr_accessor :user_agent
     
     # Defaults go in here..
     def initialize
       @response_format = :json
-      @base_uri = 'api.wordnik.com/v4'
-      
+      @scheme = 'http'
+      @host = 'api.wordnik.com'
+      @base_path = '/v4'
+      @user_agent = "ruby-#{Wordnik::VERSION}"
       # Build the default set of resource names from the filenames of the API documentation
       begin
         api_docs_path = File.join(File.dirname(__FILE__), "../../api_docs")
         @resource_names = `find #{api_docs_path} -name '*.json'`.split("\n").map {|f| f.split("/").last.sub('.json', '') }
+        true
       rescue
         raise "Problem loading the resource files in ./api_docs/"
-      end
-      
+      end      
+    end
+    
+    def base_url
+      Addressable::URI.new(
+        :scheme => self.scheme,
+        :host => self.host,
+        :path => self.base_path
+      )
     end
 
   end
 
-end
+end

data/lib/wordnik/operation.rb

@@ -6,7 +6,8 @@ module Wordnik
     include ActiveModel::Conversion
     extend ActiveModel::Naming
   
-    attr_accessor :endpoint, :http_method, :summary, :notes, :parameters, :response, :open, :nickname, :deprecated, :category, :suggested_name
+    attr_accessor :endpoint, :http_method, :summary, :notes, :parameters, :response, :open, 
+      :nickname, :deprecated, :category, :error_responses, :response_class
   
     validates_presence_of :endpoint, :http_method, :summary, :notes, :parameters, :response, :open
   
@@ -29,7 +30,7 @@ module Wordnik
         self.parameters = []
       end
       
-      self.nickname = self.suggested_name.underscore
+      self.nickname = self.nickname.underscore
     end
     
     # A globally unique identifier for the operation

data/lib/wordnik/operation_parameter.rb

@@ -6,7 +6,7 @@ module Wordnik
     include ActiveModel::Conversion
     extend ActiveModel::Naming
 
-    attr_accessor :name, :description, :required, :param_type, :default_value, :allowable_values, :param_access, :internal_description, :wrapper_name, :data_type
+    attr_accessor :name, :description, :required, :param_type, :default_value, :allowable_values, :param_access, :internal_description, :wrapper_name, :data_type, :allow_multiple
 
     def initialize(attributes = {})
       attributes.each do |name, value|
@@ -22,17 +22,15 @@ module Wordnik
       self.name.to_s
     end
 
-    def has_allowable_array?
-      self.allowable_values.present? && self.allowable_values.include?(",")
-    end
-
     def required?
       self.required || self.param_type == "path"
     end
     
     # Is this a required positional param used in a convenience method?
     def positional?
-      %w(path body).include?(self.param_type) && self.name.to_sym != :format
+      return true if self.param_type == 'body'
+      return true if self.param_type == 'path' && self.name.to_s != 'format'
+      false
     end
 
     # It's an ActiveModel thing..

data/lib/wordnik/request.rb

@@ -12,30 +12,27 @@ module Wordnik
 
     attr_accessor :host, :path, :format, :params, :body, :http_method, :headers
 
-    validates_presence_of :host, :path, :format, :http_method
+    validates_presence_of :format, :http_method
 
     # All requests must have an HTTP method and a path
     # Optionals parameters are :params, :headers, :body, :format, :host
     # 
     def initialize(http_method, path, attributes={})
-      attributes[:format] ||= "json"
-      attributes[:host] ||= Wordnik.configuration.base_uri
+      attributes[:format] ||= Wordnik.configuration.response_format
       attributes[:params] ||= {}
 
       # Set default headers
       default_headers = {
-        'User-Agent' => "Wordnik Ruby Gem #{Wordnik::VERSION}",
         'Content-Type' => "application/#{attributes[:format].downcase}",
         :api_key => Wordnik.configuration.api_key
       }
 
-      # If a nil/blank api_key was passed in, remove it from the headers, even if the override value is nil/blank
+      # api_key from headers hash trumps the default, even if its value is blank
       if attributes[:headers].present? && attributes[:headers].has_key?(:api_key)
         default_headers.delete(:api_key)
       end
       
-      # If nil/blank api_key was passed in in the params, it overrides both the default
-      # headers and the argument headers
+      # api_key from params hash trumps all others (headers and default_headers)
       if attributes[:params].present? && attributes[:params].has_key?(:api_key)
         default_headers.delete(:api_key)
         attributes[:headers].delete(:api_key) if attributes[:headers].present?
@@ -57,18 +54,30 @@ module Wordnik
     end
 
     # Construct a base URL
-    def url
-      u = Addressable::URI.new
-      u.host = self.host.sub(/\/$/, '') # Remove trailing slash
-      u.path = self.interpreted_path
-      u.scheme = "http" # For some reason this must be set _after_ host, otherwise Addressable gets upset
-      u.to_s
+    #
+    def url(options = {})  
+      u = Addressable::URI.new(
+        :scheme => Wordnik.configuration.scheme,
+        :host => Wordnik.configuration.host,
+        :path => self.interpreted_path,
+        :query => self.query_string.sub(/\?/, '')
+      ).to_s
+      
+      # Drop trailing question mark, if present
+      u.sub! /\?$/, ''
+      
+      # Obfuscate API key?
+      u.sub! /api\_key=\w+/, 'api_key=YOUR_API_KEY' if options[:obfuscated]
+      
+      u
     end
 
     # Iterate over the params hash, injecting any path values into the path string
     # e.g. /word.{format}/{word}/entries => /word.json/cat/entries
     def interpreted_path
-      p = self.path
+      p = self.path.dup
+
+      # Fill in the path params
       self.params.each_pair do |key, value|
         p = p.gsub("{#{key}}", value.to_s)
       end
@@ -80,8 +89,9 @@ module Wordnik
         p = p.sub(/^(\/?\w+)/, "\\1.#{format}")
       end
 
-      p = p.sub("{format}", self.format)
-      URI.encode(p)
+      p = p.sub("{format}", self.format.to_s)
+      
+      URI.encode [Wordnik.configuration.base_path, p].join("/").gsub(/\/+/, '/')
     end
   
     # Massage the request body into a state of readiness
@@ -97,77 +107,67 @@ module Wordnik
       @body = value
     end
     
+    # If body is an object, JSONify it before making the actual request.
+    # 
     def outgoing_body
-      return self.body if self.body.is_a? String
-      self.body.to_json
+      body.is_a?(String) ? body : body.to_json
     end
-  
-    # Iterate over all params,
-    # .. removing the ones that are part of the path itself.
-    # .. stringifying values so Addressable doesn't blow up.
-    # .. obfuscating the API key if needed.
-    def query_string_params(obfuscated=false)
-      qsp = {}
+    
+    # Construct a query string from the query-string-type params
+    def query_string
+
+      # Iterate over all params,
+      # .. removing the ones that are part of the path itself.
+      # .. stringifying values so Addressable doesn't blow up.
+      query_values = {}
       self.params.each_pair do |key, value|
         next if self.path.include? "{#{key}}"                                   # skip path params
         next if value.blank? && value.class != FalseClass                       # skip empties
-        value = "YOUR_API_KEY" if key.to_sym == :api_key && obfuscated          # obscure the API key
         key = key.to_s.camelize(:lower).to_sym unless key.to_sym == :api_key    # api_key is not a camelCased param
-        qsp[key] = value.to_s
+        query_values[key] = value.to_s
       end
-      qsp
-    end
-  
-    # Construct a query string from the query-string-type params
-    def query_string(options={})
     
       # We don't want to end up with '?' as our query string
       # if there aren't really any params
-      return "" if query_string_params.blank?
-    
-      default_options = {:obfuscated => false}
-      options = default_options.merge(options)
+      return "" if query_values.blank?
     
+      # Addressable requires query_values to be set after initialization..
       qs = Addressable::URI.new
-      qs.query_values = self.query_string_params(options[:obfuscated])
+      qs.query_values = query_values
       qs.to_s
     end
   
-    # Returns full request URL with query string included
-    def url_with_query_string(options={})
-      default_options = {:obfuscated => false}
-      options = default_options.merge(options)
-    
-      [url, query_string(options)].join('')
-    end
-  
     def make
       response = case self.http_method.to_sym
       when :get
         Typhoeus::Request.get(
-          self.url_with_query_string,
-          :headers => self.headers.stringify_keys
+          self.url,
+          :headers => self.headers.stringify_keys,
+          :user_agent => Wordnik.configuration.user_agent
         )
 
       when :post
         Typhoeus::Request.post(
-          self.url_with_query_string,
+          self.url,
           :body => self.outgoing_body,
-          :headers => self.headers.stringify_keys
+          :headers => self.headers.stringify_keys,
+          :user_agent => Wordnik.configuration.user_agent
         )
 
       when :put
         Typhoeus::Request.put(
-          self.url_with_query_string,
+          self.url,
           :body => self.outgoing_body,
-          :headers => self.headers.stringify_keys
+          :headers => self.headers.stringify_keys,
+          :user_agent => Wordnik.configuration.user_agent
         )
       
       when :delete
         Typhoeus::Request.delete(
-          self.url_with_query_string,
+          self.url,
           :body => self.outgoing_body,
-          :headers => self.headers.stringify_keys
+          :headers => self.headers.stringify_keys,
+          :user_agent => Wordnik.configuration.user_agent
         )
       end
       Response.new(response)

data/lib/wordnik/resource.rb

@@ -22,8 +22,8 @@ module Wordnik
       end
 
       # Generate Endpoint instances from JSON
-      if self.raw_data['endPoints']
-        self.endpoints = self.raw_data['endPoints'].map do |endpointData|
+      if self.raw_data['apis']
+        self.endpoints = self.raw_data['apis'].map do |endpointData|
           Endpoint.new(self, endpointData)
         end
       end 
@@ -34,7 +34,72 @@ module Wordnik
         self.class.send(:require, "wordnik/resource_modules/#{self.name}")
         self.class.send(:include, "#{self.name.to_s.camelize}Methods".constantize)
       end
-      
+    end
+
+    def write_convenience_methods
+      return unless endpoints.present?
+
+      filename = "lib/wordnik/resource_modules/#{name}.rb"
+      puts "  #{filename}"
+      file = File.new(filename, "w")
+      lines = []
+
+      lines << "# HEY HACKER! THIS IS AN AUTO-GENERATED FILE."
+      lines << "# So don't bother editing it. To see how it's built, take a look at the Rakefile\n"
+
+      lines << "module #{name.to_s.camelize}Methods\n"
+
+      endpoints.each do |endpoint|
+        endpoint.operations.each do |operation|
+
+          next if operation.nickname.blank?
+
+          # Comment about the operation
+          # (Turn newlines into commented newlines)
+          lines << "  # #{operation.summary.gsub("\n", "\n  # ")}" if operation.summary.present?
+          lines << "  # #{operation.notes.gsub("\n", "\n  # ")}" if operation.notes.present?
+          lines << "  #" if operation.summary.present?
+
+          # Start writing the method
+          lines << "  def #{operation.nickname}(#{[operation.positional_parameter_names, '*args'].flatten.join(', ')})"
+
+          # HTTP Method
+          lines << "    http_method = :#{operation.http_method}"
+
+          # Path
+          lines << "    path = '#{endpoint.path.sub(".{format}", "")}'"
+          operation.positional_parameter_names.each do |param|
+            # `body` positional params don't get injected into the path will be dealt with separately
+            next if param.to_s == 'body' 
+            lines << "    path.sub!('\{#{param}\}', #{param}.to_s)"
+          end
+
+          lines << "\n    # Ruby turns all key-value arguments at the end into a single hash"
+          lines << "    # e.g. Wordnik.word.get_examples('dingo', :limit => 10, :part_of_speech => 'verb')"
+          lines << "    # becomes {:limit => 10, :part_of_speech => 'verb'}"
+          lines << "    last_arg = args.pop if args.last.is_a?(Hash)"
+          lines << "    last_arg = args.pop if args.last.is_a?(Array)"
+          lines << "    last_arg ||= {}\n"
+
+          lines << "    # Look for a kwarg called :request_only, whose presence indicates"
+          lines << "    # that we want the request itself back, not the response body"
+          lines << "    if last_arg.is_a?(Hash) && last_arg[:request_only].present?"
+          lines << "      request_only = true"
+          lines << "      last_arg.delete(:request_only)"
+          lines << "    end\n"
+
+          lines << "    params = last_arg"
+          lines << "    body ||= {}"
+
+          lines << "    request = Wordnik::Request.new(http_method, path, :params => params, :body => body)"
+          lines << "    request_only ? request : request.response.body"
+          lines << "  end\n"
+        end      
+      end
+
+      lines << "end"
+      file.write lines.join("\n")
+      file.close
     end
 
     # It's an ActiveModel thing..

data/lib/wordnik/resource_modules/account.rb

@@ -83,32 +83,6 @@ module AccountMethods
     request_only ? request : request.response.body
   end
 
-  # Returns information about API parameters
-  #
-  def get_help(*args)
-    http_method = :get
-    path = '/account'
-
-    # Ruby turns all key-value arguments at the end into a single hash
-    # e.g. Wordnik.word.get_examples('dingo', :limit => 10, :part_of_speech => 'verb')
-    # becomes {:limit => 10, :part_of_speech => 'verb'}
-    last_arg = args.pop if args.last.is_a?(Hash)
-    last_arg = args.pop if args.last.is_a?(Array)
-    last_arg ||= {}
-
-    # Look for a kwarg called :request_only, whose presence indicates
-    # that we want the request itself back, not the response body
-    if last_arg.is_a?(Hash) && last_arg[:request_only].present?
-      request_only = true
-      last_arg.delete(:request_only)
-    end
-
-    params = last_arg
-    body ||= {}
-    request = Wordnik::Request.new(http_method, path, :params => params, :body => body)
-    request_only ? request : request.response.body
-  end
-
   # Fetches WordList objects for the logged-in user.
   #
   def get_word_lists_for_current_user(*args)

data/lib/wordnik/resource_modules/analytics.rb

@@ -0,0 +1,89 @@
+# HEY HACKER! THIS IS AN AUTO-GENERATED FILE.
+# So don't bother editing it. To see how it's built, take a look at the Rakefile
+
+module AnalyticsMethods
+
+  # Returns top hits over a year, month, week, day or hour
+  # If no time resolution parameters are passed, it returns top hits for this week. To fetch top hits for a year, pass only the year. To fetch top hits for a month, pass (year and month). To fetch top hits for a week, pass (year and week). To fetch top hits for a day, pass (year, month and day). To fetch top hits for an hour, pass (year, month, day and hour).
+  #
+  def get_top_hits(*args)
+    http_method = :get
+    path = '/analytics/top'
+
+    # Ruby turns all key-value arguments at the end into a single hash
+    # e.g. Wordnik.word.get_examples('dingo', :limit => 10, :part_of_speech => 'verb')
+    # becomes {:limit => 10, :part_of_speech => 'verb'}
+    last_arg = args.pop if args.last.is_a?(Hash)
+    last_arg = args.pop if args.last.is_a?(Array)
+    last_arg ||= {}
+
+    # Look for a kwarg called :request_only, whose presence indicates
+    # that we want the request itself back, not the response body
+    if last_arg.is_a?(Hash) && last_arg[:request_only].present?
+      request_only = true
+      last_arg.delete(:request_only)
+    end
+
+    params = last_arg
+    body ||= {}
+    request = Wordnik::Request.new(http_method, path, :params => params, :body => body)
+    request_only ? request : request.response.body
+  end
+
+  # Returns words which were trending on a given week or month
+  # If no time resolution parameters are passed, it returns trending hits for this week.
+  # To fetch trending hits for a month, pass (year and month). To fetch trending hits for a week, pass (year and week).
+  #
+  def get_trending_hits(*args)
+    http_method = :get
+    path = '/analytics/trending'
+
+    # Ruby turns all key-value arguments at the end into a single hash
+    # e.g. Wordnik.word.get_examples('dingo', :limit => 10, :part_of_speech => 'verb')
+    # becomes {:limit => 10, :part_of_speech => 'verb'}
+    last_arg = args.pop if args.last.is_a?(Hash)
+    last_arg = args.pop if args.last.is_a?(Array)
+    last_arg ||= {}
+
+    # Look for a kwarg called :request_only, whose presence indicates
+    # that we want the request itself back, not the response body
+    if last_arg.is_a?(Hash) && last_arg[:request_only].present?
+      request_only = true
+      last_arg.delete(:request_only)
+    end
+
+    params = last_arg
+    body ||= {}
+    request = Wordnik::Request.new(http_method, path, :params => params, :body => body)
+    request_only ? request : request.response.body
+  end
+
+  # Returns hits a word received in a given year, month, week or day
+  # If no time resolution parameters are passed, it returns hits the word received this week. To fetch word hits for a year, pass only the year. To fetch word hits for a month, pass (year and month). To fetch word hits for a week, pass (year and week). To fetch word hits for a day, pass (year, month and day)
+  #
+  def get_word_hits(word, *args)
+    http_method = :get
+    path = '/analytics/word/{word}'
+    path.sub!('{word}', word.to_s)
+
+    # Ruby turns all key-value arguments at the end into a single hash
+    # e.g. Wordnik.word.get_examples('dingo', :limit => 10, :part_of_speech => 'verb')
+    # becomes {:limit => 10, :part_of_speech => 'verb'}
+    last_arg = args.pop if args.last.is_a?(Hash)
+    last_arg = args.pop if args.last.is_a?(Array)
+    last_arg ||= {}
+
+    # Look for a kwarg called :request_only, whose presence indicates
+    # that we want the request itself back, not the response body
+    if last_arg.is_a?(Hash) && last_arg[:request_only].present?
+      request_only = true
+      last_arg.delete(:request_only)
+    end
+
+    params = last_arg
+    body ||= {}
+    request = Wordnik::Request.new(http_method, path, :params => params, :body => body)
+    request_only ? request : request.response.body
+  end
+
+end