media_types 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 27062ffb1d9b17404a0032f220478b120aa41089
-  data.tar.gz: ba0dab9025a4e53aef10e8b9de7edd3ef121c2dc
+  metadata.gz: 3399faaeae9e47d89ee2efe7a327dd8b1ceae7ae
+  data.tar.gz: 2519f99721a48e5aa5f7cf7b014e821717276d8f
 SHA512:
-  metadata.gz: f18dd51f3f86ba10a7c8deb68ce21dc5f2fe1f07bafe2a2fbdf6ed2a30caba04c92df54b1468adce18512641742c593d433b974304db28345804ae6020e79fe4
-  data.tar.gz: b05ed05756b9af5512eca5a10dec3244a75462d8ea3a7869ccd9b6e0fe2dc76b2c4fab5d5d89f39b760f606ec496590b9469d8a82fc2b96f8ea4d288f4576ba4
+  metadata.gz: 55f29a6d81758d3c0fa71153e63677d35d138b22e64afae8ae4e76b349219915f0e826a86d51f83c51c0ff573555abbaa807669766f413f6297ee12a9609ae4c
+  data.tar.gz: c4017a0fc061f4ecbde0f66a3274e59982f6e608847e4654e431f3c3644464481da56c0bd5364c88525d7da1e2f6ea45bb0a69534e37abc86340992ef29f674a

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# 0.2.0
+
+Breaking changes to update public API and usage
+
+ - Remove `Base` class (use `MediaTypes::Dsl` instead)
+ - Remove a lot of configuration options as they are deemed unneeded
+ - Remove `active_support` dependency
+ - Rename `ConstructableMimeType` to `Constructable`
+ - Moved global scheme types to `Scheme` as subtype
+ - Add `MediaTypes::Dsl`
+ - Add `validations` block to capture schemes
+ - Add `registrations` block to capture register intent
+ - Add `defaults` block to capture mime type defaults
+ - Add `MediaTypes.register` class method to call `Mime::Type.register`
+ - Add `Registerable` capture class
+ - Add type / base setting for `Constructable`
+ - Add versioned validations
+ - Add forced types of `collection`s
+ - Add `attribute` with block
+ - Add `EnumerationOfType` for schema typed arrays
+ - Add `AnyOf` for scheme enum types
+ - Add non-block calls for `Scheme` dsl
+ - Add yard documentation to `/docs`
+ 
+# 0.1.0
+
+:baby: initial release

data/Gemfile.lock

@@ -1,12 +1,13 @@
 PATH
   remote: .
   specs:
-    media_types (0.1.3)
+    media_types (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ansi (1.5.0)
+    awesome_print (1.8.0)
     builder (3.2.3)
     docile (1.3.1)
     json (2.1.0)
@@ -30,6 +31,7 @@ PLATFORMS
   x64-mingw32
 
 DEPENDENCIES
+  awesome_print
   bundler (~> 1.16)
   media_types!
   minitest (~> 5.0)

data/README.md

@@ -24,7 +24,7 @@ Or install it yourself as:
 
 By default there are no media types registered or defined, except for an abstract base type.
 
-### Definition
+## Definition
 You can define media types by inheriting from this base type, or create your own base type with a class method
 `.base_format` that is used to create the final media type string by injecting formatted parameters:
 
@@ -37,9 +37,9 @@ You can define media types by inheriting from this base type, or create your own
 require 'media_types'
 
 class Venue < MediaTypes::Base
-  media_type 'venue', suffix: :json, current_version: 2
+  media_type 'venue', defaults: { suffix: :json, version: 2 }
 
-  current_scheme do
+  validations do
     attribute :name, String
     collection :location do
       attribute :latitude, Numeric
@@ -49,22 +49,41 @@ class Venue < MediaTypes::Base
 
     link :self
     link :route, allow_nil: true
-  end
-
-  register_types :venue_json do
-    create     :create_venue_json
-    index      :venue_urls_json
-    collection :venue_collection_json
-  end
-
-  register_additional_versions do
+    
     version 1 do
       attribute :name, String
       attribute :coords, String
       attribute :updated_at, String
-
+    
       link :self
     end
+    
+    view 'create' do
+      collection :location do
+        attribute :latitude, Numeric
+        attribute :longitude, Numeric
+        attribute :altitude, AllowNil(Numeric)
+      end
+      
+      version 1 do
+        collection :location do
+          attribute :latitude, Numeric
+          attribute :longitude, Numeric
+          attribute :altitude, AllowNil(Numeric)
+        end
+      end
+    end
+  end
+
+  registrations :venue_json do
+    view 'create', :create_venue
+    view 'index', :venue_urls
+    view 'collection', :venue_collection
+    
+    versions [1,2]
+    
+    suffix :json
+    suffix :xml
   end
   
   def self.base_format
@@ -73,26 +92,201 @@ class Venue < MediaTypes::Base
 end
 ```
 
-### Schema Definitions
+## Schema Definitions
 
 If you define a scheme using `current_scheme { }`, you may use any of the following dsl:
 
-- `attribute(string, klazz)`: Adds an attribute to the scheme, with the type `klazz`
-- `any(&block)`: Allow for any key, which then is validated against the block (which is a scheme).
-- `collection(string, &block)`: Expect a collection such as an array or hash. If it's an array, each item is validated
-against the block (which is a scheme). If it's a hash, the hash is validated against the block. If you want to force an
-array or an object, prepend the collection by `attribute(string, Hash)` or `attribute(string, Array)`.
-- `no_strict`: Can be added to a `scheme` such as the root, block inside `any` or block inside `collection` to allow for
-undefined keys. If `no_strict` is not added, the block will not be valid if there are extra keys.
-- `link(string)`: Example of a domain type. Each link is actually added to a scheme for `_links` on the current scheme.
+### `attribute`
+
+Adds an attribute to the schema, if a +block+ is given, uses that to test against instead of +type+
+
+| param | type | description |
+|-------|------|-------------|
+| key | `Symbol` | the attribute name |
+| opts | `Hash` | options to pass to `Scheme` or `Attribute` |
+| type | `Class`, `===`, Scheme | The type of the value, can be anything that responds to `===`,  or scheme to use if no `&block` is given. Defaults to `String` without a `&block` and to Hash with a `&block`. |
+| &block | `Block` | defines the scheme of the value of this attribute |
+
+#### Add an attribute named foo, expecting a string
+```Ruby
+require 'media_types'
+
+class MyMedia
+  include MediaTypes::Dsl
+
+  validations do
+    attribute :foo, String
+  end
+end
+
+MyMedia.valid?({ foo: 'my-string' })
+# => true
+```
+
+####  Add an attribute named foo, expecting nested scheme
 
-If you want to compose types, you can wrap a klazz in `AllowNil(klazz)` to allow for nil values. This makes a validation
-expected that klass, or nil.
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   attribute :foo do
+     attribute :bar, String
+   end
+ end
+end
+
+MyMedia.valid?({ foo: { bar: 'my-string' }})
+# => true
+```
 
-You an add your own DSL by inspecting the `lib/media_types/scheme/<klazz>` classes.
+### `any`
+Allow for any key. The `&block` defines the Schema for each value.
 
-### Validation
-If your type has a schema, you can now use this media type for validation:
+| param | type | description |
+|-------|------|-------------|
+| scheme | `Scheme`, `NilClass` | scheme to use if no `&block` is given |
+| allow_empty: | `TrueClass`, `FalsClass` | if true, empty (no key/value present) is allowed |
+| force: | `Class`, | forces the validated value to have this type, defaults to `Hash` |
+| &block | `Block` | defines the scheme of the value of this attribute |
+
+#### Add a collection named foo, expecting any key with a defined value
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo do
+     any do
+       attribute :bar, String
+     end
+   end
+ end
+end
+
+MyMedia.valid?({ foo: [{ anything: { bar: 'my-string' }, other_thing: { bar: 'other-string' } }] })
+# => true
+```` 
+
+### `not_strict`
+Allow for extra keys in the schema/collection even when passing `strict: true` to `#validate!`
+
+#### Allow for extra keys in collection
+
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo do
+     attribute :required, String
+     not_strict
+   end
+ end
+end
+
+MyMedia.valid?({ foo: [{ required: 'test', bar: 42 }] })
+# => true
+``` 
+  
+### `collection`
+Expect a collection such as an array or hash. The `&block` defines the Schema for each item in that collection.
+
+| param | type | description |
+|-------|------|-------------|
+| key | `Symbol` | key of the collection (same as `#attribute`) |
+| scheme | `Scheme`, `NilClass`, `Class` | scheme to use if no `&block` is given or `Class` of each item in the  |
+| allow_empty: | `TrueClass`, `FalsClass` | if true, empty (no key/value present) is allowed |
+| force: | `Class`, | forces the validated value to have this type, defaults to `Array` |
+| &block | `Block` | defines the scheme of the value of this attribute |
+
+
+#### Collection with an array of string
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo, String
+ end
+end
+
+MyMedia.valid?({ collection: ['foo', 'bar'] })
+# => true
+```
+
+#### Collection with defined scheme
+
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo do
+     attribute :required, String
+     attribute :number, Numeric
+   end
+ end
+end
+
+MyMedia.valid?({ foo: [{ required: 'test', number: 42 }, { required: 'other', number: 0 }] })
+# => true
+```
+
+### `link`
+
+Expect a link
+
+#### Links as defined in HAL, JSON-Links and other specs
+```Ruby
+class MyMedia
+  include MediaTypes::Dsl
+
+  validations do
+    link :_self
+    link :image
+  end
+end
+
+MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
+# => true
+```
+
+
+#### Link with extra attributes
+```Ruby
+class MyMedia
+  include MediaTypes::Dsl
+
+  validations do
+    link :image do
+      attribute :templated, TrueClass
+    end
+  end
+end
+
+MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
+# => true
+```
+
+#### Link with extra attributes
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   link :image do
+     attribute :templated, TrueClass
+   end
+ end
+end
+
+MyMedia.valid?({ _links: { image: { href: 'https://image.org/{md5}', templated: true }} })
+# => true
+```
+
+## Validation
+If your type has a validations, you can now use this media type for validation:
 
 ```Ruby
 Venue.valid?({ ... })
@@ -102,11 +296,10 @@ Venue.validate!({ ... })
 # => raises if it's not valid
 ```
 
-### Formatting for headers
+## Formatting for headers
 Any media type object can be coerced in valid string to be used with `Content-Type` or `Accept`:
 
 ```Ruby
-
 Venue.mime_type.to_s
 # => "application/vnd.mydomain.venue.v2+json"
 
@@ -126,7 +319,11 @@ Venue.mime_type.view('active').to_s
 # => "application/vnd.mydomain.venue.v2.active+json"
 ```
 
-### Register in Rails or Rack
+## Register in Rails or Rack
+Define a `registrations` block on your media type, indicating the symbol for the base type (`registrations :symbol do`)
+and inside use the registrations dsl to define which media types to register. `versions array_of_numbers` determines which versions, 
+`suffix name` adds a suffix, `type_alias name` adds an alias and `view name, symbol` adds a view.
+
 As long as `action_dispatch` is available, you can register the mime type with `action_dispatch/http/mime_type`:
 ```Ruby
 Venue.register
@@ -147,4 +344,4 @@ push the `.gem` file to rubygems.org.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [SleeplessByte/media_types-ruby](https://github.com/SleeplessByte/media_types-ruby)
+Bug reports and pull requests are welcome on GitHub at [SleeplessByte/media-types-ruby](https://github.com/SleeplessByte/media-types-ruby)

data/Rakefile

@@ -1,10 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/lib/media_types/{constructable_mime_type.rb → constructable.rb}

@@ -4,26 +4,31 @@ require 'delegate'
 require 'singleton'
 
 module MediaTypes
-  class ConstructableMimeType < SimpleDelegator
+  class Constructable < SimpleDelegator
 
     def initialize(klazz, **opts)
       super klazz
       self.opts = opts
     end
 
+    def type(name = NO_ARG)
+      return opts[:type] if name == NO_ARG
+      Constructable.new(__getobj__, **with(type: name))
+    end
+
     def version(version = NO_ARG)
       return opts[:version] if version == NO_ARG
-      ConstructableMimeType.new(__getobj__, **with(version: version))
+      Constructable.new(__getobj__, **with(version: version))
     end
 
     def view(view = NO_ARG)
       return opts[:view] if view == NO_ARG
-      ConstructableMimeType.new(__getobj__, **with(view: view))
+      Constructable.new(__getobj__, **with(view: view))
     end
 
     def suffix(suffix = NO_ARG)
       return opts[:suffix] if suffix == NO_ARG
-      ConstructableMimeType.new(__getobj__, **with(suffix: suffix))
+      Constructable.new(__getobj__, **with(suffix: suffix))
     end
 
     def collection

data/lib/media_types/defaults.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module MediaTypes
+  class Defaults
+    def initialize(media_type, &block)
+      self.media_type = media_type
+
+      instance_exec(&block) if block_given?
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      if media_type.respond_to?(method_name)
+        return self.media_type = media_type.send(method_name, *arguments, &block)
+      end
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      media_type.respond_to?(method_name) || super
+    end
+
+    def to_constructable
+      media_type
+    end
+
+    private
+
+    attr_accessor :media_type
+  end
+end

data/lib/media_types/dsl.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'media_types/constructable'
+require 'media_types/defaults'
+require 'media_types/registrar'
+require 'media_types/validations'
+
+module MediaTypes
+  module Dsl
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+        class << self
+          private
+
+          attr_accessor :media_type_constructable, :symbol_base, :media_type_registrar, :media_type_validations
+        end
+      end
+    end
+
+    module ClassMethods
+
+      def to_constructable
+        media_type_constructable.dup
+      end
+
+      def valid?(output, media_type = to_constructable, **opts)
+        validations.find(String(media_type)).valid?(output, backtrace: ['.'], **opts)
+      end
+
+      def validate!(output, media_type = to_constructable, **opts)
+        validations.find(String(media_type)).validate(output, backtrace: ['.'], **opts)
+      end
+
+      def register
+        registrations.to_a.map do |registerable|
+          MediaTypes.register(registerable)
+          registerable
+        end
+      end
+
+      private
+
+      def media_type(name, defaults: {})
+        self.media_type_constructable =
+          Constructable.new(self, format: base_format, type: name)
+                       .version(defaults.fetch(:version) { nil })
+                       .suffix(defaults.fetch(:suffix) { nil })
+                       .view(defaults.fetch(:view) { nil })
+      end
+
+      def defaults(&block)
+        self.media_type_constructable = Defaults.new(to_constructable, &block).to_constructable
+      end
+
+      def registrations(symbol = nil, &block)
+        self.media_type_registrar = media_type_registrar || Registrar.new(self, symbol: symbol, &block)
+      end
+
+      def validations(&block)
+        self.media_type_validations = media_type_validations || Validations.new(to_constructable, &block)
+      end
+    end
+  end
+end

data/lib/media_types/hash.rb

@@ -0,0 +1,21 @@
+module MediaTypes
+  class Hash < SimpleDelegator
+    def class
+      __getobj__.class
+    end
+
+    def ===(other)
+      __getobj__ === other # rubocop:disable Style/CaseEquality
+    end
+
+    def slice(*keep_keys)
+      if __getobj__.respond_to?(:slice)
+        return __getobj__.slice(*keep_keys)
+      end
+
+      h = {}
+      keep_keys.each { |key| h[key] = fetch(key) if key?(key) }
+      h
+    end
+  end
+end

data/lib/media_types/minitest/assert_media_types_registered.rb

@@ -106,10 +106,10 @@ module MediaTypes
       uncalled = expected_types_hash.dup
 
       uncalled.length.times do
-        mock.expect(:call, nil) do |arguments|
-          type = arguments.fetch(:mime_type)
-          symbol = arguments.fetch(:symbol)
-          synonyms = arguments.fetch(:synonyms)
+        mock.expect(:call, nil) do |registerable|
+          type = registerable.to_s
+          symbol = registerable.to_sym
+          synonyms = registerable.synonyms
 
           options = uncalled.delete(type)
           options && options == [symbol, synonyms] || raise(

data/lib/media_types/object.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MediaTypes
+  class Object < SimpleDelegator
+    def class
+      __getobj__.class
+    end
+
+    def ===(other)
+      __getobj__ === other # rubocop:disable Style/CaseEquality
+    end
+
+    def blank?
+      if __getobj__.respond_to?(:blank?)
+        return __getobj__.blank?
+      end
+
+      if __getobj__.respond_to?(:empty?)
+        return __getobj__.empty?
+      end
+
+      if __getobj__.respond_to?(:length)
+        return __getobj__.length.zero?
+      end
+
+      !__getobj__
+    end
+
+    alias empty? blank?
+
+    def present?
+      !blank?
+    end
+  end
+end