jsapi 1.4 → 2.0

data/lib/jsapi/meta/example/base.rb

@@ -13,13 +13,18 @@ module Jsapi
         attribute :description, String
 
         ##
-        # :attr: external
-        # If true, +value+ is interpreted as a URI pointing to an external sample value.
-        attribute :external, values: [true, false]
+        # :attr: external_value
+        # The URI of an external sample value.
+        attribute :external_value, String, accessors: %i[reader]
+
+        ##
+        # :attr: serialized_value
+        # The serialized form of the sample value.
+        attribute :serialized_value, accessors: %i[reader]
 
         ##
         # :attr: summary
-        # The summary of the example.
+        # The short summary of the example.
         attribute :summary, String
 
         ##
@@ -27,12 +32,40 @@ module Jsapi
         # The sample value.
         attribute :value
 
+        def external_value=(value) # :nodoc:
+          try_modify_attribute!(:external_value) do
+            raise 'external value and serialized value are mutually exclusive' \
+            unless serialized_value.nil?
+
+            @external_value = value
+          end
+        end
+
+        def serialized_value=(value)  # :nodoc:
+          try_modify_attribute!(:serialized_value) do
+            raise 'external value and serialized value are mutually exclusive' \
+            unless external_value.nil?
+
+            @serialized_value = value
+          end
+        end
+
         # Returns a hash representing the \OpenAPI example object.
-        def to_openapi(*)
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
           with_openapi_extensions(
-            { summary: summary, description: description }.tap do |result|
-              result[external? ? :externalValue : :value] = value
-            end
+            summary: summary,
+            description: description,
+            **if version < OpenAPI::V3_2
+                { value: value }
+              else
+                {
+                  dataValue: value,
+                  serializedValue: serialized_value
+                }
+              end,
+            externalValue: external_value
           )
         end
       end

data/lib/jsapi/meta/existence.rb

@@ -30,7 +30,9 @@ module Jsapi
       # or must be +false+.
       PRESENT = new(4)
 
-      # Creates a new instance from +value+.
+      # Transforms +value+ to an instance of this class.
+      #
+      # Raises an +ArgumentError+ if +value+ could not be transformed.
       def self.from(value)
         return value if value.is_a?(Existence)
 
@@ -53,7 +55,7 @@ module Jsapi
       end
 
       def <=>(other) # :nodoc:
-        level <=> other.level
+        level <=> other.level if other.is_a?(Existence)
       end
 
       def inspect # :nodoc:

data/lib/jsapi/meta/header/base.rb

@@ -23,7 +23,7 @@ module Jsapi
 
         ##
         # :attr: deprecated
-        # Specifies whether or not the header is deprecated.
+        # Specifies whether the header is marked as deprecated.
         attribute :deprecated, values: [true, false]
 
         ##
@@ -70,7 +70,9 @@ module Jsapi
                 description: description,
                 deprecated: deprecated?.presence,
                 schema: schema.to_openapi(version),
-                examples: examples.transform_values(&:to_openapi).presence
+                examples: examples.transform_values do |example|
+                  example.to_openapi(version)
+                end.presence
               }
             end
           )

data/lib/jsapi/meta/info.rb

@@ -23,7 +23,9 @@ module Jsapi
 
       ##
       # :attr: summary
-      # The short summary of the API. Applies to \OpenAPI 3.1 and higher.
+      # The short summary of the API.
+      #
+      # Applies to \OpenAPI 3.1 and higher.
       attribute :summary, String
 
       ##

data/lib/jsapi/meta/license.rb

@@ -8,7 +8,9 @@ module Jsapi
 
       ##
       # :attr: identifier
-      # The SDPX identifier of the license. Applies to \OpenAPI 3.1 and higher.
+      # The SDPX identifier of the license.
+      #
+      # Applies to \OpenAPI 3.1 and higher.
       attribute :identifier, String, accessors: %i[reader]
 
       ##
@@ -22,15 +24,19 @@ module Jsapi
       attribute :url, String, accessors: %i[reader]
 
       def identifier=(identifier) # :nodoc:
-        raise 'identifier and url are mutually exclusive' if url.present?
+        try_modify_attribute!(:identifier) do
+          raise 'identifier and url are mutually exclusive' unless url.nil?
 
-        @identifier = identifier
+          @identifier = identifier
+        end
       end
 
       def url=(url) # :nodoc:
-        raise 'identifier and url are mutually exclusive' if identifier.present?
+        try_modify_attribute!(:url) do
+          raise 'identifier and url are mutually exclusive' unless identifier.nil?
 
-        @url = url
+          @url = url
+        end
       end
 
       # Returns a hash representing the \OpenAPI license object.

data/lib/jsapi/meta/model/attributes/class_methods.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      module Attributes
+        module ClassMethods
+          DEFAULT_ARRAY = [].freeze
+          DEFAULT_HASH = {}.freeze
+
+          # Defines an attribute.
+          def attribute(name, type = Object,
+                        accessors: %i[add reader writer],
+                        default: nil,
+                        default_key: nil,
+                        keys: nil,
+                        values: nil)
+
+            (@attribute_names ||= []) << name.to_sym
+
+            instance_variable_name = "@#{name}"
+
+            case type
+            when Array
+              # General default
+              default ||= DEFAULT_ARRAY
+
+              if accessors.include?(:add) || accessors.include?(:writer)
+                singular_name = name.to_s.singularize
+                add_method = "add_#{singular_name}"
+                type_caster = TypeCaster.new(type.first, values: values, name: singular_name)
+
+                # Attribute writer
+                if accessors.include?(:writer)
+                  define_method("#{name}=") do |argument|
+                    instance_variable_set(instance_variable_name, []).tap do
+                      Array.wrap(argument).each { |element| send(add_method, element) }
+                    end
+                  end
+                end
+
+                # Add method
+                if accessors.include?(:add)
+                  define_method(add_method) do |argument = nil|
+                    try_modify_attribute!(name) do
+                      type_caster.cast(argument).tap do |casted_argument|
+                        if instance_variable_defined?(instance_variable_name)
+                          instance_variable_get(instance_variable_name)
+                        else
+                          instance_variable_set(instance_variable_name, [])
+                        end << casted_argument
+                      end
+                    end
+                  end
+                end
+              end
+            when Hash
+              # General default
+              default ||= DEFAULT_HASH
+
+              singular_name = name.to_s.singularize
+              key_type, value_type = type.first
+              key_type_caster = TypeCaster.new(key_type, values: keys, name: 'key')
+
+              # Lookup method
+              if accessors.include?(:reader)
+                define_method(singular_name) do |key = nil|
+                  key = default_key if key.to_s.empty?
+                  send(name)[key_type_caster.cast(key)]
+                end
+              end
+
+              if accessors.include?(:add) || accessors.include?(:writer)
+                add_method = "add_#{singular_name}"
+                value_type_caster = TypeCaster.new(value_type, values: values)
+
+                # Attribute writer
+                if accessors.include?(:writer)
+                  define_method("#{name}=") do |argument|
+                    instance_variable_set(instance_variable_name, {}).tap do
+                      Hash(argument).each { |key, value| send(add_method, key, value) }
+                    end
+                  end
+                end
+
+                # Add method
+                if accessors.include?(:add)
+                  define_method(add_method) do |key_or_value, value = nil|
+                    try_modify_attribute!(name) do
+                      if value.nil? && default_key
+                        key = default_key
+                        value = key_or_value
+                      else
+                        key = key_or_value
+                        key = default_key if key.to_s.empty?
+                      end
+                      raise ArgumentError, "key can't be blank" if key.to_s.empty?
+
+                      if instance_variable_defined?(instance_variable_name)
+                        instance_variable_get(instance_variable_name)
+                      else
+                        instance_variable_set(instance_variable_name, {})
+                      end[key_type_caster.cast(key)] = value_type_caster.cast(value)
+                    end
+                  end
+                end
+              end
+            else
+              # Predicate method
+              if values == [true, false] && accessors.include?(:reader)
+                define_method("#{name}?") do
+                  value = instance_variable_get(instance_variable_name)
+                  value.nil? ? (default == true) || false : value
+                end
+              end
+
+              # Attribute writer
+              if accessors.include?(:writer)
+                type_caster = TypeCaster.new(type, values: values, name: name)
+
+                define_method("#{name}=") do |argument = nil|
+                  try_modify_attribute!(name) do
+                    instance_variable_set(instance_variable_name, type_caster.cast(argument))
+                  end
+                end
+              end
+            end
+
+            # Attribute reader
+            if accessors.include?(:reader)
+              default = nil if default == :nil
+
+              define_method(name) do
+                value = instance_variable_get(instance_variable_name)
+                value.nil? ? default : value
+              end
+            end
+          end
+
+          def attribute_names
+            names = @attribute_names || []
+            return names unless superclass.respond_to?(:attribute_names)
+
+            superclass.attribute_names + names
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/model/attributes/frozen_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      module Attributes
+        # Raised when trying to modify a frozen attribute.
+        class FrozenError < StandardError
+          def initialize(target)
+            super("can't modify frozen #{target.class}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/model/attributes/type_caster.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      module Attributes
+        class TypeCaster
+          STRING_CASTER = ->(arg) { arg&.to_s } # :nodoc:
+
+          SYMBOL_CASTER = ->(arg) { # :nodoc:
+            return if arg.nil?
+
+            arg = arg.to_s unless arg.respond_to?(:to_sym)
+            arg.to_sym
+          }
+
+          # Creates a new type caster for +klass+.
+          def initialize(klass = nil, name: 'value', values: nil)
+            klass = Object if klass.nil?
+            @caster =
+              case klass.name
+              when 'String'
+                STRING_CASTER
+              when 'Symbol'
+                SYMBOL_CASTER
+              else
+                ->(arg) {
+                  return arg if arg.is_a?(klass)
+                  return klass.from(arg) if klass.respond_to?(:from)
+                  return klass.new if arg.nil?
+
+                  klass.new(arg)
+                }
+              end
+            @values = values
+            @name = name
+          end
+
+          # Casts +value+.
+          #
+          # Raises an ArgumentError if the (casted) value is invalid.
+          def cast(value)
+            casted_value = @caster.call(value)
+            return casted_value unless @values&.exclude?(casted_value)
+
+            raise ArgumentError, Messages.invalid_value(
+              name: @name,
+              value: casted_value,
+              valid_values: @values
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/model/attributes.rb

@@ -1,134 +1,40 @@
 # frozen_string_literal: true
 
+require_relative 'attributes/frozen_error'
+require_relative 'attributes/type_caster'
+require_relative 'attributes/class_methods'
+
 module Jsapi
   module Meta
     module Model
       module Attributes
-        DEFAULT_ARRAY = [].freeze
-        DEFAULT_HASH = {}.freeze
-
-        # Defines an attribute.
-        def attribute(name, type = Object,
-                      accessors: %i[add reader writer],
-                      default: nil,
-                      default_key: nil,
-                      keys: nil,
-                      values: nil)
-
-          (@attribute_names ||= []) << name.to_sym
-
-          instance_variable_name = "@#{name}"
-
-          case type
-          when Array
-            # General default
-            default ||= DEFAULT_ARRAY
-
-            if accessors.include?(:add) || accessors.include?(:writer)
-              singular_name = name.to_s.singularize
-              add_method = "add_#{singular_name}"
-              type_caster = TypeCaster.new(type.first, values: values, name: singular_name)
-
-              # Attribute writer
-              define_method("#{name}=") do |argument|
-                instance_variable_set(instance_variable_name, []).tap do
-                  Array.wrap(argument).each { |element| send(add_method, element) }
-                end
-              end if accessors.include?(:writer)
-
-              # Add method
-              define_method(add_method) do |argument = nil|
-                type_caster.cast(argument).tap do |casted_argument|
-                  if instance_variable_defined?(instance_variable_name)
-                    instance_variable_get(instance_variable_name)
-                  else
-                    instance_variable_set(instance_variable_name, [])
-                  end << casted_argument
-                  attribute_changed(name)
-                end
-              end if accessors.include?(:add)
-            end
-          when Hash
-            # General default
-            default ||= DEFAULT_HASH
-
-            singular_name = name.to_s.singularize
-            key_type, value_type = type.first
-            key_type_caster = TypeCaster.new(key_type, values: keys, name: 'key')
-
-            # Lookup method
-            define_method(singular_name) do |key = nil|
-              key = default_key if key.to_s.empty?
-              send(name)[key_type_caster.cast(key)]
-            end if accessors.include?(:reader)
-
-            if accessors.include?(:add) || accessors.include?(:writer)
-              add_method = "add_#{singular_name}"
-              value_type_caster = TypeCaster.new(value_type, values: values)
-
-              # Attribute writer
-              define_method("#{name}=") do |argument|
-                instance_variable_set(instance_variable_name, {}).tap do
-                  Hash(argument).each { |key, value| send(add_method, key, value) }
-                end
-              end if accessors.include?(:writer)
-
-              # Add method
-              define_method(add_method) do |key_or_value, value = nil|
-                if value.nil? && default_key
-                  key = default_key
-                  value = key_or_value
-                else
-                  key = key_or_value
-                  key = default_key if key.to_s.empty?
-                end
-                raise ArgumentError, "key can't be blank" if key.to_s.empty?
-
-                casted_key = key_type_caster.cast(key)
-                casted_value = value_type_caster.cast(value)
+        def self.included(base) # :nodoc:
+          base.extend(ClassMethods)
+        end
 
-                if instance_variable_defined?(instance_variable_name)
-                  instance_variable_get(instance_variable_name)
-                else
-                  instance_variable_set(instance_variable_name, {})
-                end[casted_key] = casted_value
+        # Returns true when attributes are frozen.
+        def attributes_frozen?
+          @attributes_frozen == true
+        end
 
-                attribute_changed(name)
-                casted_value
-              end if accessors.include?(:add)
-            end
-          else
-            # Predicate method
-            define_method("#{name}?") do
-              value = instance_variable_get(instance_variable_name)
-              value.nil? ? default || false : value
-            end if values == [true, false] && accessors.include?(:reader)
+        # Freezes attributes.
+        def freeze_attributes
+          @attributes_frozen = true
+        end
 
-            if accessors.include?(:writer)
-              type_caster = TypeCaster.new(type, values: values, name: name)
+        protected
 
-              # Attribute writer
-              define_method("#{name}=") do |argument = nil|
-                type_caster.cast(argument).tap do |casted_value|
-                  instance_variable_set(instance_variable_name, casted_value)
-                  attribute_changed(name)
-                end
-              end
-            end
-          end
+        # Invoked whenever an attribute has been changed.
+        def attribute_changed(name); end
 
-          # Attribute reader
-          define_method(name) do
-            value = instance_variable_get(instance_variable_name)
-            value.nil? ? default : value
-          end if accessors.include?(:reader)
-        end
+        private
 
-        def attribute_names
-          names = @attribute_names || []
-          return names unless superclass.respond_to?(:attribute_names)
+        def try_modify_attribute!(name)
+          raise FrozenError.new(self) if attributes_frozen?
 
-          superclass.attribute_names + names
+          result = yield if block_given?
+          attribute_changed(name)
+          result
         end
       end
     end

data/lib/jsapi/meta/model/base.rb

@@ -5,7 +5,7 @@ module Jsapi
     module Model
       # The base meta model class.
       class Base
-        extend Attributes
+        include Attributes
 
         # Creates a new meta model.
         #
@@ -48,10 +48,7 @@ module Jsapi
           self
         end
 
-        protected
-
-        # Invoked whenever an attribute has been changed.
-        def attribute_changed(name); end
+        alias resolve_lazily resolve
       end
     end
   end

data/lib/jsapi/meta/model/reference.rb

@@ -5,19 +5,47 @@ module Jsapi
     module Model
       # The base reference class.
       class Reference < Base
-        # Derrives the component type from the inner most module name.
-        def self.component_type
-          @component_type ||= name.split('::')[-2].underscore
+        class Resolver # :nodoc:
+          def initialize(reference, definitions)
+            @reference = reference
+            @definitions = definitions
+          end
+
+          protected
+
+          def respond_to_missing?(...)
+            @reference.respond_to?(...)
+          end
+
+          private
+
+          def method_missing(name, ...)
+            result = @reference.send(name, ...)
+            return result unless result.nil?
+
+            @reference
+              .resolve(@definitions, deep: false)
+              .resolve_lazily(@definitions)
+              .send(name, ...)
+          end
         end
 
-        # Derrives the \OpenAPI component type from the inner most module name.
-        def self.openapi_component_type
-          @openapi_component_type ||= name.split('::')[-2].pluralize.camelize(:lower)
+        class << self
+          # Derrives the component type from the inner most module name.
+          def component_type
+            @component_type ||= name.split('::')[-2].underscore
+          end
+
+          # Derrives the \OpenAPI component type from the inner most module name.
+          def openapi_component_type
+            @openapi_component_type ||= name.split('::')[-2].pluralize.camelize(:lower)
+          end
         end
 
         ##
         # :attr: description
         # The description to be displayed instead of the description of the referred object.
+        #
         # Applies to \OpenAPI 3.1 and higher.
         attribute :description, String
 
@@ -29,6 +57,7 @@ module Jsapi
         ##
         # :attr: summary
         # The summary to be displayed instead of the summary of the referred object.
+        #
         # Applies to \OpenAPI 3.1 and higher.
         attribute :summary, String
 
@@ -37,14 +66,21 @@ module Jsapi
           true
         end
 
-        # Resolves +ref+ by looking up the object with that name in +definitions+.
+        # Resolves the reference by looking up the referred object in +definitions+.
         #
-        # Raises a ReferenceError if +ref+ could not be resolved.
-        def resolve(definitions)
+        # Raises a ReferenceError if the reference could not be resolved.
+        def resolve(definitions, deep: true)
           object = definitions.send("find_#{self.class.component_type}", ref)
           raise ReferenceError, ref if object.nil?
 
-          object.resolve(definitions)
+          deep ? object.resolve(definitions, deep: true) : object
+        end
+
+        # Lazily resolves the reference.
+        #
+        # Raises a ReferenceError if the reference could not be resolved.
+        def resolve_lazily(definitions)
+          Resolver.new(self, definitions)
         end
 
         # Returns a hash representing the \OpenAPI reference object.

data/lib/jsapi/meta/model/wrappable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      # Defines a +wrap+ class method to wrap an instance of the given class.
+      module Wrappable
+        def self.included(base) # :nodoc:
+          class << base
+            define_method(:wrap) do |model, definitions|
+              return if model.nil?
+
+              wrapper_class = "#{name}::Wrapper".constantize
+              return model if model.is_a?(wrapper_class)
+
+              wrapper_class.new(model, definitions)
+            end
+          end
+        end
+      end
+    end
+  end
+end