scorpio 0.1.0 → 0.2.0

data/lib/scorpio.rb

@@ -8,7 +8,11 @@ module Scorpio
   def self.root
     @root ||= Pathname.new(__FILE__).dirname.parent.expand_path
   end
+end
+
+require "scorpio/util"
 
+module Scorpio
   # generally put in code paths that are not expected to be valid control flow paths.
   # rather a NotImplementedCorrectlyError. but that's too long.
   class Bug < NotImplementedError
@@ -17,78 +21,74 @@ module Scorpio
   proc { |v| define_singleton_method(:error_classes_by_status) { v } }.call({})
   class Error < StandardError; end
   class HTTPError < Error
-    define_singleton_method(:status) { |status| Scorpio.error_classes_by_status[status] = self }
-    attr_accessor :response
-  end
-  class ClientError < HTTPError; end
-  class ServerError < HTTPError; end
-
-  class BadRequest400Error < ClientError;                    status(400); end
-  class Unauthorized401Error < ClientError;                  status(401); end
-  class PaymentRequired402Error < ClientError;               status(402); end
-  class Forbidden403Error < ClientError;                     status(403); end
-  class NotFound404Error < ClientError;                      status(404); end
-  class MethodNotAllowed405Error < ClientError;              status(405); end
-  class NotAcceptable406Error < ClientError;                 status(406); end
-  class ProxyAuthenticationRequired407Error < ClientError;   status(407); end
-  class RequestTimeout408Error < ClientError;                status(408); end
-  class Conflict409Error < ClientError;                      status(409); end
-  class Gone410Error < ClientError;                          status(410); end
-  class LengthRequired411Error < ClientError;                status(411); end
-  class PreconditionFailed412Error < ClientError;            status(412); end
-  class PayloadTooLarge413Error < ClientError;               status(413); end
-  class URITooLong414Error < ClientError;                    status(414); end
-  class UnsupportedMediaType415Error < ClientError;          status(415); end
-  class RangeNotSatisfiable416Error < ClientError;           status(416); end
-  class ExpectationFailed417Error < ClientError;             status(417); end
-  class ImaTeapot418Error < ClientError;                     status(418); end
-  class MisdirectedRequest421Error < ClientError;            status(421); end
-  class UnprocessableEntity422Error < ClientError;           status(422); end
-  class Locked423Error < ClientError;                        status(423); end
-  class FailedDependency424Error < ClientError;              status(424); end
-  class UpgradeRequired426Error < ClientError;               status(426); end
-  class PreconditionRequired428Error < ClientError;          status(428); end
-  class TooManyRequests429Error < ClientError;               status(429); end
-  class RequestHeaderFieldsTooLarge431Error < ClientError;   status(431); end
-  class UnavailableForLegalReasons451Error < ClientError;    status(451); end
-
-  class InternalServerError500Error < ServerError;           status(500); end
-  class NotImplemented501Error < ServerError;                status(501); end
-  class BadGateway502Error < ServerError;                    status(502); end
-  class ServiceUnavailable503Error < ServerError;            status(503); end
-  class GatewayTimeout504Error < ServerError;                status(504); end
-  class HTTPVersionNotSupported505Error < ServerError;       status(505); end
-  class VariantAlsoNegotiates506Error < ServerError;         status(506); end
-  class InsufficientStorage507Error < ServerError;           status(507); end
-  class LoopDetected508Error < ServerError;                  status(508); end
-  class NotExtended510Error < ServerError;                   status(510); end
-  class NetworkAuthenticationRequired511Error < ServerError; status(511); end
-  error_classes_by_status.freeze
-
-  autoload :Model, 'scorpio/model'
-  autoload :OpenAPI, 'scorpio/openapi'
-  autoload :Google, 'scorpio/google_api_document'
-  autoload :JSON, 'scorpio/json'
-  autoload :Schema, 'scorpio/schema'
-
-  class << self
-    def stringify_symbol_keys(hash)
-      unless hash.is_a?(Hash)
-        raise ArgumentError, "expected argument to be a Hash; got #{hash.class}: #{hash.pretty_inspect}"
+    define_singleton_method(:status) do |status = nil|
+      if status
+        @status = status
+        Scorpio.error_classes_by_status[status] = self
+      else
+        @status
       end
-      hash.map { |k,v| {k.is_a?(Symbol) ? k.to_s : k => v} }.inject({}, &:update)
     end
+    attr_accessor :faraday_response, :response_object
   end
+  # HTTP Error classes' canonical names are like Scorpio::HTTPErrors::BadRequest400Error, but can
+  # be referred to like Scorpio::BadRequest400Error. this is just to avoid clutter in the Scorpio
+  # namespace in yardoc.
+  module HTTPErrors
+    class ClientError < HTTPError; end
+    class ServerError < HTTPError; end
 
-  module FingerprintHash
-    def ==(other)
-      other.respond_to?(:fingerprint) && other.fingerprint == self.fingerprint
-    end
-
-    alias eql? ==
+    class BadRequest400Error < ClientError;                    status(400); end
+    class Unauthorized401Error < ClientError;                  status(401); end
+    class PaymentRequired402Error < ClientError;               status(402); end
+    class Forbidden403Error < ClientError;                     status(403); end
+    class NotFound404Error < ClientError;                      status(404); end
+    class MethodNotAllowed405Error < ClientError;              status(405); end
+    class NotAcceptable406Error < ClientError;                 status(406); end
+    class ProxyAuthenticationRequired407Error < ClientError;   status(407); end
+    class RequestTimeout408Error < ClientError;                status(408); end
+    class Conflict409Error < ClientError;                      status(409); end
+    class Gone410Error < ClientError;                          status(410); end
+    class LengthRequired411Error < ClientError;                status(411); end
+    class PreconditionFailed412Error < ClientError;            status(412); end
+    class PayloadTooLarge413Error < ClientError;               status(413); end
+    class URITooLong414Error < ClientError;                    status(414); end
+    class UnsupportedMediaType415Error < ClientError;          status(415); end
+    class RangeNotSatisfiable416Error < ClientError;           status(416); end
+    class ExpectationFailed417Error < ClientError;             status(417); end
+    class ImaTeapot418Error < ClientError;                     status(418); end
+    class MisdirectedRequest421Error < ClientError;            status(421); end
+    class UnprocessableEntity422Error < ClientError;           status(422); end
+    class Locked423Error < ClientError;                        status(423); end
+    class FailedDependency424Error < ClientError;              status(424); end
+    class UpgradeRequired426Error < ClientError;               status(426); end
+    class PreconditionRequired428Error < ClientError;          status(428); end
+    class TooManyRequests429Error < ClientError;               status(429); end
+    class RequestHeaderFieldsTooLarge431Error < ClientError;   status(431); end
+    class UnavailableForLegalReasons451Error < ClientError;    status(451); end
 
-    def hash
-      fingerprint.hash
-    end
+    class InternalServerError500Error < ServerError;           status(500); end
+    class NotImplemented501Error < ServerError;                status(501); end
+    class BadGateway502Error < ServerError;                    status(502); end
+    class ServiceUnavailable503Error < ServerError;            status(503); end
+    class GatewayTimeout504Error < ServerError;                status(504); end
+    class HTTPVersionNotSupported505Error < ServerError;       status(505); end
+    class VariantAlsoNegotiates506Error < ServerError;         status(506); end
+    class InsufficientStorage507Error < ServerError;           status(507); end
+    class LoopDetected508Error < ServerError;                  status(508); end
+    class NotExtended510Error < ServerError;                   status(510); end
+    class NetworkAuthenticationRequired511Error < ServerError; status(511); end
   end
+  include HTTPErrors
+  error_classes_by_status.freeze
+
+  autoload :JSON,       'scorpio/json'
+  autoload :Google,      'scorpio/google_api_document'
+  autoload :OpenAPI,      'scorpio/openapi'
+  autoload :Typelike,      'scorpio/typelike_modules'
+  autoload :Hashlike,       'scorpio/typelike_modules'
+  autoload :Arraylike,       'scorpio/typelike_modules'
+  autoload :ResourceBase,     'scorpio/resource_base'
+  autoload :Schema,            'scorpio/schema'
+  autoload :SchemaInstanceBase, 'scorpio/schema_instance_base'
 end

data/lib/scorpio/google_api_document.rb

@@ -1,29 +1,27 @@
 require 'api_hammer/ycomb'
-require 'scorpio/schema_object_base'
+require 'scorpio/schema_instance_base'
 
 module Scorpio
   module Google
-    apidoc_schema_doc = ::JSON.parse(Scorpio.root.join('documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest').read)
-    api_document_class = proc do |*key|
-      Scorpio.class_for_schema(Scorpio::JSON::Node.new_by_type(apidoc_schema_doc, ['schemas', *key]))
-    end
+    discovery_rest_description_doc = Scorpio::JSON::Node.new_by_type(::JSON.parse(Scorpio.root.join('documents/www.googleapis.com/discovery/v1/apis/discovery/v1/rest').read), [])
 
-    # naming these is not strictly necessary, but is nice to have.
-    # generated: puts Scorpio::Google::ApiDocument.document['schemas'].select { |k,v| v['type'] == 'object' }.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = api_document_class.call('#{k}')" }
-    DirectoryList   = api_document_class.call('DirectoryList')
-    JsonSchema      = api_document_class.call('JsonSchema')
-    RestDescription = api_document_class.call('RestDescription')
-    RestMethod      = api_document_class.call('RestMethod')
-    RestResource    = api_document_class.call('RestResource')
+    discovery_metaschema = discovery_rest_description_doc['schemas']['JsonSchema']
+    rest_description_schema = Scorpio.class_for_schema(discovery_metaschema).new(discovery_rest_description_doc['schemas']['RestDescription'])
+    discovery_rest_description = Scorpio.class_for_schema(rest_description_schema).new(discovery_rest_description_doc)
 
-    # not generated
-    RestMethodRequest = api_document_class.call('RestMethod', 'properties', 'request')
-    RestMethodResponse = api_document_class.call('RestMethod', 'properties', 'response')
+    # naming these is not strictly necessary, but is nice to have.
+    DirectoryList      = Scorpio.class_for_schema(discovery_rest_description['schemas']['DirectoryList'])
+    JsonSchema         = Scorpio.class_for_schema(discovery_rest_description['schemas']['JsonSchema'])
+    RestDescription    = Scorpio.class_for_schema(discovery_rest_description['schemas']['RestDescription'])
+    RestMethod         = Scorpio.class_for_schema(discovery_rest_description['schemas']['RestMethod'])
+    RestResource       = Scorpio.class_for_schema(discovery_rest_description['schemas']['RestResource'])
+    RestMethodRequest  = Scorpio.class_for_schema(discovery_rest_description['schemas']['RestMethod']['properties']['request'])
+    RestMethodResponse = Scorpio.class_for_schema(discovery_rest_description['schemas']['RestMethod']['properties']['response'])
 
     # google does a weird thing where it defines a schema with a $ref property where a json-schema is to be used in the document (method request and response fields), instead of just setting the schema to be the json-schema schema. we'll share a module across those schema classes that really represent schemas. is this confusingly meta enough?
     module SchemaLike
       def to_openapi
-        dup_doc = ::JSON.parse(::JSON.generate(object.content))
+        dup_doc = ::JSON.parse(::JSON.generate(instance.content))
         # openapi does not want an id field on schemas
         dup_doc.delete('id')
         if dup_doc['properties'].is_a?(Hash)
@@ -45,12 +43,12 @@ module Scorpio
 
     class RestDescription
       def to_openapi_document(options = {})
-        Scorpio::OpenAPI::Document.new(to_openapi_hash(options))
+        Scorpio::OpenAPI::V2::Document.new(to_openapi_hash(options))
       end
 
       def to_openapi_hash(options = {})
         # we will be modifying the api document (RestDescription). clone self and modify that one.
-        ad = self.class.new(::JSON.parse(::JSON.generate(object.document)))
+        ad = self.class.new(::JSON.parse(::JSON.generate(instance.document)))
         ad_methods = []
         if ad['methods']
           ad_methods += ad['methods'].map do |mn, m|
@@ -80,13 +78,9 @@ module Scorpio
             method = http_method_methods.first
             unused_path_params = Addressable::Template.new(path).variables
             {http_method.downcase => {}.tap do |operation|
-              #operation['tags'] = []
+              operation['tags'] = method.resource_name ? [method.resource_name] : []
               #operation['summary'] = 
               operation['description'] = method['description'] if method['description']
-              if method.resource_name && options[:x]
-                operation['x-resource'] = method.resource_name
-                operation['x-resource-method'] = method.method_name
-              end
               #operation['externalDocs'] = 
               operation['operationId'] = method['id'] || (method.resource_name ? "#{method.resource_name}.#{method.method_name}" : method.method_name)
               #operation['produces'] = 
@@ -186,7 +180,7 @@ module Scorpio
                         proc do |toopenapiobject|
                           toopenapiobject = toopenapiobject.to_openapi if toopenapiobject.respond_to?(:to_openapi)
                           if toopenapiobject.respond_to?(:to_hash)
-                            toopenapiobject.map { |k, v| {toopenapirec.call(k) => toopenapirec.call(v)} }.inject({}, &:update)
+                            toopenapiobject.map { |k2, v2| {toopenapirec.call(k2) => toopenapirec.call(v2)} }.inject({}, &:update)
                           elsif toopenapiobject.respond_to?(:to_ary)
                             toopenapiobject.map(&toopenapirec)
                           elsif toopenapiobject.is_a?(Symbol)

data/lib/scorpio/json-schema-fragments.rb

@@ -116,7 +116,7 @@ module JSON
       end
 
       def to_s
-        "#<#{self.class.name} #{@type} = #{representation_s}>"
+        "#<#{self.class.inspect} #{@type} = #{representation_s}>"
       end
 
       private

data/lib/scorpio/json/node.rb

@@ -1,8 +1,20 @@
-require 'scorpio/typelike_modules'
-
 module Scorpio
   module JSON
+    # Scorpio::JSON::Node is an abstraction of a node within a JSON document.
+    # it aims to act like the underlying data type of the node's content
+    # (Hash or Array, generally) in most cases, defining methods of Hash
+    # and Array which delegate to the content. However, destructive methods
+    # are not defined, as modifying the content of a node would change it
+    # for any other nodes in the document that contain or refer to it.
+    #
+    # methods that return a modified copy such as #merge are defined, and
+    # return a copy of the document with the content of the node modified.
+    # the original node's document and content are untouched.
     class Node
+      # if the content of the document at the given path is a Hash, returns
+      # a HashNode; if an Array, returns ArrayNode. otherwise returns a
+      # regular Node, though, for the most part this will be called with Hash
+      # or Array content.
       def self.new_by_type(document, path)
         node = Node.new(document, path)
         content = node.content
@@ -15,17 +27,22 @@ module Scorpio
         end
       end
 
+      # a Node represents the content of a document at a given path.
       def initialize(document, path)
-        raise(ArgumentError, "path must be an array. got: #{path.pretty_inspect} (#{path.class})") unless path.is_a?(Array)
-        define_singleton_method(:document) { document }
+        raise(ArgumentError, "path must be an array. got: #{path.pretty_inspect.chomp} (#{path.class})") unless path.is_a?(Array)
+        @document = document
         @path = path.dup.freeze
         @pointer = ::JSON::Schema::Pointer.new(:reference_tokens, path)
       end
 
+      # the path of this Node within its document
       attr_reader :path
+      # the document containing this Node at is path
       attr_reader :document
+      # ::JSON::Schema::Pointer representing the path to this node within its document
       attr_reader :pointer
 
+      # the raw content of this Node from the underlying document at this Node's path.
       def content
         pointer.evaluate(document)
       end
@@ -40,7 +57,7 @@ module Scorpio
         begin
           el = content[k]
         rescue TypeError => e
-          raise(e.class, e.message + "\nsubscripting from #{content.pretty_inspect} (#{content.class}): #{k.pretty_inspect} (#{k.class})", e.backtrace)
+          raise(e.class, e.message + "\nsubscripting with #{k.pretty_inspect.chomp} (#{k.class}) from #{content.class.inspect}. self is: #{pretty_inspect.chomp}", e.backtrace)
         end
         if el.is_a?(Hash) || el.is_a?(Array)
           self.class.new_by_type(node.document, node.path + [k])
@@ -73,26 +90,91 @@ module Scorpio
         return self
       end
 
+      # a Node at the root of the document
       def document_node
         Node.new_by_type(document, [])
       end
 
+      # the parent of this node. if this node is the document root (its path is empty), raises
+      # ::JSON::Schema::Pointer::ReferenceError.
+      def parent_node
+        if path.empty?
+          raise(::JSON::Schema::Pointer::ReferenceError, "cannot access parent of root node: #{pretty_inspect.chomp}")
+        else
+          Node.new_by_type(document, path[0...-1])
+        end
+      end
+
+      # the pointer path to this node within the document, per RFC 6901 https://tools.ietf.org/html/rfc6901
       def pointer_path
         pointer.pointer
       end
+      # the pointer fragment to this node within the document, per RFC 6901 https://tools.ietf.org/html/rfc6901
       def fragment
         pointer.fragment
       end
 
+      def as_json
+        Typelike.as_json(content)
+      end
+
+      # takes a block. the block is yielded the content of this node. the block MUST return a modified
+      # copy of that content (and NOT modify the object it is given).
+      def modified_copy
+        # we need to preserve the rest of the document, but modify the content at our path.
+        #
+        # this is actually a bit tricky. we can't modify the original document, obviously.
+        # we could do a deep copy, but that's expensive. instead, we make a copy of each array
+        # or hash in the path above this node. this node's content is modified by the caller, and
+        # that is recursively merged up to the document root. the recursion is done with a
+        # y combinator, for no other reason than that was a fun way to implement it.
+        modified_document = ycomb do |rec|
+          proc do |subdocument, subpath|
+            if subpath == []
+              yield(subdocument)
+            else
+              car = subpath[0]
+              cdr = subpath[1..-1]
+              if subdocument.respond_to?(:to_hash)
+                car_object = rec.call(subdocument[car], cdr)
+                if car_object.object_id == subdocument[car].object_id
+                  subdocument
+                else
+                  subdocument.merge({car => car_object})
+                end
+              elsif subdocument.respond_to?(:to_ary)
+                if car.is_a?(String) && car =~ /\A\d+\z/
+                  car = car.to_i
+                end
+                unless car.is_a?(Integer)
+                  raise(TypeError, "bad subscript #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for array: #{subdocument.pretty_inspect.chomp}")
+                end
+                car_object = rec.call(subdocument[car], cdr)
+                if car_object.object_id == subdocument[car].object_id
+                  subdocument
+                else
+                  subdocument.dup.tap do |arr|
+                    arr[car] = car_object
+                  end
+                end
+              else
+                raise(TypeError, "bad subscript: #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for content: #{subdocument.pretty_inspect.chomp}")
+              end
+            end
+          end
+        end.call(document, path)
+        Node.new_by_type(modified_document, path)
+      end
+
       def object_group_text
         "fragment=#{fragment.inspect}"
       end
       def inspect
-        "\#<#{self.class.name} #{object_group_text} #{content.inspect}>"
+        "\#<#{self.class.inspect} #{object_group_text} #{content.inspect}>"
       end
       def pretty_print(q)
         q.instance_exec(self) do |obj|
-          text "\#<#{obj.class.name} #{object_group_text}"
+          text "\#<#{obj.class.inspect} #{obj.object_group_text}"
           group_sub {
             nest(2) {
               breakable ' '
@@ -105,7 +187,7 @@ module Scorpio
       end
 
       def fingerprint
-        {class: self.class, document: document, path: path}
+        {is_node: self.is_a?(Scorpio::JSON::Node), document: document, path: path}
       end
       include FingerprintHash
     end
@@ -116,7 +198,6 @@ module Scorpio
         content.each_index { |i| yield self[i] }
         self
       end
-      include Enumerable
 
       def to_ary
         to_a
@@ -124,29 +205,27 @@ module Scorpio
 
       include Arraylike
 
-      # array methods - define only those which do not modify the array.
-
-      # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_a)
-      index_methods = %w(each_index empty? length size)
-      index_methods.each do |method_name|
-        define_method(method_name) { |*a, &b| content.public_send(method_name, *a, &b) }
+      def as_json # needs redefined after including Enumerable
+        Typelike.as_json(content)
       end
 
-      # methods which use index and value.
-      # flatten is omitted. flatten should not exist.
-      array_methods = %w(& | * + - <=> abbrev assoc at bsearch bsearch_index combination compact count cycle dig fetch index first include? join last pack permutation rassoc repeated_combination reject reverse reverse_each rindex rotate sample select shelljoin shuffle slice sort take take_while transpose uniq values_at zip)
-      array_methods.each do |method_name|
-        define_method(method_name) { |*a, &b| to_a.public_send(method_name, *a, &b) }
+      # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_a).
+      # we override these methods from Arraylike
+      SAFE_INDEX_ONLY_METHODS.each do |method_name|
+        define_method(method_name) { |*a, &b| content.public_send(method_name, *a, &b) }
       end
     end
 
     class HashNode < Node
-      def each
+      def each(&block)
         return to_enum(__method__) { content.size } unless block_given?
-        content.each_key { |k| yield k, self[k] }
+        if block.arity > 1
+          content.each_key { |k| yield k, self[k] }
+        else
+          content.each_key { |k| yield [k, self[k]] }
+        end
         self
       end
-      include Enumerable
 
       def to_hash
         inject({}) { |h, (k, v)| h[k] = v; h }
@@ -154,61 +233,14 @@ module Scorpio
 
       include Hashlike
 
-      # hash methods - define only those which do not modify the hash.
+      def as_json # needs redefined after including Enumerable
+        Typelike.as_json(content)
+      end
 
       # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_hash)
-      key_methods = %w(each_key empty? include? has_key? key key? keys length member? size)
-      key_methods.each do |method_name|
+      SAFE_KEY_ONLY_METHODS.each do |method_name|
         define_method(method_name) { |*a, &b| content.public_send(method_name, *a, &b) }
       end
-
-      # methods which use key and value
-      hash_methods = %w(any? compact dig each_pair each_value fetch fetch_values has_value? invert rassoc reject select to_h transform_values value? values values_at)
-      hash_methods.each do |method_name|
-        define_method(method_name) { |*a, &b| to_hash.public_send(method_name, *a, &b) }
-      end
-
-      # methods that return a modified copy
-      def merge(other)
-        # we need to preserve the rest of the document, but modify the content at our path.
-        #
-        # this is actually a bit tricky. we can't modify the original document, obviously.
-        # we could do a deep copy, but that's expensive. instead, we make a copy of each array
-        # or hash in the path above this node. this node's content is merged with `other`, and
-        # that is recursively merged up to the document root. the recursion is done with a
-        # y combinator, for no other reason than that was a fun way to implement it.
-        merged_document = ycomb do |rec|
-          proc do |subdocument, subpath|
-            if subpath == []
-              subdocument.merge(other.is_a?(JSON::Node) ? other.content : other)
-            else
-              car = subpath[0]
-              cdr = subpath[1..-1]
-              if subdocument.is_a?(Array)
-                if car.is_a?(String) && car =~ /\A\d+\z/
-                  car = car.to_i
-                end
-                unless car.is_a?(Integer)
-                  raise(TypeError, "bad subscript #{car.pretty_inspect} with remaining subpath: #{cdr.inspect} for array: #{subdocument.pretty_inspect}")
-                end
-              end
-              car_object = rec.call(subdocument[car], cdr)
-              if car_object == subdocument[car]
-                subdocument
-              elsif subdocument.is_a?(Hash)
-                subdocument.merge({car => car_object})
-              elsif subdocument.is_a?(Array)
-                subdocument.dup.tap do |arr|
-                  arr[car] = car_object
-                end
-              else
-                raise(TypeError, "bad subscript: #{car.pretty_inspect} with remaining subpath: #{cdr.inspect} for content: #{subdocument.pretty_inspect}")
-              end
-            end
-          end
-        end.call(document, path)
-        self.class.new(merged_document, path)
-      end
     end
   end
 end