oxford_dictionary 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97d848d8c66972c3a1bb87b3e19c218912c80f360edba2bd1e991e099fddb613
-  data.tar.gz: c324040796efe1973e520938c96a343df15d08312262a10f1bf2d72f7091e7f4
+  metadata.gz: 99377db60cc25d19b09832803710b6302a81809713f160ed25c91991dbade46d
+  data.tar.gz: 98b102cbf2c4751b4d801b39e4aa7adc4d2e6a7d21a1eb42f5c156db2413da23
 SHA512:
-  metadata.gz: ec6b3db6c5b7722bb06a69b14c20393c0d24d7574efdaa640f676f03341783b63e692d024f3175bddb468ad91e5f5c28442f44d8d2b7c5ef8eaed00851746371
-  data.tar.gz: 4254c3c440308c62a3152a218646f9fba9dd4026149e001e4835e5b85de95d76ed62b6805f9e9a2cc50340b33e9d32fb8dc5fd4679a674e79dddbff6106ad271
+  metadata.gz: '03392263ed3ec7ff17d9b3347b2334285b62563c81b7475576977a356308117826579aa5680a2da86f8da712d9e86e4fe874fba6e8dcb586428dcc472b503c8a'
+  data.tar.gz: 705ea67f3ca0a7d87b3a16fa776c321f78e35718dacb985478bbff08d9259656ecfa9fda5981fa81172762b0f82a7f58ad2e74f8933103d2f29bfbd49e5cf13e

data/.rubocop.yml

@@ -0,0 +1,5 @@
+Lint/ImplicitStringConcatenation:
+  Enabled: false
+
+Style/DotPosition:
+  EnforcedStyle: trailing

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## OxfordDictionary master (unreleased)
 
+## OxfordDictionary 3.0.0 (2019-08-13)
+- Remove support for all V1 API calls
+
 ## OxfordDictionary 2.0.0 (2019-06-29)
 - Remove wordlist endpoint
   [\#20](https://github.com/swcraig/oxford-dictionary/pull/20)

data/README.md

@@ -34,6 +34,9 @@ first_lexical_entry = entry.lexicalEntries.first
 filters = { lexicalCategory: 'Verb', domains: 'Art'}
 client.entry(word: 'truth', dataset: 'en-gb', params: filters)
 
+# To have multiple values for a single filter use comma separated terms
+filters = { lexicalCategory: 'Verb,Noun' }
+
 # You can also search for the results for different datasets
 # Refer to the Oxford Dictionaries documentation for all the
 # possible datasets

data/Rakefile

@@ -3,4 +3,8 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: [:spec]
+task default: [:spec, :rubocop]
+
+task :rubocop do
+  sh 'rubocop'
+end

data/lib/oxford_dictionary/client.rb

@@ -8,7 +8,10 @@ require 'oxford_dictionary/endpoints/search'
 require 'oxford_dictionary/request'
 
 module OxfordDictionary
-  # The client object to interact with
+  # Our client class to interface with the different API endpoints
+  # This should be, in general, the only touchpoint for library use
+  #
+  # OxfordDictionary::Client.new is also aliased to OxfordDictionary.new
   class Client
     attr_reader :app_id, :app_key
 
@@ -21,183 +24,8 @@ module OxfordDictionary
       end
     end
 
-    def entry(*args)
-      if args.first.is_a?(Hash)
-        args = args.first
-        entry_endpoint.entry(
-          word: args[:word],
-          dataset: args[:dataset],
-          params: args[:params]
-        )
-      else
-        warn '''
-          The V1 interface for this library is DEPRECATED.
-          Use the new V2 interface for this
-          method instead. Reference github.com/swcraig/oxford-dictionary/pull/8
-          for more information. Specifically check out
-          OxfordDictionary::Endpoints::Entries#entry for the new interface.
-        '''
-        # Try our best
-        dataset = args[1].is_a?(Hash) && args[1][:lang] || 'en-gb'
-        has_lang = args[1].is_a?(Hash) && args[1][:lang]
-        args[1].delete(:lang) if has_lang
-
-          params = args[1]&.map do |key, value|
-            if value.is_a?(Array)
-              [key, value.join(',')]
-            else
-              [key, value]
-            end
-          end.to_h
-          parameters = params || {}
-        entry(word: args.first, dataset: dataset, params: parameters)
-      end
-    end
-
-    def entry_definitions(*args)
-      warn '''
-        Client#entry_defintions is DEPRECATED.
-        Use Client#entry instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/8 for more
-        information. Check out OxfordDictionary::Endpoints::Entries for the
-        interface to use. Specifically use it with
-        params: { fields: \'definitions\' }
-      '''
-
-      dataset = args[1].is_a?(Hash) && args[1][:lang] || 'en-gb'
-      entry(
-        word: args.first,
-        dataset: dataset,
-        params: { fields: 'definitions' }
-      )
-    end
-
-    def entry_examples(*args)
-      warn '''
-        Client#entry_examples is DEPRECATED. Use Client#entry instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/8 for more
-        information. Check out OxfordDictionary::Endpoints::Entries for the
-        interface to use. Specifically use it with
-        params: { fields: \'examples\' }
-      '''
-
-      dataset = args[1].is_a?(Hash) && args[1][:lang] || 'en-gb'
-      entry(
-        word: args.first,
-        dataset: dataset,
-        params: { fields: 'examples' }
-      )
-    end
-
-    def entry_pronunciations(*args)
-      warn '''
-        Client#entry_pronunciations is DEPRECATED.
-        Use Client#entry instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/8 for more
-        information. Check out OxfordDictionary::Endpoints::Entries for the
-        interface to use. Specifically use it with
-        params: { fields: \'pronunciations\' }
-      '''
-
-      dataset = args[1].is_a?(Hash) && args[1][:lang] || 'en-gb'
-      entry(
-        word: args.first,
-        dataset: dataset,
-        params: { fields: 'pronunciations' }
-      )
-    end
-
-    def entry_sentences(*args)
-      warn '''
-        Client#entry_sentences is DEPRECATED.
-        Use Client#sentence instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/13 for more
-        information. Check out OxfordDictionary::Endpoints::Sentences for the
-        interface to use.
-      '''
-
-      dataset = args[1].is_a?(Hash) && args[1][:lang] || 'en'
-      sentence(
-        word: args.first,
-        language: dataset,
-        params: {}
-      )
-    end
-
-    def entry_antonyms(*args)
-      warn '''
-        Client#entry_antonyms is DEPRECATED.
-        Use Client#thesaurus instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/13 for more
-        information. Check out OxfordDictionary::Endpoints::Thesaurus for the
-        interface to use. Specifically use it with
-        params: { fields: \'antonyms\' }
-      '''
-
-      thesaurus(
-        word: args.first,
-        language: 'en',
-        params: { fields: 'antonyms' }
-      )
-    end
-
-    def entry_synonyms(*args)
-      warn '''
-        Client#entry_synonyms is DEPRECATED.
-        Use Client#thesaurus instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/13 for more
-        information. Check out OxfordDictionary::Endpoints::Thesaurus for the
-        interface to use. Specifically use it with
-        params: { fields: \'synonyms\' }
-      '''
-
-      thesaurus(
-        word: args.first,
-        language: 'en',
-        params: { fields: 'synonyms' }
-      )
-    end
-
-    def entry_antonyms_synonyms(*args)
-      warn '''
-        Client#entry_antonyms_synonyms is DEPRECATED.
-        Use Client#thesaurus instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/14 for more
-        information. Check out OxfordDictionary::Endpoints::Thesaurus for the
-        interface to use. Specifically use it with
-        params: { fields: \'synonyms,antonyms\' }
-      '''
-
-      thesaurus(
-        word: args.first,
-        language: 'en',
-        params: { fields: 'antonyms,synonyms' }
-      )
-    end
-
-    def entry_translations(*args)
-      warn '''
-        Client#entry_translations is DEPRECATED.
-        Use Client#translation instead. Reference
-        https://github.com/swcraig/oxford-dictionary/pull/12 for more
-        information. Check out OxfordDictionary::Endpoints::Translations for the
-        interface to use.
-      '''
-
-      language = args[1] && args[1][:translations] || 'es'
-      translation(
-        word: args.first,
-        source_language: 'en-us',
-        target_language: language,
-        params: {}
-      )
-    end
-
-    def entry_snake_case(word:, dataset:, params: {})
-      warn 'Client#entry_snake_case is DEPRECATED. Use Client#entry instead.'
-
-      entry_endpoint.
-        entry_snake_case(word: word, dataset: dataset, params: params)
+    def entry(word:, dataset:, params:)
+      entry_endpoint.entry(word: word, dataset: dataset, params: params)
     end
 
     def lemma(word:, language:, params: {})
@@ -225,52 +53,8 @@ module OxfordDictionary
       )
     end
 
-    def search(*args)
-      if args.first.is_a?(Hash)
-        args = args.first
-        search_endpoint.search(language: args[:language], params: args[:params])
-      else
-        warn '''
-          Client#search without parameters is DEPRECATED.
-          Use the new V2 interface for this
-          method instead. Reference github.com/swcraig/oxford-dictionary/pull/15
-          for more information. Specifically check out
-          OxfordDictionary::Endpoints::Search#search for the new interface.
-        '''
-
-        language_parameter = args[1].is_a?(Hash) && args[1][:lang]
-        language = language_parameter || 'en-gb'
-        args[1].delete(:lang) if language_parameter
-
-        if args[1].is_a?(Hash) && args[1][:translations]
-          target_language = args[1][:translations]
-          args[1].delete(:translations)
-
-          params = args[1]&.map do |key, value|
-            if value.is_a?(Array)
-              [key, value.join(',')]
-            else
-              [key, value]
-            end
-          end.to_h
-          parameters = params&.merge(q: args[0]) || {}
-          search_translation(
-            source_language: language,
-            target_language: target_language,
-            params: parameters
-          )
-        else
-          params = args[1]&.map do |key, value|
-            if value.is_a?(Array)
-              [key, value.join(',')]
-            else
-              [key, value]
-            end
-          end.to_h
-          parameters = params&.merge(q: args[0]) || {}
-          search_endpoint.search(language: language, params: parameters)
-        end
-      end
+    def search(language:, params:)
+      search_endpoint.search(language: language, params: params)
     end
 
     def search_translation(source_language:, target_language:, params: {})
@@ -281,31 +65,6 @@ module OxfordDictionary
       )
     end
 
-    def inflection(*args)
-      warn '''
-          Client#inflection is DEPRECATED.
-          Use Client#lemma instead. Reference
-          github.com/swcraig/oxford-dictionary/pull/10 for for more information.
-          Check out OxfordDictionary::Endpoints::Lemmas#lemma for the interface
-          to use.
-      '''
-
-      language_parameter = args[1].is_a?(Hash) && args[1][:lang]
-      language = language_parameter || 'en'
-      args[1].delete(:lang) if language_parameter
-
-      params = args[1]&.map do |key, value|
-        if value.is_a?(Array)
-          [key, value.join(',')]
-        else
-          [key, value]
-        end
-      end.to_h
-      parameters = params || {}
-
-      lemma(word: args.first, language: language, params: parameters)
-    end
-
     private
 
     def lemma_endpoint

data/lib/oxford_dictionary/deserialize.rb

@@ -1,7 +1,17 @@
 require 'json'
 
 module OxfordDictionary
+  # A small service object that parses a JSON payload into
+  # an OpenStruct recursively. The keys of the OpenStruct
+  # are in camelCase, not snake_case. This keeps the struct
+  # more representative of the JSON in the response.
   class Deserialize
+    # Parses a JSON payload into an OpenStruct
+    # Nested objects are also parsed into OpenStructs
+    #
+    # @param [String] payload a JSON string
+    #
+    # @return [OpenStruct] the JSON parsed into OpenStructs recursively
     def call(payload)
       JSON.parse(payload, object_class: OpenStruct)
     end

data/lib/oxford_dictionary/endpoints/endpoint.rb

@@ -2,6 +2,7 @@ require 'oxford_dictionary/deserialize'
 
 module OxfordDictionary
   module Endpoints
+    # The common functionality (and dependency initialization) of all endpoints
     class Endpoint
       def initialize(request_client:)
         @request_client = request_client

data/lib/oxford_dictionary/endpoints/entries.rb

@@ -1,11 +1,24 @@
 require 'oxford_dictionary/endpoints/endpoint'
-require 'plissken'
 
 module OxfordDictionary
   module Endpoints
+    # Interface for the /entries endpoint
+    #
+    # API documentation can be found here:
+    # https://developer.oxforddictionaries.com/documentation
     class Entries < Endpoint
       ENDPOINT = 'entries'.freeze
 
+      # Return all the entries for a word
+      #
+      # @param [String] word the word to search for
+      # @param [String] dataset the dataset to search in
+      # @param [Hash] params the query parameters in the request
+      #
+      # @example Search for all domains of 'vapid' from the en-gb dataset
+      #   entry(word: 'vapid', dataset: 'en-gb', params: { fields: 'domains' })
+      #
+      # @return [OpenStruct] the JSON response parsed into an OpenStruct
       def entry(word:, dataset:, params: {})
         path = "#{ENDPOINT}/#{dataset}/#{word}"
         uri = request_uri(path: path, params: params)
@@ -13,15 +26,6 @@ module OxfordDictionary
         response = @request_client.get(uri: uri)
         deserialize.call(response.body)
       end
-
-      def entry_snake_case(word:, dataset:, params: {})
-        path = "#{ENDPOINT}/#{dataset}/#{word}"
-        uri = request_uri(path: path, params: params)
-
-        response = @request_client.get(uri: uri)
-        snake_keys = JSON.parse(response.body).to_snake_keys
-        deserialize.call(JSON.generate(snake_keys))
-      end
     end
   end
 end

data/lib/oxford_dictionary/endpoints/lemmas.rb

@@ -2,9 +2,27 @@ require 'oxford_dictionary/endpoints/endpoint'
 
 module OxfordDictionary
   module Endpoints
+    # Interface for the /lemmas endpoint
+    #
+    # API documentation can be found here:
+    # https://developer.oxforddictionaries.com/documentation
     class Lemmas < Endpoint
       ENDPOINT = 'lemmas'.freeze
 
+      # Returns all possible lemmas for a word
+      #
+      # @param [String] word the inflected word to search for
+      # @param [String] language the language to search in
+      # @param [Hash] params the query parameters in the request
+      #
+      # @example Search for the verb lemmas of 'running' in 'en'
+      #   lemma(
+      #     word: 'running',
+      #     language: 'en',
+      #     params: { lexicalCategory: 'verb' }
+      #   )
+      #
+      # @return [OpenStruct] the JSON response parsed into an OpenStruct
       def lemma(word:, language:, params: {})
         path = "#{ENDPOINT}/#{language}/#{word}"
         uri = request_uri(path: path, params: params)

data/lib/oxford_dictionary/endpoints/search.rb

@@ -2,6 +2,10 @@ require 'oxford_dictionary/endpoints/endpoint'
 
 module OxfordDictionary
   module Endpoints
+    # Interface for the /search endpoint
+    #
+    # API documentation can be found here:
+    # https://developer.oxforddictionaries.com/documentation
     class Search < Endpoint
       ENDPOINT = 'search'.freeze
 

data/lib/oxford_dictionary/endpoints/sentences.rb

@@ -2,6 +2,10 @@ require 'oxford_dictionary/endpoints/endpoint'
 
 module OxfordDictionary
   module Endpoints
+    # Interface for the /sentences endpoint
+    #
+    # API documentation can be found here:
+    # https://developer.oxforddictionaries.com/documentation
     class Sentences < Endpoint
       ENDPOINT = 'sentences'.freeze