dry-types 0.9.2 → 0.9.3

data/lib/dry/types/hash.rb

@@ -3,6 +3,11 @@ require 'dry/types/hash/schema'
 module Dry
   module Types
     class Hash < Definition
+      # @param [{Symbol => Definition}] type_map
+      # @param [Class] klass
+      #   {Schema} or one of its subclasses ({Weak}, {Permissive}, {Strict},
+      #   {StrictWithDefaults}, {Symbolized})
+      # @return [Schema]
       def schema(type_map, klass = Schema)
         member_types = type_map.each_with_object({}) { |(name, type), result|
           result[name] =
@@ -15,28 +20,41 @@ module Dry
         klass.new(primitive, options.merge(member_types: member_types))
       end
 
+      # @param [{Symbol => Definition}] type_map
+      # @return [Weak]
       def weak(type_map)
         schema(type_map, Weak)
       end
 
+      # @param [{Symbol => Definition}] type_map
+      # @return [Permissive]
       def permissive(type_map)
         schema(type_map, Permissive)
       end
 
+      # @param [{Symbol => Definition}] type_map
+      # @return [Strict]
       def strict(type_map)
         schema(type_map, Strict)
       end
 
+      # @param [{Symbol => Definition}] type_map
+      # @return [StrictWithDefaults]
       def strict_with_defaults(type_map)
         schema(type_map, StrictWithDefaults)
       end
 
+      # @param [{Symbol => Definition}] type_map
+      # @return [Symbolized]
       def symbolized(type_map)
         schema(type_map, Symbolized)
       end
 
       private
 
+      # @param [Hash] _result
+      # @param [Symbol] _key
+      # @param [Definition] _type
       def resolve_missing_value(_result, _key, _type)
         # noop
       end

data/lib/dry/types/hash/schema.rb

@@ -1,19 +1,38 @@
 module Dry
   module Types
     class Hash < Definition
+      # The built-in Hash type has constructors that you can use to define
+      # hashes with explicit schemas and coercible values using the built-in types.
+      #
+      # Basic {Schema} evaluates default values for keys missing in input hash
+      # (see {Schema#resolve_missing_value})
+      #
+      # @see Dry::Types::Default#evaluate
+      # @see Dry::Types::Default::Callable#evaluate
       class Schema < Hash
+        # @return [Hash{Symbol => Definition}]
         attr_reader :member_types
 
+        # @param [Class] _primitive
+        # @param [Hash] options
+        # @option options [Hash{Symbol => Definition}] :member_types
         def initialize(_primitive, options)
           @member_types = options.fetch(:member_types)
           super
         end
 
+        # @param [Hash] hash
+        # @return [Hash{Symbol => Object}]
         def call(hash)
           coerce(hash)
         end
         alias_method :[], :call
 
+        # @param [Hash] hash
+        # @param [#call] block
+        # @yieldparam [Failure] failure
+        # @yieldreturn [Result]
+        # @return [Result]
         def try(hash, &block)
           success = true
           output  = {}
@@ -40,12 +59,16 @@ module Dry
 
         private
 
+        # @param [Hash] hash
+        # @return [Hash{Symbol => Object}]
         def try_coerce(hash)
           resolve(hash) do |type, key, value|
             yield(key, type.try(value))
           end
         end
 
+        # @param [Hash] hash
+        # @return [Hash{Symbol => Object}]
         def coerce(hash)
           resolve(hash) do |type, key, value|
             begin
@@ -56,6 +79,8 @@ module Dry
           end
         end
 
+        # @param [Hash] hash
+        # @return [Hash{Symbol => Object}]
         def resolve(hash)
           result = {}
           member_types.each do |key, type|
@@ -68,6 +93,12 @@ module Dry
           result
         end
 
+        # @param [Hash] result
+        # @param [Symbol] key
+        # @param [Definition] type
+        # @return [Object]
+        # @see Dry::Types::Default#evaluate
+        # @see Dry::Types::Default::Callable#evaluate
         def resolve_missing_value(result, key, type)
           if type.default?
             result[key] = type.evaluate
@@ -77,17 +108,33 @@ module Dry
         end
       end
 
+      # Permissive schema raises a {MissingKeyError} if the given key is missing
+      # in provided hash.
       class Permissive < Schema
         private
 
+        # @param [Symbol] key
+        # @raise [MissingKeyError] when key is missing in given input
         def resolve_missing_value(_, key, _)
           raise MissingKeyError, key
         end
       end
 
+      # Strict hash will raise errors when keys are missing or value types are incorrect.
+      # Strict schema raises a {UnknownKeysError} if there are any unexpected
+      # keys in given hash, and raises a {MissingKeyError} if any key is missing
+      # in it.
+      # @example
+      #   hash = Types::Hash.strict(name: Types::String, age: Types::Coercible::Int)
+      #   hash[email: 'jane@doe.org', name: 'Jane', age: 21]
+      #     # => Dry::Types::SchemaKeyError: :email is missing in Hash input
       class Strict < Permissive
         private
 
+        # @param [Hash] hash
+        # @return [Hash{Symbol => Object}]
+        # @raise [UnknownKeysError]
+        #   if there any unexpected key in given hash
         def resolve(hash)
           unexpected = hash.keys - member_types.keys
           raise UnknownKeysError.new(*unexpected) unless unexpected.empty?
@@ -100,9 +147,20 @@ module Dry
         end
       end
 
+      # {StrictWithDefaults} checks that there are no extra keys
+      # (raises {UnknownKeysError} otherwise) and there a no missing keys
+      # without default values given (raises {MissingKeyError} otherwise).
+      # @see Default#evaluate
+      # @see Default::Callable#evaluate
       class StrictWithDefaults < Strict
         private
 
+        # @param [Hash] result
+        # @param [Symbol] key
+        # @param [Definition] type
+        # @return [Object]
+        # @see Dry::Types::Default#evaluate
+        # @see Dry::Types::Default::Callable#evaluate
         def resolve_missing_value(result, key, type)
           if type.default?
             result[key] = type.evaluate
@@ -112,7 +170,12 @@ module Dry
         end
       end
 
+      # Weak schema provides safe types for every type given in schema hash
+      # @see Safe
       class Weak < Schema
+        # @param [Class] primitive
+        # @param [Hash] options
+        # @see #initialize
         def self.new(primitive, options)
           member_types = options.
             fetch(:member_types).
@@ -121,6 +184,11 @@ module Dry
           super(primitive, options.merge(member_types: member_types))
         end
 
+        # @param [Hash] hash
+        # @param [#call] block
+        # @yieldparam [Failure] failure
+        # @yieldreturn [Result]
+        # @return [Result]
         def try(hash, &block)
           if hash.is_a?(::Hash)
             super
@@ -131,6 +199,7 @@ module Dry
         end
       end
 
+      # {Symbolized} hash will turn string key names into symbols.
       class Symbolized < Weak
         private
 

data/lib/dry/types/options.rb

@@ -1,18 +1,24 @@
 module Dry
   module Types
     module Options
+      # @return [Hash]
       attr_reader :options
 
+      # @see Definition#initialize
       def initialize(*args, **options)
         @__args__ = args
         @options = options
         @meta = options.fetch(:meta, {})
       end
 
+      # @param [Hash] new_options
+      # @return [Definition]
       def with(new_options)
         self.class.new(*@__args__, options.merge(new_options))
       end
 
+      # @param [Hash] data
+      # @return [Hash, Definition]
       def meta(data = nil)
         data ? with(meta: @meta.merge(data)) : @meta
       end

data/lib/dry/types/result.rb

@@ -5,17 +5,21 @@ module Dry
     class Result
       include Dry::Equalizer(:input)
 
+      # @return [Object]
       attr_reader :input
 
+      # @param [Object] input
       def initialize(input)
         @input = input
       end
 
       class Success < Result
+        # @return [true]
         def success?
           true
         end
 
+        # @return [false]
         def failure?
           false
         end
@@ -24,21 +28,27 @@ module Dry
       class Failure < Result
         include Dry::Equalizer(:input, :error)
 
+        # @return [#to_s]
         attr_reader :error
 
+        # @param [Object] input
+        # @param [#to_s] error
         def initialize(input, error)
           super(input)
           @error = error
         end
 
+        # @return [String]
         def to_s
           error.to_s
         end
 
+        # @return [false]
         def success?
           false
         end
 
+        # @return [true]
         def failure?
           true
         end

data/lib/dry/types/safe.rb

@@ -7,6 +7,8 @@ module Dry
       include Decorator
       include Builder
 
+      # @param [Object] input
+      # @return [Object]
       def call(input)
         result = try(input)
 
@@ -18,6 +20,11 @@ module Dry
       end
       alias_method :[], :call
 
+      # @param [Object] input
+      # @param [#call] block
+      # @yieldparam [Failure] failure
+      # @yieldreturn [Result]
+      # @return [Result]
       def try(input, &block)
         type.try(input, &block)
       rescue TypeError, ArgumentError => e
@@ -27,6 +34,8 @@ module Dry
 
       private
 
+      # @param [Object, Dry::Types::Constructor] response
+      # @return [Boolean]
       def decorate?(response)
         super || response.kind_of?(Constructor)
       end

data/lib/dry/types/sum.rb

@@ -7,19 +7,26 @@ module Dry
       include Builder
       include Options
 
+      # @return [Definition]
       attr_reader :left
 
+      # @return [Definition]
       attr_reader :right
 
       class Constrained < Sum
+        # @return [Dry::Logic::Rule]
         def rule
           left.rule | right.rule
         end
 
+        # @return [true]
         def constrained?
           true
         end
 
+        # @param [Object] input
+        # @return [Object]
+        # @raise [ConstraintError] if given +input+ not passing {#try}
         def call(input)
           try(input) do |result|
             raise ConstraintError.new(result, input)
@@ -28,28 +35,37 @@ module Dry
         alias_method :[], :call
       end
 
+      # @param [Definition] left
+      # @param [Definition] right
+      # @param [Hash] options
       def initialize(left, right, options = {})
         super
         @left, @right = left, right
         freeze
       end
 
+      # @return [String]
       def name
         [left, right].map(&:name).join(' | ')
       end
 
+      # @return [false]
       def default?
         false
       end
 
+      # @return [false]
       def maybe?
         false
       end
 
+      # @return [false]
       def constrained?
         false
       end
 
+      # @param [Object] input
+      # @return [Object]
       def call(input)
         try(input).input
       end
@@ -69,10 +85,14 @@ module Dry
         end
       end
 
+      # @param [Object] value
+      # @return [Boolean]
       def primitive?(value)
         left.primitive?(value) || right.primitive?(value)
       end
 
+      # @param [Object] value
+      # @return [Boolean]
       def valid?(value)
         left.valid?(value) || right.valid?(value)
       end

data/lib/dry/types/version.rb

@@ -1,5 +1,5 @@
 module Dry
   module Types
-    VERSION = '0.9.2'.freeze
+    VERSION = '0.9.3'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-types
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
 - Piotr Solnica
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-13 00:00:00.000000000 Z
+date: 2016-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -31,6 +31,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +41,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: dry-container
   requirement: !ruby/object:Gem::Requirement
@@ -176,6 +182,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.5
 description: Type system for Ruby supporting coercions, constraints and complex types
   like structs, value objects, enums etc.
 email:
@@ -187,6 +207,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - LICENSE