Wordniky 1.0.0.pre.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb285be6781866ad44de110aa686d8372b3616634cc07f9b585d23193bb7f826
+  data.tar.gz: 60bc52a1e5a023c2e7815acd15b8f6e6aa2e6945b3f364fb73e2fae3dd8b566b
+SHA512:
+  metadata.gz: 9b7643e1db0df417999b5571783ef63339a50f91ae0cd3aba8fae2e3f90e0b1271d843cfd445d6fc8343b24bcb22a0630be3afc728448ce91039e186e807a950
+  data.tar.gz: 127be08e658425ed5b178c7d949f9b284012a501f753a028c86ad18b83374470bf8cf97478bf66d3de8b884d4cd98dcc910299c00e1cfa261d7460aae07cf29d

data/lib/wordnik/client.rb

@@ -0,0 +1,434 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module Wordnik
+  class Error < StandardError; end
+
+  class Client
+    attr_accessor :configuration, :clean_up
+
+    # Initializes a new Wordnik::Client object.
+    # @param configuration [Wordnik::Configuration] the configuration to use.
+    # @param clean_up [Boolean] whether to clean up the results. Default is true.
+    #      If true, the results will be cleaned up in various ways. Generally, this means
+    #      404 (Missing) results will be returned as empty arrays. Other results will generally
+    #      be cleaned up to return arrays. Etyomologies will be cleaned up to remove XML tags.
+    def initialize(configuration: nil, http_client: nil, clean_up: true)
+      @configuration = configuration || Configuration.new
+      @http_client = http_client || create_net_https_client
+      @clean_up = clean_up
+    end
+
+    # Fetches audio metadata for a word.
+    # @param word [String] the word to fetch audio metadata for.
+    # @param limit [Integer] the maximum number of results to return. Default is 50.
+    # @return [Array] Array of hashes containing audio metadata.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def audio(word, limit = 50)
+      params = { limit: limit }
+      results = call_with_path("word.json/#{word}/audio", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up && results.is_a?(Hash) ? [] : results
+    end
+
+    # Fetches definitions for a word.
+    # @param word [String] the word to fetch definitions for.
+    # @param limit [Integer] the maximum number of results to return. Default is 200.
+    # @param part_of_speech [String, Array<String>] the parts of speech to filter by. This can be
+    #                       a single string or an array of strings. Default is nil.
+    #                       If a single string is provided, it should be comma-separated values
+    #                       (e.g. "noun,verb") or just "noun"
+    # @param source_dictionaries [String, Array<String>] the source dictionaries to filter by.
+    #                       This can be a single string or an array of strings. Default is nil.
+    #                       If a single string is provided, it should be comma-separated values
+    #                       (e.g. "wiktionary,wordnet") or just "wordnet"
+    # @return [Array] Array of hashes containing definitions.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def definitions(word, limit: 200, part_of_speech: nil, source_dictionaries: nil)
+      params = { limit: limit }
+      params[:part_of_speech] = ensure_csv(part_of_speech) if part_of_speech
+      params[:source_dictionaries] = ensure_csv(source_dictionaries) if source_dictionaries
+      results = call_with_path("word.json/#{word}/definitions", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up ? results.select { |r| r[:text] } : results
+    end
+
+    alias defs definitions
+
+    # Fetches etymologies for a word.
+    # @param word [String] the word to fetch etymologies for.
+    # @return [Array] Array of strings containing etymologies.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def etymologies(word)
+      params = {}
+      results = call_with_path("word.json/#{word}/etymologies", params)
+      # foolishly, the API returns a 500 error if the word is not found
+      raise Wordnik::Error, results[:message] if results.is_a?(Hash) && results[:status_code] != 500
+
+      if @clean_up && results.is_a?(Hash)
+        []
+      elsif results.is_a?(Array)
+        results.map { |r| cleanup_etymology_result(r) }
+      else
+        results
+      end
+    end
+
+    # Fetches examples for a word.
+    # @param word [String] the word to fetch examples for.
+    # @param include_duplicates [Boolean] whether to include duplicate examples
+    # @param skip [Integer] the number of examples to skip. Default is 0.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array, Hash] Array of hashes containing examples, or a hash with an examples: key.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def examples(word, include_duplicates: false, skip: 0, limit: 10)
+      params = { limit: limit }
+      params[:include_duplicates] = include_duplicates if include_duplicates
+      params[:skip] = skip if skip&.positive?
+      results = call_with_path("word.json/#{word}/examples", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      if @clean_up && is_404?(results)
+        []
+      elsif @clean_up && results.is_a?(Hash)
+        results[:examples]
+      else
+        results
+      end
+    end
+
+    # Fetches frequency data for a word.
+    # @param word [String] the word to fetch frequency data for.
+    # @param start_year [Integer] the start year for the frequency data. Defaults to 1800.
+    # @param end_year [Integer] the end year for the frequency data. Defaults to 2012.
+    # @return [Array, Hash] Array of hashes containing frequency data, or a hash with a frequency: key.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def frequency(word, start_year: nil, end_year: nil)
+      params = {}
+      params[:start_year] = start_year if start_year
+      params[:end_year] = end_year if end_year
+      results = call_with_path("word.json/#{word}/frequency", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      if @clean_up && is_404?(results)
+        []
+      elsif @clean_up && !is_404?(results)
+        frequencies = results[:frequency]
+        # convert the years to integers
+        # and convert the counts to integers
+        frequencies.each do |f|
+          f[:year] = f[:year].to_i
+          f[:count] = f[:count].to_i
+        end
+        frequencies
+      else
+        results
+      end
+    end
+
+    # Fetches hyphenation data for a word.
+    # @param word [String] the word to fetch hyphenation data for.
+    # @param source_dictionary [String] the source dictionary to use. Default is nil.
+    # @param limit [Integer] the maximum number of results to return. Default is 50.
+    # @return [Array] Array of hashes containing hyphenation data.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def hyphenation(word, source_dictionary: nil, limit: 50)
+      params = { limit: limit }
+      params[:source_dictionary] = source_dictionary if source_dictionary
+      results = call_with_path("word.json/#{word}/hyphenation", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up && is_404?(results) ? [] : results
+    end
+
+    # Fetches phrases for a word.
+    # @param word [String] the word to fetch phrases for.
+    # @param limit [Integer] the maximum number of results to return. Default is 5.
+    # @param wlmi [Integer] the minimum weighted mutual information for the phrases returned. What is wlmi?
+    #                       I don't know.
+    # @return [Array] Array of hashes containing phrases.
+    # @raise [Wordnik::Error] if some error is returned
+    def phrases(word, limit: 5, wlmi: nil)
+      params = { limit: limit }
+      params[:wlmi] = wlmi if wlmi
+      results = call_with_path("word.json/#{word}/phrases", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up && is_404?(results) ? [] : results
+    end
+
+    # Fetches pronunciations for a word.
+    # @param word [String] the word to fetch pronunciations for.
+    # @param source_dictionary [String] the source dictionary to use. Default is nil (meaning all)
+    # @param type_format [String] the type format to use. Default is nil (meaning all)
+    # @param limit [Integer] the maximum number of results to return. Default is 50.
+    # @return [Array] Array of hashes containing pronunciations.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def pronunciations(word, source_dictionary: nil, type_format: nil, limit: 50)
+      params = { limit: limit }
+      params[:source_dictionary] = source_dictionary if source_dictionary
+      params[:type_format] = type_format if type_format
+      results = call_with_path("word.json/#{word}/pronunciations", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      if @clean_up
+        if is_404?(results)
+          []
+        else
+          type_format ? results.select { |r| r[:raw_type] == type_format } : results
+        end
+      else
+        results
+      end
+    end
+
+    # Fetches related words for a word.
+    # @param word [String] the word to fetch related words for.
+    # @param relationship_types [String, Array<String>] the relationship types to fetch.
+    #                     This can be a single string or an array of strings. Default is nil.
+    #                       If a single string is provided, it should be comma-separated values
+    #                       (e.g. "form,equivalent") or just "form"
+    # @param limit_per_relationship_type [Integer] the maximum number of results to return per relationship type.
+    def related_words(word, relationship_types: nil, limit_per_relationship_type: 10)
+      params = { limit_per_relationship_type: limit_per_relationship_type }
+      params[:relationship_types] = ensure_csv(relationship_types) if relationship_types
+      results = call_with_path("word.json/#{word}/relatedWords", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up && is_404?(results) ? [] : results
+    end
+
+    # Fetches the Scrabble score for a word.
+    # @param word [String] the word to fetch the Scrabble score for.
+    # @return [Integer] the Scrabble score for the word.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def scrabble_score(word, params = {})
+      results = call_with_path("word.json/#{word}/scrabbleScore", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      if @clean_up && is_404?(results)
+        0
+      elsif @clean_up && results.is_a?(Hash)
+        results[:value]
+      else
+        results
+      end
+    end
+
+    # Fetches the top example for a word.
+    # @param word [String] the word to fetch the top example for.
+    # @return [Hash] the top example for the word.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def top_example(word)
+      params = {}
+      results = call_with_path("word.json/#{word}/topExample", params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      if @clean_up && is_404?(results)
+        {}
+      elsif @clean_up && results.is_a?(Hash)
+        results
+      else
+        results
+      end
+    end
+
+    # Fetches a random word.
+    # @param has_dictionary_def [Boolean] only return words with dictionary definitions, defaults to true.
+    # @param include_part_of_speech [String, Array<String>] the parts of speech to include. Default is nil, meaning all.
+    #              This can be a single string or an array of strings.
+    #              If a single string is provided, it should be comma-separated values,
+    #              (e.g. "noun,verb") or just "noun"
+    # @param exclude_part_of_speech [String, Array<String>] the parts of speech to exclude. Default is ni, meaning none.
+    #              This can be a single string or an array of strings.
+    #              If a single string is provided, it should be comma-separated values,
+    #              (e.g. "noun,verb") or just "noun"
+    # @param min_corpus_count [Integer] the minimum corpus count for the word, defaults to nil, meaning no minimum.
+    # @param max_corpus_count [Integer] the maximum corpus count for the word, defaults to nil, meaning no maximum.
+    # @param min_dictionary_count [Integer] the minimum dictionary count for the word, defaults to nil, meaning none.
+    # @param max_dictionary_count [Integer] the maximum dictionary count for the word, defaults to nil, meaning none.
+    # @param min_length [Integer] the minimum length of the word, defaults to nil, meaning no minimum.
+    # @param max_length [Integer] the maximum length of the word, defaults to nil, meaning no maximum.
+    # @return [String, Hash] the random word.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def random_word(has_dictionary_def: true, include_part_of_speech: nil, exclude_part_of_speech: nil,
+                    min_corpus_count: nil, max_corpus_count: nil, min_dictionary_count: nil, max_dictionary_count: nil,
+                    min_length: nil, max_length: nil)
+      params = {}
+      params[:has_dictionary_def] = has_dictionary_def if has_dictionary_def
+      params[:include_part_of_speech] = ensure_csv(include_part_of_speech) if include_part_of_speech
+      params[:exclude_part_of_speech] = ensure_csv(exclude_part_of_speech) if exclude_part_of_speech
+      params[:min_corpus_count] = min_corpus_count if min_corpus_count
+      params[:max_corpus_count] = max_corpus_count if max_corpus_count
+      params[:min_dictionary_count] = min_dictionary_count if min_dictionary_count
+      params[:max_dictionary_count] = max_dictionary_count if max_dictionary_count
+      params[:min_length] = min_length if min_length
+      params[:max_length] = max_length if max_length
+      results = call_with_path('words.json/randomWord', params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up ? results[:word] : results
+    end
+
+    def random_words(has_dictionary_def: true, include_part_of_speech: nil, exclude_part_of_speech: nil,
+                     min_corpus_count: nil, max_corpus_count: nil, min_dictionary_count: nil, max_dictionary_count: nil,
+                     min_length: nil, max_length: nil, limit: 10)
+      params = { limit: limit }
+      params[:has_dictionary_def] = has_dictionary_def if has_dictionary_def
+      params[:include_part_of_speech] = ensure_csv(include_part_of_speech) if include_part_of_speech
+      params[:exclude_part_of_speech] = ensure_csv(exclude_part_of_speech) if exclude_part_of_speech
+      params[:min_corpus_count] = min_corpus_count if min_corpus_count
+      params[:max_corpus_count] = max_corpus_count if max_corpus_count
+      params[:min_dictionary_count] = min_dictionary_count if min_dictionary_count
+      params[:max_dictionary_count] = max_dictionary_count if max_dictionary_count
+      params[:min_length] = min_length if min_length
+      params[:max_length] = max_length if max_length
+      results = call_with_path('words.json/randomWords', params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up ? results.map { |w| w[:word] } : results
+    end
+
+    # reverse_dictionary is deprecated
+    # def reverse_dictionary(word, params = {})
+    #   call_with_path("words.json/reverseDictionary", params)
+    # end
+
+    # search is deprecated
+    # def search(query, params = {})
+    #   call_with_path("words.json/search/#{query}", params)
+    # end
+
+    def word_of_the_day(date: nil)
+      params = {}
+      params[:date] = date if date
+      results = call_with_path('words.json/wordOfTheDay', params)
+      raise Wordnik::Error, results[:message] if is_error?(results)
+
+      @clean_up && results == '' ? nil : results
+    end
+
+    alias wotd word_of_the_day
+
+    ## Extras!
+
+    # Fetches rhymes for a word.
+    # @param word [String] the word to fetch rhymes for.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array] Array of antonyms.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def rhymes(word, limit: 10)
+      related_words(word, relationship_types: :rhyme, limit_per_relationship_type: limit).map do |r|
+        r[:words]
+      end.flatten
+    end
+
+    # Fetches antonyms for a word.
+    # @param word [String] the word to fetch antonyms for.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array] Array of antonyms.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def antonyms(word, limit: 10)
+      related_words(word, relationship_types: :antonym, limit_per_relationship_type: limit).map do |r|
+        r[:words]
+      end.flatten
+    end
+
+    # Fetches synonyms for a word.
+    # @param word [String] the word to fetch synonyms for.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array] Array of antonyms.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def synonyms(word, limit: 10)
+      related_words(word, relationship_types: :synonym, limit_per_relationship_type: limit).map do |r|
+        r[:words]
+      end.flatten
+    end
+
+    # Fetches hypernyms for a word.
+    # @param word [String] the word to fetch hypernyms for.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array] Array of antonyms.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def hypernyms(word, limit: 10)
+      related_words(word, relationship_types: :hypernym, limit_per_relationship_type: limit).map do |r|
+        r[:words]
+      end.flatten
+    end
+
+    # Fetches hyponyms for a word.
+    # @param word [String] the word to fetch hyponyms for.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array] Array of antonyms.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def hyponyms(word, limit: 10)
+      related_words(word, relationship_types: :hyponym, limit_per_relationship_type: limit).map do |r|
+        r[:words]
+      end.flatten
+    end
+
+    # Fetches equivalents for a word.
+    # @param word [String] the word to fetch equivalents for.
+    # @param limit [Integer] the maximum number of results to return. Default is 10.
+    # @return [Array] Array of antonyms.
+    # @raise [Wordnik::Error] if some error is returned by the API.
+    def equivalents(word, limit: 10)
+      related_words(word, relationship_types: :equivalent, limit_per_relationship_type: limit).map do |r|
+        r[:words]
+      end.flatten
+    end
+
+    private
+
+    def create_net_https_client
+      client = Net::HTTP.new(@configuration.api_host, @configuration.api_port)
+      client.use_ssl = true
+      client
+    end
+
+    def call(url, params)
+      params[:api_key] = @configuration.api_key
+      uri = URI.parse(url)
+      uri.query = URI.encode_www_form(params)
+      response = @http_client.get(uri)
+      JSON.parse(response.body, symbolize_names: true)
+    end
+
+    def compose_url(path)
+      "https://#{configuration.api_host}/#{configuration.api_version}/#{path}"
+    end
+
+    def normalize_params(params)
+      Wordnik.to_camel_case(params)
+    end
+
+    def call_with_path(path, params)
+      url = compose_url(path)
+      params = normalize_params(params)
+      b = call(url, params)
+      Wordnik.to_snake_case(b)
+    end
+
+    def ensure_csv(value)
+      value.is_a?(Array) ? value.join(',') : value
+    end
+
+    def cleanup_etymology_result(result)
+      # looks like this: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ety>[AS. <ets>hÔøΩsian</ets>.]</ety>\n"
+      # want to return this: "AS. hÔøΩsian"
+      result.gsub(/<.*?>/, '').gsub(/[\n\r]/, '').gsub(/[\[\]]/, '').strip
+    end
+
+    def is_404?(result)
+      result.is_a?(Hash) && result[:status_code] == 404
+    end
+
+    def is_error?(result)
+      result.is_a?(Hash) && result[:status_code] && result[:status_code] != 200 && result[:status_code] != 404
+    end
+  end
+end

data/lib/wordnik/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Wordnik
+  class Configuration
+    attr_accessor :api_key, :api_host, :api_port, :api_version, :connection
+
+    def initialize
+      defaults = {
+        api_host: 'api.wordnik.com',
+        api_port: 443,
+        api_version: 'v4'
+      }
+      loaded = look_for_config_file
+      @api_key = loaded['api_key'] || ENV['WORDNIK_API_KEY']
+      @api_host = loaded['api_host'] || defaults[:api_host]
+      @api_port = loaded['api_port'] || defaults[:api_port]
+      @api_version = loaded['api_version'] || defaults[:api_version]
+      return unless @api_key.nil?
+
+      raise 'No API key found. Please set it in the environment variable WORDNIK_API_KEY or in a .wordnik.yml file'
+    end
+
+    def look_for_config_file
+      if File.exist?('.wordnik.yml')
+        YAML.load_file('.wordnik.yml')
+      elsif File.exist?(File.join(Dir.home, '.wordnik.yml'))
+        YAML.load_file(File.join(Dir.home, '.wordnik.yml'))
+      else
+        {}
+      end
+    end
+
+    def to_s
+      "<Configuration api_key: *****, api_host: #{@api_host}:#{@api_port}, api_version: #{@api_version}>"
+    end
+
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/wordnik/utils.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Wordnik
+  module_function
+
+  def to_timestamp_or_string(thing)
+    if thing.is_a?(String)
+      if thing.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(:?\.\d{2,4})?Z$/)
+        return Time.parse(thing)
+      elsif thing.match(/^\d{4}-\d{2}-\d{2}$/)
+        return Date.parse(thing)
+      end
+
+      return thing
+    end
+    thing
+  end
+
+  def capitalize_simple(str)
+    return str if str.empty?
+
+    str[0].upcase + str[1..]
+  end
+
+  def lowercase_simple(str)
+    return str if str.empty?
+
+    str[0].downcase + str[1..]
+  end
+
+  def to_underscore(str)
+    str = str.to_s
+    str.gsub(/::/, '/')
+       .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+       .tr('-', '_')
+       .downcase
+  end
+
+  def to_camel(str)
+    str = str.to_s
+    return str if str.empty?
+
+    s = str.split('_').map { |part| capitalize_simple(part) }.join
+    lowercase_simple(s)
+  end
+
+  def to_snake_case(thing)
+    if thing.is_a?(Array)
+      return thing.map { |v| to_snake_case(v) }
+    elsif thing.is_a?(String)
+      return to_timestamp_or_string(thing)
+    elsif !thing.is_a?(Hash)
+      return thing
+    end
+
+    # else it's a hash
+    result = {}
+    thing.each do |key, value|
+      if value.is_a?(Hash)
+        value = to_snake_case(value)
+      elsif value.is_a?(Array)
+        value = value.map { |v| to_snake_case(v) }
+      end
+      value = to_timestamp_or_string(value)
+      result[to_underscore(key).to_sym] = value
+    end
+    result
+  end
+
+  def to_camel_case(thing)
+    if thing.is_a?(Array)
+      return thing.map { |v| to_camel_case(v) }
+    elsif !thing.is_a?(Hash)
+      return thing
+    end
+
+    # else it's a hash
+    result = {}
+    thing.each do |key, value|
+      if value.is_a?(Hash)
+        value = to_camel_case(value)
+      elsif value.is_a?(Array)
+        value = value.map { |v| to_camel_case(v) }
+      end
+      result[to_camel(key).to_sym] = value
+    end
+    result
+  end
+end

data/lib/wordnik/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wordnik
+  VERSION = '0.0.3'
+end

data/lib/wordnik.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'wordnik/utils'
+require_relative 'wordnik/configuration'
+require_relative 'wordnik/client'