reynard 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 149366d0bcc24959907a263c6223a2bb75cc7004a06cf153d1ef2dc35e26b91d
-  data.tar.gz: 8f698ffa4c958564a902d1039807324c9b1182e0a6638dedb16fc6eb3b6eb00f
+  metadata.gz: 96421332b89c0816b77704aba7b07f267424c0a238fd5b74c8b91aa9d3943c6d
+  data.tar.gz: a6a714f984bd420fe2254b747972ba804968cc4df6ca534b38c50c1cf2b2687b
 SHA512:
-  metadata.gz: 5de35106aeb06b3478d807d34f5da335684530f6f4f28c789fe52d8a0aafd7f13dab27154ac39cfdc354c4e65bd6da755ea16d669603eae280c027f12d54d152
-  data.tar.gz: ff64d0913efc4e8a2b7c5b8420f94cefcf13567633906d48459ce8a653f5a65f8bd9d8c24368c68a8445320012561a24ff42568065232703675af4944b59f301
+  metadata.gz: 7cbb02d762e3c38b05b59ec25f8320f3a5830b56aabe376249f2347a098b43cff31935829d9dd831edc383a62531a06b78e735d886bf4f2329475e8785820211
+  data.tar.gz: 767b9ba9f0f5eb3fae98d414f778e481fd6b3c0a928128cec29b3a409db44481057afc44c9ac029a98892b71c3d3e09fd80286e0b2e942e47aef97b2921fab22

data/README.md

@@ -152,6 +152,72 @@ For example, in case of an array item it would look at `books` and singularize i
 
 If you run into issues where Reynard doesn't properly build an object for a nested resource, it's probably because of a naming issue. It's advised to add a `title` property to the schema definition with a unique name in that case.
 
+### Properties and model attributes
+
+Reynard provides access to JSON properties on the model in a number of ways. There are some restrictions because of Ruby, so it's good to understand them.
+
+Let's assume there is a payload for an `Author` model that looks like this:
+
+```json
+{"first_name":"Marcél","lastName":"Marcellus","1st-class":false}
+```
+
+Reynard attemps to give access to these properties as much as possible by sanitizing and normalizing them, so you can do the following:
+
+```ruby
+response.object.first_name #=> "Marcél"
+response.object.last_name #=> "Marcellus"
+```
+
+But it's also possible to use the original casing for `lastName`.
+
+```ruby
+response.object.lastName #=> "Marcellus"
+```
+
+However, a method can't start with a number and can't contain dashes in Ruby so the following is not possible:
+
+```
+# Not valid Ruby syntax:
+response.object.1st-class
+```
+
+There are two alternatives for accessing this property:
+
+```ruby
+# The preferred solution for accessing raw property values is through the
+# parsed JSON on the response object.
+response.parsed_body["1st-class"]
+# When you are processing nested models and you don't have access to the
+# response object, you can chose to use the `[]` method.
+response.object["1st-class"]
+# Don't use `send` to access the property, this may not work in future
+# versions.
+response.object.send("1st-class")
+```
+
+#### Mapping properties
+
+In case you are forced to access a property through a method, you could chose to map irregular property names to method names globally for all models:
+
+```ruby
+reynard.snake_cases({ "1st-class" => "first_class" })
+```
+
+This will allow you to access the property through the `first_class` method without changing the behavior of the rest of the object.
+
+```ruby
+response.object.first_class #=> false
+response.object["1st-class"] #=> false
+```
+
+Don't use this to map common property names that would work fine otherwise, because you could make things really confusing.
+
+```ruby
+# Don't do this.
+reynard.snake_cases({ "name" => "naem" })
+```
+
 ## Logging
 
 When you want to know what the Reynard client is doing you can enable logging.

data/lib/reynard/context.rb

@@ -8,13 +8,14 @@ class Reynard
     extend Forwardable
     def_delegators :@request_context, :verb, :path, :full_path, :url
 
-    def initialize(specification:, request_context: nil)
+    def initialize(specification:, inflector:, request_context: nil)
       @specification = specification
+      @inflector = inflector
       @request_context = request_context || build_request_context
     end
 
     def base_url(base_url)
-      copy(base_url:)
+      copy(base_url: base_url)
     end
 
     def operation(operation_name)
@@ -43,7 +44,7 @@ class Reynard
     end
 
     def logger(logger)
-      copy(logger:)
+      copy(logger: logger)
     end
 
     def execute
@@ -59,6 +60,7 @@ class Reynard
     def copy(**properties)
       self.class.new(
         specification: @specification,
+        inflector: @inflector,
         request_context: @request_context.copy(**properties)
       )
     end
@@ -70,8 +72,9 @@ class Reynard
     def build_response(http_response)
       Reynard::Http::Response.new(
         specification: @specification,
+        inflector: @inflector,
         request_context: @request_context,
-        http_response:
+        http_response: http_response
       )
     end
   end

data/lib/reynard/external.rb

@@ -8,6 +8,7 @@ class Reynard
     def initialize(path:, ref:)
       @path = path
       @relative_path, @anchor = ref.split('#', 2)
+      @filename = File.expand_path(@relative_path, @path)
     end
 
     def path
@@ -22,11 +23,14 @@ class Reynard
       end
     end
 
+    def filesystem_path
+      File.dirname(@filename)
+    end
+
     private
 
     def filename
-      filename = File.expand_path(@relative_path, @path)
-      return filename if filename.start_with?(@path)
+      return @filename if @filename.start_with?(@path)
 
       raise 'You are only allowed to reference files relative to the specification file.'
     end

data/lib/reynard/http/request.rb

@@ -25,8 +25,12 @@ class Reynard
         Net::HTTP.const_get(@request_context.verb.capitalize)
       end
 
+      def request_headers
+        { 'User-Agent' => Reynard.user_agent }.merge(@request_context.headers || {})
+      end
+
       def build_request
-        request = request_class.new(uri, @request_context.headers)
+        request = request_class.new(uri, request_headers)
         if @request_context.body
           @request_context.logger&.debug { @request_context.body }
           request.body = @request_context.body

data/lib/reynard/http/response.rb

@@ -8,8 +8,9 @@ class Reynard
       extend Forwardable
       def_delegators :@http_response, :code, :content_type, :[], :body
 
-      def initialize(specification:, request_context:, http_response:)
+      def initialize(specification:, inflector:, request_context:, http_response:)
         @specification = specification
+        @inflector = inflector
         @request_context = request_context
         @http_response = http_response
       end
@@ -69,9 +70,10 @@ class Reynard
       end
 
       def build_object_with_media_type(media_type)
-        ::Reynard::ObjectBuilder.new(
+        ObjectBuilder.new(
           schema: @specification.schema(media_type.node),
-          parsed_body:
+          inflector: @inflector,
+          parsed_body: parsed_body
         ).call
       end
 

data/lib/reynard/http.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class Reynard
+  # Contains classes that wrap Net::HTTP to provide a slightly more convenient interface.
   class Http
     autoload :Request, 'reynard/http/request'
     autoload :Response, 'reynard/http/response'

data/lib/reynard/inflector.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class Reynard
+  # Transforms property names so they are value Ruby identifiers or more readable to users.
+  class Inflector
+    def initialize
+      @snake_case = {}
+    end
+
+    # Registers additional exceptions to the regular snake-case algorithm. Registering is additive
+    # so you can call this multiple times without losing previously registered exceptions.
+    def snake_cases(exceptions)
+      @snake_case.merge!(exceptions)
+    end
+
+    # Returns the string in snake-case, taking previously registered exceptions into account.
+    def snake_case(property)
+      @snake_case[property] || self.class.snake_case(property)
+    end
+
+    # Returns the string in snake-case.
+    def self.snake_case(property)
+      property
+        .to_s
+        .gsub(/([A-Z])(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { (Regexp.last_match(1) || Regexp.last_match(2)) << '_' }
+        .tr("'\"-", '___')
+        .downcase
+    end
+  end
+end

data/lib/reynard/model.rb

@@ -3,30 +3,41 @@
 class Reynard
   # Superclass for dynamic classes generated by the object builder.
   class Model
+    extend Forwardable
+    def_delegators :@attributes, :[]
+
     class << self
       # Holds references to the full schema for the model if available.
       attr_accessor :schema
+      # The inflector to use on properties.
+      attr_writer :inflector
     end
 
     def initialize(attributes)
+      @attributes = {}
+      @snake_cases = self.class.snake_cases(attributes.keys)
       self.attributes = attributes
     end
 
     def attributes=(attributes)
       attributes.each do |name, value|
-        instance_variable_set("@#{name}", self.class.cast(name, value))
+        @attributes[name.to_s] = self.class.cast(name, value)
       end
     end
 
     # Until we can set accessors based on the schema
     def method_missing(attribute_name, *)
-      instance_variable_get("@#{attribute_name}")
-    rescue NameError
+      attribute_name = attribute_name.to_s
+      @attributes[attribute_name] || @attributes.fetch(@snake_cases.fetch(attribute_name))
+    rescue KeyError
       raise NoMethodError, "undefined method `#{attribute_name}' for #{inspect}"
     end
 
     def respond_to_missing?(attribute_name, *)
-      instance_variable_defined?("@#{attribute_name}")
+      attribute_name = attribute_name.to_s
+      return true if @attributes.key?(attribute_name)
+
+      @snake_cases.key?(attribute_name) && @attributes.key?(@snake_cases[attribute_name])
     rescue NameError
       false
     end
@@ -37,7 +48,20 @@ class Reynard
       property = schema.property_schema(name)
       return value unless property
 
-      Reynard::ObjectBuilder.new(schema: property, parsed_body: value).call
+      Reynard::ObjectBuilder.new(schema: property, inflector: inflector, parsed_body: value).call
+    end
+
+    def self.inflector
+      @inflector ||= Inflector.new
+    end
+
+    def self.snake_cases(property_names)
+      property_names.each_with_object({}) do |property_name, snake_cases|
+        snake_case = inflector.snake_case(property_name)
+        next if snake_case == property_name
+
+        snake_cases[snake_case] = property_name
+      end
     end
   end
 end

data/lib/reynard/object_builder.rb

@@ -7,8 +7,9 @@ class Reynard
   class ObjectBuilder
     attr_reader :schema, :parsed_body
 
-    def initialize(schema:, parsed_body:, model_name: nil)
+    def initialize(schema:, inflector:, parsed_body:, model_name: nil)
       @schema = schema
+      @inflector = inflector
       @parsed_body = parsed_body
       @model_name = model_name
     end
@@ -21,7 +22,8 @@ class Reynard
       return @model_class if defined?(@model_class)
 
       @model_class =
-        self.class.model_class_get(model_name) || self.class.model_class_set(model_name, schema)
+        self.class.model_class_get(model_name) ||
+        self.class.model_class_set(model_name, schema, @inflector)
     end
 
     def call
@@ -41,11 +43,11 @@ class Reynard
       nil
     end
 
-    def self.model_class_set(model_name, schema)
+    def self.model_class_set(model_name, schema, inflector)
       if schema.type == 'array'
         array_model_class_set(model_name)
       else
-        object_model_class_set(model_name, schema)
+        object_model_class_set(model_name, schema, inflector)
       end
     end
 
@@ -55,11 +57,12 @@ class Reynard
       ::Reynard::Models.const_set(model_name, Class.new(Array))
     end
 
-    def self.object_model_class_set(model_name, schema)
+    def self.object_model_class_set(model_name, schema, inflector)
       return Reynard::Model unless model_name
 
       model_class = Class.new(Reynard::Model)
       model_class.schema = schema
+      model_class.inflector = inflector
       ::Reynard::Models.const_set(model_name, model_class)
     end
 
@@ -73,6 +76,7 @@ class Reynard
       parsed_body.each do |item|
         array << self.class.new(
           schema: item_schema,
+          inflector: @inflector,
           parsed_body: item
         ).call
       end

data/lib/reynard/specification.rb

@@ -14,7 +14,7 @@ class Reynard
 
     # Digs a value out of the specification, taking $ref into account.
     def dig(*path)
-      dig_into(@data, @data, path.dup)
+      dig_into(@data, @data, path.dup, File.dirname(@filename))
     end
 
     def servers
@@ -103,7 +103,7 @@ class Reynard
     # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/CyclomaticComplexity
     # rubocop:disable Metrics/MethodLength
-    def dig_into(data, cursor, path)
+    def dig_into(data, cursor, path, filesystem_path)
       while path.length.positive?
         cursor = cursor[path.first]
         return unless cursor
@@ -118,7 +118,8 @@ class Reynard
           cursor = data
         # References another file, with an optional anchor to an element in the data.
         when %r{\A\./}
-          external = External.new(path: File.dirname(@filename), ref: cursor['$ref'])
+          external = External.new(path: filesystem_path, ref: cursor['$ref'])
+          filesystem_path = external.filesystem_path
           path = external.path + path
           cursor = external.data
         end

data/lib/reynard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Reynard
-  VERSION = '0.6.0'
+  VERSION = '0.8.0'
 end

data/lib/reynard.rb

@@ -13,11 +13,13 @@ class Reynard
   extend Forwardable
   def_delegators :build_context, :logger, :base_url, :operation, :headers, :params
   def_delegators :@specification, :servers
+  def_delegators :@inflector, :snake_cases
 
   autoload :Context, 'reynard/context'
   autoload :External, 'reynard/external'
   autoload :GroupedParameters, 'reynard/grouped_parameters'
   autoload :Http, 'reynard/http'
+  autoload :Inflector, 'reynard/inflector'
   autoload :Logger, 'reynard/logger'
   autoload :MediaType, 'reynard/media_type'
   autoload :Model, 'reynard/model'
@@ -33,7 +35,8 @@ class Reynard
   autoload :VERSION, 'reynard/version'
 
   def initialize(filename:)
-    @specification = Specification.new(filename:)
+    @specification = Specification.new(filename: filename)
+    @inflector = Inflector.new
   end
 
   class << self
@@ -42,6 +45,12 @@ class Reynard
     attr_writer :http
   end
 
+  # Returns a value that will be used by default for Reynard's User-Agent headers. Please use
+  # the +headers+ setter on the context if you want to change this.
+  def self.user_agent
+    "Reynard/#{Reynard::VERSION}"
+  end
+
   # Returns Reynard's global request interface. This is a global object to allow persistent
   # connections, caching, and other features that need a persistent object in the process.
   def self.http
@@ -55,6 +64,6 @@ class Reynard
   private
 
   def build_context
-    Context.new(specification: @specification)
+    Context.new(specification: @specification, inflector: @inflector)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reynard
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Manfred Stienstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-24 00:00:00.000000000 Z
+date: 2023-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -52,62 +52,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: webrick
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: |2
     Reynard is an OpenAPI client for Ruby. It operates directly on the OpenAPI specification without
     the need to generate any source code.
@@ -126,6 +70,7 @@ files:
 - lib/reynard/http.rb
 - lib/reynard/http/request.rb
 - lib/reynard/http/response.rb
+- lib/reynard/inflector.rb
 - lib/reynard/media_type.rb
 - lib/reynard/model.rb
 - lib/reynard/models.rb
@@ -151,7 +96,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="