media_types 0.1.3 → 0.2.0

data/lib/media_types/registrar.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module MediaTypes
+  class Registerable
+    def initialize(media_type, symbol:, aliases: [])
+      self.media_type = media_type
+      self.symbol = symbol
+      self.aliases = aliases
+
+      freeze
+    end
+
+    def to_s
+      String(media_type)
+    end
+
+    def to_sym
+      symbol
+    end
+
+    attr_accessor :media_type, :symbol, :aliases
+
+    alias synonyms aliases
+    alias mime_type to_s
+
+  end
+
+  ##
+  # Holds all the configuration options in order to call {MediaTypes.register} exactly enough times to register the
+  # media type in its entirety.
+  #
+  # @see Registerable
+  #
+  class Registrar
+
+    ##
+    # Creates a new registry with default values
+    #
+    # @param [Class] klazz the class that has {MediaTypes::Dsl} included
+    # @param [Symbol, NilClass] symbol the symbol the base view (nil view) should be registered under
+    #
+    def initialize(klazz, symbol: nil, &block)
+      self.base_media_type = klazz.to_constructable
+
+      self.registered_views = symbol ? { nil => { symbol: String(symbol).to_sym } } : {}
+      self.registered_versions = [base_media_type.version]
+      self.registered_aliases = []
+      self.registered_suffixes = [String(base_media_type.suffix).to_sym]
+
+      instance_exec(&block) if block_given?
+    end
+
+    ##
+    # Resolves all the permutations and returns a list of {Registerable}
+    #
+    # @return [Array<Registerable>] the registerables based on all the permutations of +self+
+    #
+    def to_a
+      result = []
+
+      each_resolved do |media_type, symbol|
+        result << Registerable.new(media_type, symbol: symbol, aliases: aliases(media_type))
+      end
+
+      result
+    end
+
+    private
+
+    attr_accessor :registered_views, :registered_versions, :registered_aliases, :registered_suffixes,
+                  :symbol_base, :base_media_type
+
+    ##
+    # Registers a +view+ with a +symbol+
+    #
+    # @param [String, Symbol] view the view
+    # @param [String, Symbol] symbol the symbol base for this view
+    #
+    def view(view, symbol)
+      registered_views[String(view)] = { symbol: String(symbol).to_sym }
+      self
+    end
+
+    ##
+    # Registers +versions+
+    #
+    # @param [*Numeric, Array<Numeric>] versions the versions to register
+    #
+    def versions(*versions)
+      registered_versions.push(*Array(versions))
+      self
+    end
+
+    ##
+    # Registers a type alias. This will become a synonym when registering the media type
+    #
+    # @param [String] alias_name the name of the alias
+    #
+    def type_alias(alias_name)
+      registered_aliases.push(String(alias_name))
+      self
+    end
+
+    ##
+    # Registers a suffix
+    #
+    # @param [String, Symbol] suffix the suffix to register
+    #
+    def suffix(suffix)
+      registered_suffixes.push(String(suffix).to_sym)
+      self
+    end
+
+    ##
+    # Calculates the aliased media types for a media type
+    #
+    # @param [Constructable] media_type the media type constructable
+    # @return [Array<String>] the resolved aliases
+    #
+    def aliases(media_type)
+      registered_aliases.map { |a| media_type.type(a).to_s }
+    end
+
+    def each_combination
+      iterable(registered_versions).each do |version|
+        iterable(registered_views).each do |view, view_opts|
+          iterable(registered_suffixes).each do |suffix|
+            opts = { view: view_opts }
+            yield version, view, suffix, opts
+          end
+        end
+      end
+    end
+
+    def iterable(source)
+      source.compact.uniq
+    end
+
+    def each_resolved
+      each_combination do |version, view, suffix, opts|
+        media_type = base_media_type.version(version).view(view).suffix(suffix)
+        symbol = iterable([opts[:view][:symbol], "v#{version}", suffix]).join('_').to_sym
+
+        yield media_type, symbol
+      end
+    end
+  end
+end

data/lib/media_types/scheme/allow_nil.rb

@@ -5,14 +5,21 @@ require 'delegate'
 module MediaTypes
   class Scheme
     class CaseEqualityWithNil < SimpleDelegator
+
+      # Same as the wrapped {Object#===}, but also allows for NilCLass
       def ===(other)
         other.nil? || super
       end
     end
 
     # noinspection RubyInstanceMethodNamingConvention
+    ##
+    # Allows the wrapped +klazz+ to be nil
+    #
+    # @param [Class] klazz the class that +it+ must be the if +it+ is not NilClass
+    # @return [CaseEqualityWithNil]
     def AllowNil(klazz) # rubocop:disable Naming/MethodName
-    CaseEqualityWithNil.new(klazz)
+      CaseEqualityWithNil.new(klazz)
     end
   end
 end

data/lib/media_types/scheme/any_of.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module MediaTypes
+  class Scheme
+    class CaseEqualityWithList < SimpleDelegator
+
+      # True for Enumerable#any? {Object#===}
+      def ===(other)
+        any? { |it| it === other } # rubocop:disable Style/CaseEquality
+      end
+    end
+
+    # noinspection RubyInstanceMethodNamingConvention
+    ##
+    # Allows +it+ to be any of the wrapped +klazzes+
+    #
+    # @param [Array<Class>] klazzes the classes that are valid for +it+
+    # @return [CaseEqualityWithList]
+    def AnyOf(*klazzes) # rubocop:disable Naming/MethodName
+      CaseEqualityWithList.new(klazzes)
+    end
+  end
+end

data/lib/media_types/scheme/attribute.rb

@@ -3,6 +3,16 @@
 module MediaTypes
   class Scheme
     class Attribute
+
+      ##
+      # An attribute that expects a value of type +type+
+      #
+      # @see AllowNil
+      # @see AnyOf
+      #
+      # @param [Class] type the class +it+ must be
+      # @param [TrueClass, FalseClass] allow_nil if true, nil? is allowed
+      #
       def initialize(type, allow_nil: false)
         self.type = type
         self.allow_nil = allow_nil

data/lib/media_types/scheme/enumeration_context.rb

@@ -0,0 +1,16 @@
+module MediaTypes
+  class Scheme
+    class EnumerationContext
+      def initialize(validations:)
+        self.validations = validations
+      end
+
+      def enumerate(val)
+        self.key = val
+        self
+      end
+
+      attr_accessor :validations, :key
+    end
+  end
+end

data/lib/media_types/scheme/enumeration_of_type.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module MediaTypes
+  class Scheme
+    class EnumerationOfType
+
+      ##
+      # An attribute that expects a value of type +enumeration_type+ and each item of type +item_type+
+      #
+      # @param [Class] item_type the type of each item
+      # @param [Class] enumeration_type the type of the enumeration as a whole
+      # @param [TrueClass, FalseClass] allow_empty if true, an empty instance of +enumeration_type+ is valid
+      #
+      def initialize(item_type, enumeration_type: Array, allow_empty: false)
+        self.item_type = item_type
+        self.enumeration_type = enumeration_type
+        self.allow_empty = allow_empty
+
+        freeze
+      end
+
+      def validate!(output, options, **_opts)
+        validate_enumeration!(output, options) &&
+          validate_not_empty!(output, options) &&
+          validate_items!(output, options)
+      end
+
+      private
+
+      attr_accessor :allow_empty, :enumeration_type, :item_type
+
+      def validate_enumeration!(output, options)
+        return true if enumeration_type === output # rubocop:disable Style/CaseEquality
+        raise ValidationError,
+              format(
+                'Expected collection as %<type>s, got %<actual>s at [%<backtrace>s]',
+                type: enumeration_type,
+                actual: output.inspect,
+                backtrace: options.backtrace.join('->')
+              )
+      end
+
+      def validate_not_empty!(output, options)
+        return true if allow_empty
+        return true if output.respond_to?(:length) && output.length.positive?
+        return true if output.respond_to?(:empty?) && !output.empty?
+
+        raise EmptyOutputError,
+              format(
+                'Expected collection to be not empty, got empty at [%<backtrace>s]',
+                backtrace: options.backtrace.join('->')
+              )
+      end
+
+      def validate_items!(output, options)
+        output.all? do |item|
+          next true if item_type === item # rubocop:disable Style/CaseEquality
+          raise ValidationError,
+                format(
+                  'Expected collection item as %<type>s, got %<actual>s at [%<backtrace>s]',
+                  type: item_type,
+                  actual: item.inspect,
+                  backtrace: options.backtrace.join('->')
+                )
+        end
+      end
+
+    end
+  end
+end

data/lib/media_types/scheme/validation_options.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MediaTypes
+  class Scheme
+    class ValidationOptions
+      attr_accessor :exhaustive, :strict, :backtrace
+
+      def initialize(exhaustive: true, strict: true, backtrace: [])
+        self.exhaustive = exhaustive
+        self.strict = strict
+        self.backtrace = backtrace
+      end
+
+      def with_backtrace(backtrace)
+        ValidationOptions.new(exhaustive: exhaustive, strict: strict, backtrace: backtrace)
+      end
+
+      def trace(*traces)
+        with_backtrace(backtrace.dup.concat(traces))
+      end
+
+      def exhaustive!
+        ValidationOptions.new(exhaustive: true, strict: strict, backtrace: backtrace)
+      end
+    end
+  end
+end