media_types 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 40c245e8d88896a28fc047f4c05f1991c59a95ba
+  data.tar.gz: 007f468d119afe894a615e4acd28a16a9175cfa4
+SHA512:
+  metadata.gz: 38e8ac6b119157c3ac12ac84f0cf495c797c9878df4f60cc24570ac7baf890941d95a62a540281a924eedff94f21acdccfd598f07a169380490b9e4946da2aac
+  data.tar.gz: 7243579da6b1819058856ebcfe85262cf48f509983e06e288fba8d5ac10ded2880fd3ed997b21f823ff83e80a2f4c6cec106bc33e2417e7a6290144d8fefdedb

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.idea/

data/.rubocop.yml

@@ -0,0 +1,29 @@
+AllCops:
+  Include:
+    - '**/Rakefile'
+    - 'lib/**/*.rb'
+  Exclude:
+    - 'Gemfile'
+    - 'bin/**/*'
+  TargetRubyVersion: 2.4
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EndOfLine:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 15
+
+Style/Documentation:
+  Enabled: false
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/IfUnlessModifier:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,20 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.3.0
+  - 2.4
+  - 2.5
+  - 2.6
+  - rbx-3
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: rbx-3
+    - rvm: 2.6
+before_install:
+  - gem update --system
+  - gem --version
+install:
+  - bundle install --with development --jobs=3 --retry=3 --path=${BUNDLE_PATH:-vendor/bundle}

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in media_types.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    media_types (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.5.0)
+    builder (3.2.3)
+    docile (1.3.1)
+    json (2.1.0)
+    minitest (5.11.3)
+    minitest-ci (3.4.0)
+      minitest (>= 5.0.6)
+    minitest-reporters (1.3.4)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    rake (10.5.0)
+    ruby-progressbar (1.10.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+
+PLATFORMS
+  x64-mingw32
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  media_types!
+  minitest (~> 5.0)
+  minitest-ci
+  minitest-reporters
+  rake (~> 10.0)
+  simplecov
+
+BUNDLED WITH
+   1.16.4

data/README.md

@@ -0,0 +1,150 @@
+# MediaTypes
+[![Build Status](https://travis-ci.com/SleeplessByte/media-types-ruby.svg?branch=master)](https://travis-ci.com/SleeplessByte/media-types-ruby)
+[![Gem Version](https://badge.fury.io/rb/media-types-ruby.svg)](https://badge.fury.io/rb/media-types-ruby)
+[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) 
+[![Maintainability](https://api.codeclimate.com/v1/badges/6f2dc1fb37ecb98c4363/maintainability)](https://codeclimate.com/github/SleeplessByte/media-types-ruby/maintainability)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'media_types'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install media_types
+
+## Usage
+
+By default there are no media types registered or defined, except for an abstract base type.
+
+### 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:
+
+- `%<type>s`: the type `media_type` received
+- `%<version>s`: the version, defaults to `:current_version`
+- `%<view>s`: the view, defaults to <empty>
+- `%<suffix>s`: the suffix
+
+```Ruby
+require 'media_types'
+
+class Venue < MediaTypes::Base
+  media_type 'venue', suffix: :json, current_version: 2
+
+  current_scheme do
+    attribute :name, String
+    collection :location do
+      attribute :latitude, Numeric
+      attribute :longitude, Numeric
+      attribute :altitude, AllowNil(Numeric)
+    end
+
+    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
+  end
+  
+  def self.base_format
+    'application/vnd.mydomain.%<type>s.v%<version>s%<view>s+%<suffix>s'
+  end
+end
+```
+
+### 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.
+
+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.
+
+You an add your own DSL by inspecting the `lib/media_types/scheme/<klazz>` classes.
+
+### Validation
+If your type has a schema, you can now use this media type for validation:
+
+```Ruby
+Venue.valid?({ ... })
+# => true if valid, false otherwise
+
+Venue.validate!({ ... })
+# => raises if it's not valid
+```
+
+### 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"
+
+Venue.mime_type.version(1).to_s
+# => "application/vnd.mydomain.venue.v1+json"
+
+Venue.mime_type.version(1).suffix(:xml).to_s
+# => "application/vnd.mydomain.venue.v1+xml"
+
+Venue.mime_type.to_s(0.2)
+# => "application/vnd.mydomain.venue.v2+json; q=0.2"
+
+Venue.mime_type.collection.to_s
+# => "application/vnd.mydomain.venue.v2.collection+json"
+
+Venue.mime_type.view('active').to_s
+# => "application/vnd.mydomain.venue.v2.active+json"
+```
+
+### Register in Rails or Rack
+As long as `action_dispatch` is available, you can register the mime type with `action_dispatch/http/mime_type`:
+```Ruby
+Venue.register
+# => Mime type is now available using the symbol, or lookup the actual mimetype
+```
+
+You can do this in the `mime_types` initializer, or anywhere before your controllers are instantiated. Yes, the symbol
+(by default `<type>_v<version>_<suffix>`) can now be used in your `format` blocks, or as extension in the url.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, call `bundle exec rake release` to create a new git tag, push git commits and tags, and
+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)

data/Rakefile

@@ -0,0 +1,10 @@
+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"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'media_types'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/media_types.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'media_types/version'
+require 'media_types/base'
+require 'media_types/scheme'
+
+require 'delegate'
+
+module MediaTypes
+  COLLECTION_VIEW = 'collection'
+  INDEX_VIEW = 'index'
+  CREATE_VIEW = 'create'
+
+  module_function
+
+  def register(mime_type:, symbol: nil, synonyms: [])
+    require 'action_dispatch/http/mime_type'
+    Mime::Type.register(mime_type, symbol, synonyms)
+  end
+
+  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
+
+      # noinspection RubySimplifyBooleanInspection
+      __getobj__.respond_to?(:empty?) ? !!__getobj__.empty? : !__getobj__ # rubocop:disable Style/DoubleNegation
+    end
+
+    def present?
+      !blank?
+    end
+  end
+
+  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/base.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'media_types/base/collector'
+require 'media_types/constructable_mime_type'
+require 'media_types/scheme'
+
+module MediaTypes
+  class Base
+
+    class << self
+      ##
+      # Registers all configured mime types
+      #
+      def register(**overrides)
+        override_version = overrides.delete(:version)
+        if override_version
+          self.versions_ = { override_version => { scheme: (overrides.delete(:scheme) || current_scheme_) } }
+        end
+
+        Array(registers_).map do |registered|
+          resolvable = registered.merge(Hash(overrides))
+          mime_type = construct_mime_type(resolvable)
+
+          resolve_versions(resolvable) do |version, symbol:|
+            MediaTypes.register(
+              mime_type: mime_type.version(version).to_s,
+              symbol: symbol,
+              synonyms: versioned_synonyms(version, resolvable)
+            )
+            symbol
+          end
+        end.flatten.compact
+      end
+
+      ##
+      # Get the constructable mime type for this class
+      #
+      # @return [ConstructableMimeType]
+      #
+      def mime_type(type: type_, version: current_version_, suffix: suffix_, view: nil)
+        ConstructableMimeType.new(self, format: base_format, version: version, suffix: suffix, type: type, view: view)
+      end
+
+      def current_version
+        current_version_
+      end
+
+      def valid?(output, version: current_version, **opts)
+        scheme = version_scheme(version: version)
+        !scheme || scheme.valid?(output, backtrace: ['.'], **opts)
+      end
+
+      def validate!(output, version: current_version, **opts)
+        scheme = version_scheme(version: version)
+        scheme.validate(output, backtrace: ['.'], **opts)
+      end
+
+      protected
+
+      attr_accessor :type_, :suffix_, :registers_, :versions_, :type_aliases_, :current_version_, :current_scheme_
+
+      def base_format
+        NotImplementedError.new('Implementors of MediaType::Base must override base_format')
+      end
+
+      ##
+      # Configure the media type
+      #
+      # @param [String] media_type the +type+ part of the media type
+      # @param [Symbol, String, NilClass] suffix the +suffix+ part of the media type
+      # @param [Array<String>] aliases the aliases of +media_type+
+      # @param [Number, String] version the latest version
+      #
+      def media_type(media_type, suffix: nil, aliases: [], current_version: nil, version: current_version, &block)
+        self.type_ = media_type
+        self.type_aliases_ = aliases
+        self.suffix_ = suffix
+
+        self.current_version_ = version
+        self.current_scheme_ = current_scheme(&block)
+      end
+
+      def current_scheme(&block)
+        scheme = Scheme.new
+        scheme.instance_exec(&block) if block_given?
+
+        self.current_scheme_ = scheme
+      end
+
+      ##
+      # Start registering media types
+      #
+      # @param [Symbol] opts optional symbol
+      # @option options [Symbol] symbol the symbol to register as if not given by +opts+
+      # @option options [Number] version the version to register for defaults to +current_version_+
+      # @option options [String, NilClass] view the view of the registered type
+      # @option options [String] synonyms synonyms to resolve to the same type
+      #
+      # @yieldparam [Collector] the collector to collect views for the media type
+      #
+      def register_types(*opts, **options, &block)
+        version = options.delete(:version)
+        symbol_suffix = options.delete(:symbol_suffix)
+
+        register_type(*opts, **options)
+        register_version(version || current_version_, symbol_suffix: symbol_suffix, scheme: current_scheme_)
+
+        return unless block_given?
+        block_collector(&block)
+      end
+
+      def register_additional_versions(&block)
+        block_collector(&block)
+      end
+
+      private
+
+      def block_collector(&block)
+        collector = Collector.new(self)
+
+        case block.arity
+        when 1, -1
+          collector.instance_exec(collector, &block)
+        else
+          collector.instance_exec(&block)
+        end
+      end
+
+      # @param [Symbol] opts optional symbol
+      # @param [Symbol] symbol the symbol to register as if not given by +opts+
+      # @param [String, NilClass] view the view of the registered type
+      # @param [String] synonyms synonyms to resolve to the same type
+      # rubocop:disable Metrics/ParameterLists
+      def register_type(*opts, suffix: suffix_, view: nil, symbol: nil, synonyms: [], version: nil)
+        symbol = opts&.first || symbol
+        self.registers_ = Array(registers_).push(
+          symbol: symbol,
+          view: view,
+          synonyms: synonyms,
+          suffix: suffix,
+          pinned_version: version
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def construct_mime_type(type: type_, **resolvable)
+        mime_type(type: type, **MediaTypes::Hash.new(resolvable).slice(:version, :view, :suffix))
+      end
+
+      def synonyms(resolvable)
+        aliases = type_aliases_.map { |type_alias| construct_mime_type(type: type_alias, **resolvable) }
+
+        Array(resolvable[:synonyms]).concat(aliases)
+      end
+
+      def register_version(version, symbol_suffix: :"_v#{version}", scheme: Scheme.new, &block)
+        scheme.instance_exec(&block) if block_given?
+
+        self.versions_ = Hash(versions_).merge(
+          version => {
+            symbol_suffix: symbol_suffix,
+            scheme: scheme
+          }
+        )
+      end
+
+      def resolve_versions(**resolvable)
+        pinned_version = resolvable[:pinned_version]
+
+        versions.map do |version, opts|
+          next if pinned_version && pinned_version != version
+          yield version, symbol: :"#{resolvable.fetch(:symbol)}#{opts[:symbol_suffix]}"
+        end
+      end
+
+      def versioned_synonyms(version, resolvable)
+        synonyms(resolvable).map do |synonym|
+          synonym.is_a?(String) ? synonym : synonym.version(version).to_s
+        end.uniq
+      end
+
+      def versions
+        { current_version => { scheme: current_scheme_ } }.merge(Hash(versions_))
+      end
+
+      def version_scheme(version:)
+        version_data = versions[version]
+        return nil unless version_data
+        version_data[:scheme] || nil
+      end
+    end
+  end
+end