Hyrule-Compendium 1.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c9bdd0411c8aa33e9cc7b3c233a3cfcc2b967b46
-  data.tar.gz: 45012d54951d67b33e285a39d95e7503efbd3897
+SHA256:
+  metadata.gz: 5b2d9bbbe32c561ccf1c94fd12ade17722d271a33099bddd1a12fa322a4cd571
+  data.tar.gz: 2e5cee56a637f9cd13683f71d2d879809d64b67c57f44a0e8670153c10c45b21
 SHA512:
-  metadata.gz: 668543423094d61e980e28f3cc3c7f435f2259cf421535db477b8418e484f6d937a8dfebc1ea801eb772d89adf46ef95901ab824ed6bd97ca19b3f5efacbfe0b
-  data.tar.gz: e4e4b0aad79927a573324eb36363821bf53111cddbbf3e00f2297ecdb4341f043b276efd3ae46a066238531f2d2e90f9124c9586264006055bd43226fd513f2f
+  metadata.gz: 06d95e42274481077bf1ca024d7b309b7a3a1898111fdf456504c3bf0673afc9169bde5fe8602d3208fde48d028772a8bb8bbe1320545c0c8a99456dd01425a0
+  data.tar.gz: e507fb881f8edda640373e5eaf41af0d0eaf926bb3c0d3e33d1450e02e5f90417c10f26ba66b29abfeb53edacdd82d1154eea71e6831d93d8c896788f9d1913f

data/lib/hyrule_compendium.rb

@@ -1,29 +1,142 @@
 require "json"
 require "uri"
 require "net/http"
+require "open-uri"
 
-def make_req url
+class NoEntryError < StandardError
+    # Raised when a given entry does not exist in the compendium
+    # 
+    # Parameters:
+    #   * `target_entry`: Non-existant input entry that causes error.
+    #       - type: str, int
+
+    def initialize(target_entry)
+        if target_entry.is_a? String
+            super "Entry with name '#{target_entry}' not in compendium."
+        elsif target_entry.is_a? Integer
+            super "Entry with ID '#{target_entry}' not in compendium."
+        end
+    end
+end
+
+class NoCategoryError < StandardError
+    # Raised when a given category does not exist in the compendium
+    # 
+    # Parameters:
+    #   * `target_category`: Non-existant input category that causes error.
+    #       - type: str
+
+    def initialize(target_category)
+        super "Category '#{target_category}' not in compendium. Categories are 'creatures', 'equipment', 'materials', 'monsters', and 'treaure'."
+    end
+end
+
+def make_req url, timeout
     uri = URI url
-    res = Net::HTTP.start uri.host, uri.port do |http|
+    res = Net::HTTP.start uri.host, uri.port, read_timeout: timeout do |http|
         req = Net::HTTP::Get.new uri
         http.request req
     end
-    return JSON.parse res.body
+    return (JSON.parse res.body)["data"]
 end
 
-module Hyrule_Compendium
+class Hyrule_Compendium
+    # Base class for the Hyrule-Compendium
+    #
+    # Parameters:
+    #   * `url`: The base URL of the API server
+    #       - type: str
+    #       - default: "http://botw-compendium.herokuapp.com/api/v2"
+    #   * `default_timeout`: Default seconds to wait for response for all API calling functions until raising `Net::ReadTimeout`.
+    #       - type: float, int
+    #       - default: `nil` (no timeout)
+    #       - notes: If a API calling function has a parameter `timeout`, it will overide this.
 
-    $base = "http://botw-compendium.herokuapp.com/api/v1"
+    def initialize url: "http://botw-compendium.herokuapp.com/api/v2", default_timeout: nil
+        @base = url
+        @default_timeout = default_timeout
+    end
+
+    def get_entry entry, timeout=@default_timeout
+        # Gets an entry from the compendium.
+        #
+        # Parameters:
+        #   * `entry`: The ID or name of the entry to be retrieved.
+        #       - type: str, int
+        #   * `timeout`: Seconds to wait for response until raising `Net::ReadTimeout`.
+        #       - type: float, int
+        #       - default: `@default_timeout`
+        #
+        # Returns: The entry's metadata.
+        #   - type: hash
+        #
+        # Raises:
+        #   * `NoEntryError` when the entry is not found.
 
-    def Hyrule_Compendium.get_entry entry
-        return make_req("#{$base}/entry/#{entry.to_s.gsub " ", "%20"}")["data"]
+        res = make_req("#{@base}/entry/#{entry.to_s.gsub " ", "%20"}", timeout=timeout)
+        if res == {}
+            raise NoEntryError.new entry
+        end
+        return res
     end
 
-    def Hyrule_Compendium.get_category category
-        return make_req("#{$base}/category/#{category}")["data"]
+    def get_category category, timeout=@default_timeout
+        # Gets all entries from a category in the compendium.
+        # 
+        # Parameters:
+        #   * `category`: The name of the category to be retrieved. Must be one of the compendium categories.
+        #       - type: string
+        #       - notes: 
+        #           * must be "creatures", "equipment", "materials", "monsters", or "treasure"
+        #           * the category "creatures" has two sub-categories, as keys: "food" and "non_food"
+        #   * `timeout`: Seconds to wait for response until raising `Net::ReadTimeout`.
+        #       - type: float, int
+        #       - default: `@default_timeout`
+        #
+        # Returns: All entries in the category.
+        #   - type: array, hash (for creatures)
+        #
+        # Raises:
+        #   * `NoCategoryError` when the category is not found.
+
+        if !(["creatures", "equipment", "materials", "monsters", "treasure"].include? category)
+            raise NoCategoryError.new category
+        end
+        return make_req "#{@base}/category/#{category}", timeout=timeout
     end
 
-    def Hyrule_Compendium.get_all
-        return make_req $base
+    def get_all timeout=@default_timeout
+        # Gets all entries from the compendium.
+        #
+        # Parameters:
+        #   * `timeout`: Seconds to wait for response until raising `Net::ReadTimeout`.
+        #       - type: float, int
+        #       - default: `@default_timeout`
+        #
+        # Returns: all items in the compendium with their metadata, nested in categories.
+        #   - type: hash
+
+        return make_req @base, timeout
+    end
+
+    def download_entry_image entry, output_file=nil, timeout=@default_timeout
+        # Downloads the image of a compendium entry.
+        # 
+        # Parameters:
+        #   * `entry`: The ID or name of the entry of the image to be downloaded.
+        #       - type: str, int
+        #   * `output_file`: The output file's path.
+        #       - type: str
+        #       - default: entry's name with a ".png" extension with spaces replaced with underscores
+        #   * `timeout`: Seconds to wait for server response until raising `Net::ReadTimeout`.
+        #       - type: float, int
+        #       - default: `@default_timeout`
+
+        entry_data = get_entry entry, timeout
+        open entry_data["image"] do |image|
+            File.open output_file || (entry_data["name"] + ".png").gsub(" ", "_"), "wb" do |file|
+                file.write image.read
+            end
+        end
     end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: Hyrule-Compendium
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Aarav Borthakur
@@ -10,7 +10,7 @@ bindir: bin
 cert_chain: []
 date: 2021-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Ruby wrapper for the Hyrule Compendium API
+description: The official ruby wrapper for the Hyrule Compendium API
 email: gadhaguy13@gmail.com
 executables: []
 extensions: []
@@ -36,8 +36,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Hyrule Compendium API