trav3 0.4.1 → 0.5.0

data/lib/trav3/error/invalid_repository.rb

@@ -3,7 +3,7 @@
 module Trav3
   class InvalidRepository < StandardError
     def message
-      "The repository format was invlaid.
+      "The repository format was invalid.
   You must either provide the digit name for the repository,
   or `user/repo` or `user%2Frepo` as the name."
     end

data/lib/trav3/headers.rb

@@ -3,8 +3,16 @@
 require 'forwardable'
 
 module Trav3
+  # A header builder class for outgoing requests
   class Headers
     extend Forwardable
+    # @!macro [attach] def_delegators
+    #   @!method each_pair
+    #     Forwards to $1.
+    #     @see Hash#each_pair
+    #   @!method fetch
+    #     Forwards to $1.
+    #     @see Hash#fetch
     def_delegators :@heads, :each_pair, :fetch
 
     def initialize(args = {})

data/lib/trav3/options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Trav3
+  # A url options builder class for outgoing requests.
   class Options
     def initialize(args = {})
       build(args)
@@ -111,7 +112,7 @@ module Trav3
       @opts.map(&split).to_h
     end
 
-    private
+    private # @private
 
     def split
       ->(entry) { entry.split('=') }

data/lib/trav3/pagination.rb

@@ -8,19 +8,25 @@ module Trav3
       @result = result
     end
 
+    # Next page of results
+    # @return [Success, RequestError]
     def next
       get(action(:next))
     end
 
+    # First page of results
+    # @return [Success, RequestError]
     def first
       get(action(:first))
     end
 
+    # Last page of results
+    # @return [Success, RequestError]
     def last
       get(action(:last))
     end
 
-    private
+    private # @private
 
     def action(action)
       dig('@pagination').dig(action.to_s).dig('@href')

data/lib/trav3/response/request_error.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 module Trav3
+  # (see Response)
   class RequestError < Response
+    # @return [Boolean]
     def success?
       false
     end
 
+    # @return [Boolean]
     def failure?
       true
     end

data/lib/trav3/response/response.rb

@@ -3,15 +3,115 @@
 require 'forwardable'
 
 module Trav3
+  # The results from queries return either `Success` or `RequestError` which both
+  # repsond with Hash like query methods for the JSON data or the Net::HTTP resonse object methods.
+  #
+  # The `Response` classes `Success` and `RequestError` forward method calls for all of the instance
+  # methods of a `ResponseCollection` to the collection.  And many of the methods calls for the Net::HTTP
+  # response are also available on this class and those method calls are forwarded to the response.
   class Response
     extend Forwardable
     attr_reader :travis
-    def_delegators :@collection, *ResponseCollection.instance_methods.-(Object.methods)
-    def_delegators :@response, :code, :code_type, :uri, :message, :read_header,
-                   :header, :value, :entity, :response, :body, :decode_content,
-                   :msg, :reading_body, :read_body, :http_version,
-                   :connection_close?, :connection_keep_alive?,
-                   :initialize_http_header, :get_fields, :each_header
+    # @!macro [attach] def_delegators
+    #   @!method []
+    #     Forwards to $1
+    #     @see ResponseCollection#[]
+    #   @!method count
+    #     Forwards to $1.
+    #     @see ResponseCollection#count
+    #   @!method dig
+    #     Forwards to $1
+    #     @see ResponseCollection#dig
+    #   @!method each
+    #     Forwards to $1
+    #     @see ResponseCollection#each
+    #   @!method empty?
+    #     Forwards to $1.
+    #     @see ResponseCollection#empty?
+    #   @!method fetch
+    #     Forwards to $1
+    #     @see ResponseCollection#fetch
+    #   @!method first
+    #     Forwards to $1
+    #     @see ResponseCollection#first
+    #   @!method follow
+    #     Forwards to $1
+    #     @see ResponseCollection#follow
+    #   @!method has_key?
+    #     Forwards to $1.
+    #     @see ResponseCollection#has_key?
+    #   @!method hash?
+    #     Forwards to $1
+    #     @see ResponseCollection#hash?
+    #   @!method key?
+    #     Forwards to $1.
+    #     @see ResponseCollection#key?
+    #   @!method last
+    #     Forwards to $1
+    #     @see ResponseCollection#last
+    #   @!method keys
+    #     Forwards to $1.
+    #     @see ResponseCollection#keys
+    #   @!method values
+    #     Forwards to $1.
+    #     @see ResponseCollection#values
+    def_delegators :@collection, *ResponseCollection.instance_methods(false)
+    # @!macro [attach] def_delegators
+    #   @!method body
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#body
+    #   @!method code
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#code
+    #   @!method code_type
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#code_type
+    #   @!method decode_content
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#decode_content
+    #   @!method each_header
+    #     Forwards to $1
+    #     @see Net::HTTPHeader#each_header
+    #   @!method entity
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#entity
+    #   @!method get_fields
+    #     Forwards to $1
+    #     @see Net::HTTPHeader#get_fields
+    #   @!method header
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#header
+    #   @!method http_version
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#http_version
+    #   @!method message
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#message
+    #   @!method msg
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#msg
+    #   @!method read_body
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#read_body
+    #   @!method read_header
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#read_header
+    #   @!method reading_body
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#reading_body
+    #   @!method response
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#response
+    #   @!method uri
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#uri
+    #   @!method value
+    #     Forwards to $1
+    #     @see Net::HTTPResponse#value
+    def_delegators :@response, :body, :code, :code_type, :decode_content,
+                   :each_header, :entity, :get_fields, :header, :http_version,
+                   :message, :msg, :read_body, :read_header, :reading_body, :response,
+                   :uri, :value
     def initialize(travis, response)
       @travis = travis
       @response = response
@@ -23,14 +123,17 @@ module Trav3
                     end
     end
 
+    # Class name and keys of response
     def inspect
       "<#{self.class} Response: keys = #{keys}>"
     end
 
+    # @abstract
     def success?
       raise Unimplemented
     end
 
+    # @abstract
     def failure?
       raise Unimplemented
     end

data/lib/trav3/response/response_collection.rb

@@ -3,12 +3,40 @@
 module Trav3
   class ResponseCollection
     extend Forwardable
+    # @!macro [attach] def_delegators
+    #   @!method count
+    #     Forwards to $1.
+    #     @see both Hash#count or Array#count
+    #   @!method keys
+    #     Forwards to $1.
+    #     @see Hash#keys
+    #   @!method values
+    #     Forwards to $1.
+    #     @see Hash#values
+    #   @!method has_key?
+    #     Forwards to $1.
+    #     @see Hash#has_key?
+    #   @!method key?
+    #     Forwards to $1.
+    #     @see Hash#key?
+    #   @!method empty?
+    #     Forwards to $1.
+    #     @see both Hash#empty? or Array#empty?
     def_delegators :@collection, :count, :keys, :values, :has_key?, :key?, :empty?
     def initialize(travis, collection)
       @travis = travis
       @collection = collection
     end
 
+    # Either the key or index of the item you wish to get depending on
+    # if this collection is a {#hash?} or an array.
+    #
+    # If the item retrieved is a Hash or Array then the returned item
+    # will be another instance of `ResponseCollection`.  Otherwise it will
+    # be a `String` unless the target does not exist and then it will be `nil`.
+    #
+    # @param target [String, Integer]
+    # @return [ResponseCollection, String, nil]
     def [](target)
       result = collection[target]
       return ResponseCollection.new(travis, result) if collection?(result)
@@ -16,15 +44,26 @@ module Trav3
       result
     end
 
+    # (see #[])
     def dig(*target)
-      return collection.dig(*target) if target.length != 1
+      dug, *rest = target
 
-      result = collection.dig(*target)
-      return ResponseCollection.new(travis, result) if collection?(result)
+      result = collection.dig(dug)
+      if collection?(result)
+        rc = ResponseCollection.new(travis, result)
+        return rest.empty? ? rc : rc.dig(*rest)
+      end
 
       result
     end
 
+    # When the inner collection is an Array every item iterated
+    # over is yielded to you as a `ResponseCollection`.
+    #
+    # If the inner collection is a {#hash?} then this method acts
+    # as though you've called `each` directly on that `Hash`.
+    #
+    # @yieldparam [Array, ResponseCollection]
     def each(&block)
       return collection.each(&block) if hash?
 
@@ -33,17 +72,37 @@ module Trav3
       end
     end
 
-    def fetch(idx)
-      result = collection.fetch(idx) { nil }
+    # Either the key or index of the item you wish to get depending on
+    # if this collection is a {#hash?} or an array.
+    #
+    # If the item retrieved is a Hash or Array then the returned item
+    # will be another instance of `ResponseCollection`.  Otherwise it will
+    # be a `String`.
+    #
+    # If the target does not exist and no block was given this will raise
+    # an exception.  If a block was given, then that block will be evaluated
+    # and that return value returned.
+    #
+    # @param target [String, Integer]
+    # @return [ResponseCollection, String, nil]
+    def fetch(target)
+      result = collection.fetch(target) { nil }
       return ResponseCollection.new(travis, result) if collection?(result)
       return result if result
 
       # For error raising behavior
-      collection.fetch(idx) unless block_given?
+      collection.fetch(target) unless block_given?
 
       yield
     end
 
+    # When the inner collection is an Array it returns the first
+    # item as either a `ResponseCollection` or a `String`.  If the
+    # Array is empty it returns `nil`.
+    #
+    # If the inner collection is a {#hash?} then this simply returns `nil`.
+    #
+    # @return [ResponseCollection, String, nil]
     def first
       self[0]
     end
@@ -65,10 +124,20 @@ module Trav3
       result.follow
     end
 
+    # Reveals if the inner collection is a Hash or not.
+    #
+    # @return [Boolean]
     def hash?
       collection.is_a? Hash
     end
 
+    # When the inner collection is an Array it returns the last
+    # item as either a `ResponseCollection` or a `String`.  If the
+    # Array is empty it returns `nil`.
+    #
+    # If the inner collection is a {#hash?} then this simply returns `nil`.
+    #
+    # @return [ResponseCollection, String, nil]
     def last
       self[-1]
     end

data/lib/trav3/response/success.rb

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
 
 module Trav3
+  # (see Response)
   class Success < Response
+    # @return [Pagination]
     def page
       Trav3::Pagination.new(travis, self)
     end
 
+    # @return [Boolean]
     def success?
       true
     end
 
+    # @return [Boolean]
     def failure?
       false
     end

data/lib/trav3/rest.rb

@@ -5,6 +5,7 @@ require 'uri'
 require 'json'
 
 module Trav3
+  # @private
   module REST
     extend Net
     class << self

data/lib/trav3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trav3
-  VERSION = '0.4.1'
+  VERSION = '0.5.0'
 end

data/trav3.gemspec

@@ -22,6 +22,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(/^exe\//) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.required_ruby_version = '>= 2.3.0'
+
   # Generate YARD DOC on install
   spec.metadata['yard.run'] = 'yri'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trav3
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Daniel P. Clark
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-29 00:00:00.000000000 Z
+date: 2019-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,7 +114,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="