nrser 0.0.24 → 0.0.25

data/lib/nrser/types/attrs.rb

@@ -36,43 +36,97 @@ module NRSER::Types
     def attrs attrs, options = {}
       Attrs.new attrs, **options
     end
-
+    
+    
+    # @overload length exact, options = {}
+    #   Get a length attribute type that specifies an `exact` value.
+    #   
+    #   @example
+    #     only_type = NRSER::Types.length 1
+    #     
+    #     only_type.test []
+    #     # => false
+    #     
+    #     only_type.test [:x]
+    #     # => true
+    #     
+    #     only_type.test [:x, :y]
+    #     # => false
+    #   
+    #   @param [Integer] exact
+    #     Exact non-negative integer that the length must be to satisfy the
+    #     type created.
+    #   
+    #   @param [Hash] options
+    #     Options hash passed up to {NRSER::Types::Type} constructor.
+    #   
+    #   @return [NRSER::Types::Attrs]
+    #     Type satisfied by a `#length` attribute that is exactly `exact`.
+    # 
+    # 
+    # @overload length bounds, options = {}
+    #   Get a length attribute type satisfied by values within a `:min` and 
+    #   `:max` (inclusive).
+    #   
+    #   @example
+    #     three_to_five = NRSER::Types.length( {min: 3, max: 5}, name: '3-5' )
+    #     three_to_five.test [1, 2]               # => false
+    #     three_to_five.test [1, 2, 3]            # => true
+    #     three_to_five.test [1, 2, 3, 4]         # => true
+    #     three_to_five.test [1, 2, 3, 4, 5]      # => true
+    #     three_to_five.test [1, 2, 3, 4, 5, 6]   # => false
+    # 
+    #   @param [Hash] bounds
+    #   
+    #   @option bounds [Integer] :min
+    #     An optional minimum value that the `#length` should not be less than.
+    #   
+    #   @option bounds [Integer] :max
+    #     An optional maximum value that the `#length` should not be more than.
+    #   
+    #   @option bounds [Integer] :length
+    #     An optional value for both the minimum and maximum.
+    #   
+    #   @param [Hash] options
+    #     Options hash passed up to {NRSER::Types::Type} constructor.
+    #   
+    #   @return [NRSER::Types::Attrs]
+    #     Type satisfied by a `#length` attribute between the `:min` and `:max`
+    #     (inclusive).
+    # 
     def length *args
       bounds = {}
-      options = {}
+      options = if args[1].is_a?( Hash ) then args[1] else {} end
       
-      case args.length
-      when 1
-        case args[0]
-        when ::Integer
-          bounds[:min] = bounds[:max] = non_neg_int.check(args[0])
-          
-        when ::Hash
-          options = NRSER.symbolize_keys args[0]
-          
-          bounds[:min] = options.delete :min
-          bounds[:max] = options.delete :max
-          
-          if length = options.delete(:length)
-            bounds[:min] = length
-            bounds[:max] = length
-          end
-          
-        else        
-          raise ArgumentError, <<-END.squish
-            arg must be positive integer or option hash, found:
-            #{ args[0].inspect } of type #{ args[0].class }
-          END
+      case args[0]
+      when ::Integer
+        # It's just a length
+        bounds[:min] = bounds[:max] = non_neg_int.check args[0]
+        
+      when ::Hash
+        # It's keyword args
+        kwds = NRSER.symbolize_keys args[0]
+        
+        # Pull any :min and :max in the keywords
+        bounds[:min] = kwds.delete :min
+        bounds[:max] = kwds.delete :max
+        
+        # But override with :length if we got it
+        if length = kwds.delete(:length)
+          bounds[:min] = length
+          bounds[:max] = length
         end
         
-      when 2
-        bounds[:min] = bounds[:max] = non_neg_int.check(args[0])
-        options = args[1]
+        # (Reverse) merge anything else into the options (options hash values
+        # take precedence)
+        options = kwds.merge options
         
-      else
+      else        
         raise ArgumentError, <<-END.squish
-          must provided 1 or 2 args.
+          arg must be positive integer or option hash, found:
+          #{ args[0].inspect } of type #{ args[0].class }
         END
+        
       end
       
       bounded_type = bounded bounds
@@ -90,7 +144,6 @@ module NRSER::Types
       attrs({ length: length_type }, options)
     end # #length
     
-    
   end # class << self (Eigenclass)
   
 end # NRSER::Types

data/lib/nrser/types/combinators.rb

@@ -8,30 +8,32 @@ module NRSER::Types
   class Combinator < NRSER::Types::Type
     attr_reader :types
     
+    
     def initialize *types, **options
       super **options
       @types = types.map {|type| NRSER::Types.make type}
     end
     
+    
     def default_name
-      @name || (
-        "#{ self.class.short_name }<" + 
-        @types.map {|type| type.name }.join(',') + 
-        ">"
-      )
+      "#{ self.class.short_name }<" + 
+      @types.map {|type| type.name }.join(',') + 
+      ">"
     end
     
+    
     # a combinator may attempt to parse from a string if any of it's types
     # can do so
     def has_from_s?
       @types.any? {|type| type.has_from_s?}
     end
     
+    
     # a combinator iterates through each of it's types, trying the
     # conversion and seeing if the result satisfies the combinator type
     # itself. the first such value found is returned.
     def from_s s
-      @types.each {|type|
+      @types.each { |type|
         if type.respond_to? :from_s
           begin
             return check type.from_s(s)
@@ -45,6 +47,52 @@ module NRSER::Types
         "none of combinator #{ self.to_s } types could convert #{ s.inspect }"
     end
     
+    
+    # Overridden to delegate functionality to the combined types:
+    # 
+    # A combinator may attempt to parse from a string if any of it's types
+    # can do so.
+    # 
+    # @return [Boolean]
+    # 
+    def has_from_s?
+      @types.any? {|type| type.has_from_s?}
+    end # has_from_s
+    
+    
+    # Overridden to delegate functionality to the combined types:
+    # 
+    # A combinator can convert a value to data if *any* of it's types can.
+    # 
+    # @return [Boolean]
+    # 
+    def has_to_data?
+      @types.any? { |type| type.has_to_data? }
+    end # #has_to_data
+    
+    
+    # Overridden to delegate functionality to the combined types:
+    # 
+    # The first of the combined types that responds to `#to_data` is used to
+    # dump the value.
+    # 
+    # @param [Object] value
+    #   Value of this type (though it is *not* checked).
+    # 
+    # @return [Object]
+    #   The data representation of the value.
+    # 
+    def to_data value
+      @types.each { |type|
+        if type.respond_to? :to_data
+          return type.to_data value
+        end
+      }
+      
+      raise NoMethodError, "#to_data not defined"
+    end # #to_data
+    
+    
     def == other
       equal?(other) || (
         other.class == self.class && other.types == @types

data/lib/nrser/types/paths.rb

@@ -34,7 +34,8 @@ module NRSER::Types
   PATHNAME = is_a \
     Pathname,
     name: 'PathnameType',
-    from_s: ->(string) { Pathname.new string }
+    from_s: ->(string) { Pathname.new string },
+    to_data: :to_s
   
   
   # A type satisfied by a {Pathname} instance that's not empty (meaning it's
@@ -53,7 +54,7 @@ module NRSER::Types
   # 
   class << self
     
-    def pathname **options
+    def pathname to_data: :to_s, **options
       if options.empty?
         PATHNAME
       else
@@ -61,11 +62,14 @@ module NRSER::Types
           Pathname,
           name: 'PathnameType',
           from_s: ->(string) { Pathname.new string },
+          to_data: to_data,
           **options
       end
     end
     
+    # A path is a non-empty {String} or {Pathname}.
     # 
+    # @param **options see NRSER::Types::Type#initialize
     # 
     # @return [NRSER::Types::Type]
     # 
@@ -77,6 +81,62 @@ module NRSER::Types
       end
     end # #path
     
+    
+    # An absolute {#path}.
+    # 
+    # @param **options see NRSER::Types::Type#initialize
+    # 
+    def abs_path name: 'AbsPath', **options
+      intersection \
+        path,
+        where { |path| File.absolute? path },
+        name: name,
+        **options
+    end
+    
+    
+    # A {NRSER::Types.path} that is a directory.
+    # 
+    # @param [Hash] **options
+    #   Construction options passed to {NRSER::Types::Type#initialize}.
+    # 
+    # @return [NRSER::Types::Type]
+    # 
+    def dir_path name: 'DirPath', **options
+      intersection \
+        path,
+        where { |path| File.directory? path },
+        name: name,
+        **options
+    end # #dir_path
+    
+    
+    # Absolute {.path} to a directory (both an {.abs_path} and an {.dir_path}).
+    # 
+    # @param [type] name:
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def abs_dir_path name: 'AbsDirPath', **options
+      intersection \
+        abs_path,
+        dir_path,
+        name: name,
+        **options
+    end # #abs_dir_path
+    
+    
+    
+    def file_path name: 'FilePath', **options
+      intersection \
+        path,
+        where { |path| File.file? path },
+        name: name,
+        **options
+    end
+    
   end # class << self (Eigenclass)
   
 end # module NRSER::Types

data/lib/nrser/types/type.rb

@@ -1,6 +1,13 @@
+# Refinements
+# =======================================================================
+
 require 'nrser/refinements'
 using NRSER
 
+
+# Definitions
+# =======================================================================
+
 module NRSER::Types
   class Type
     def self.short_name
@@ -25,9 +32,25 @@ module NRSER::Types
     #   value that doesn't satisfy will result in a {TypeError} being raised
     #   by {#from_s}.
     # 
-    def initialize name: nil, from_s: nil
+    # @param [nil | #call | #to_proc] to_data:
+    #   
+    # 
+    def initialize name: nil, from_s: nil, to_data: nil
       @name = name
       @from_s = from_s
+      
+      @to_data = if to_data.nil?
+        nil
+      elsif to_data.respond_to?( :call )
+        to_data
+      elsif to_data.respond_to?( :to_proc )
+        to_data.to_proc
+      else
+        raise TypeError.squished <<-END
+          `to_data:` keyword arg must be `nil`, respond to `:call` or respond
+          to `:to_proc`; found #{ to_data.inspect }
+        END
+      end
     end # #initialize
     
     
@@ -43,6 +66,7 @@ module NRSER::Types
       raise NotImplementedError
     end
     
+    
     def check value, &make_fail_message
       # success case
       return value if test value
@@ -58,14 +82,67 @@ module NRSER::Types
       raise TypeError.new msg
     end
     
+    
+    # Overridden to customize behavior for the {#from_s} and {#to_data} 
+    # methods - those methods are always defined, but we have {#respond_to?}
+    # return `false` if they lack the underlying instance variables needed
+    # to execute.
+    # 
+    # @example
+    #   t1 = t.where { |value| true }
+    #   t1.respond_to? :from_s
+    #   # => false
+    #   
+    #   t2 = t.where( from_s: ->(s){ s.split ',' } ) { |value| true }
+    #   t2.respond_to? :from_s
+    #   # => true
+    # 
+    # @param [Symbol | String] name
+    #   Method name to ask about.
+    # 
+    # @param [Boolean] include_all
+    #   IDK, part of Ruby API that is passed up to `super`.
+    # 
+    # @return [Boolean]
+    # 
     def respond_to? name, include_all = false
       if name == :from_s || name == 'from_s'
         has_from_s?
+      elsif name == :to_data || name == 'to_data'
+        has_to_data?
       else
         super name, include_all
       end
-    end
+    end # #respond_to?
     
+    
+    # Load a value of this type from a string representation by passing `s`
+    # to the {@from_s} {Proc}.
+    # 
+    # Checks the value {@from_s} returns with {#check} before returning it, so
+    # you know it satisfies this type.
+    # 
+    # @param [String] s
+    #   String representation.
+    # 
+    # @return [Object]
+    #   Value that has passed {#check}.
+    # 
+    # @raise [NoMethodError]
+    #   If this type doesn't know how to load values from strings.
+    #   
+    #   In basic types this happens when {NRSER::Types::Type#initialize} was 
+    #   not provided a `from_s:` {Proc} argument.
+    #   
+    #   {NRSER::Types::Type} subclasses may override {#from_s} entirely,
+    #   divorcing it from the `from_s:` constructor argument and internal
+    #   {@from_s} instance variable (which is why {@from_s} is not publicly
+    #   exposed - it should not be assumed to dictate {#from_s} behavior 
+    #   in general).
+    # 
+    # @raise [TypeError]
+    #   If the value loaded does not pass {#check}.
+    # 
     def from_s s
       if @from_s.nil?
         raise NoMethodError, "#from_s not defined"
@@ -74,12 +151,55 @@ module NRSER::Types
       check @from_s.call( s )
     end
     
+    
+    # Test if the type knows how to load values from strings.
+    # 
+    # If this method returns `true`, then we expect {#from_s} to succeed.
+    # 
+    # @return [Boolean]
+    # 
     def has_from_s?
       ! @from_s.nil?
     end
     
+    
+    # Test if the type has custom information about how to convert it's values
+    # into "data" - structures and values suitable for transportation and 
+    # storage (JSON, etc.).
+    # 
+    # If this method returns `true` then {#to_data} should succeed.
+    # 
+    # @return [Boolean]
+    # 
+    def has_to_data?
+      ! @to_data.nil?
+    end # #has_to_data?
+    
+    
+    # Dumps a value of this type to "data" - structures and values suitable
+    # for transport and storage, such as dumping to JSON or YAML, etc.
+    # 
+    # @param [Object] value
+    #   Value of this type (though it is *not* checked).
+    # 
+    # @return [Object]
+    #   The data representation of the value.
+    # 
+    def to_data value
+      if @from_s.nil?
+        raise NoMethodError, "#to_data not defined"
+      end
+      
+      @to_data.call value
+    end # #to_data
+    
+    
+    # @return [String]
+    #   a brief string description of the type.
+    # 
     def to_s
       "`Type: #{ name }`"
     end
+    
   end # Type
 end # NRSER::Types

data/lib/nrser/types.rb

@@ -41,6 +41,8 @@ using NRSER
 
 # Stuff to help you define, test, check and match types in Ruby.
 # 
+# {include:file:lib/nrser/types/README.md}
+# 
 module NRSER::Types
   
   # Make a {NRSER::Types::Type} from a value.

data/lib/nrser/version.rb

@@ -1,5 +1,5 @@
 module NRSER
-  VERSION = "0.0.24"
+  VERSION = "0.0.25"
   
   module Version
     

data/lib/nrser.rb

@@ -1,4 +1,8 @@
-module NRSER; end
+require 'pathname'
+
+module NRSER
+  ROOT = ( Pathname.new(__FILE__).dirname / '..' ).expand_path
+end
 
 require_relative './nrser/version'
 require_relative './nrser/no_arg'

data/spec/nrser/hash/bury_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe "NRSER.bury!" do
+  subject { NRSER.method :bury! }
+  
+  it do    
+    expect(
+      {}.tap { |hash|
+        subject.call( hash, [:a, :b, :c], 1 )
+      }
+    ).to eq(
+      { a: { b: { c: 1 } } }
+    )
+  end
+  
+  context "string key path" do
+    context ":parsed_key_type option omitted" do
+      it "creates hashes and sets string keys" do
+        expect(
+          {}.tap { |hash|
+            subject.call( hash, 'a.b.c', 1 )
+          }
+        ).to eq(
+          { 'a' => { 'b' => { 'c' => 1 } } }
+        )
+      end
+    end # :key_type option omitted
+
+  end # string key path
+  
+end # NRSER.bury

data/spec/nrser/hash/guess_name_type_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe "NRSER.guess_name_type" do
+  subject { NRSER.method :guess_name_type }
+  
+  it "can't guess about an empty hash" do
+    expect( subject.call( {} ) ).to be nil
+  end
+  
+  it "guesses String when all keys are strings" do
+    expect( subject.call( {'a' => 1, 'b' => 2} ) ).to be String
+  end
+  
+  it "guesses Symbol when all keys are symbols" do
+    expect( subject.call( {a: 1, b: 2} ) ).to be Symbol
+  end
+  
+  it "guesses String when there are string keys but no symbols" do
+    expect(
+      subject.call({
+        'a' => 1,
+        [:b] => 2,
+        3 => 'three',
+      })
+    ).to be String
+  end
+  
+  it "guesses Symbol when there are symbol keys but no strings" do
+    expect(
+      subject.call({
+        a: 1,
+        ['b'] => 2,
+        3 => 'three',
+      })
+    ).to be Symbol
+  end
+  
+  it "can't guess when there are string and symbol keys" do
+    expect(
+      subject.call({
+        a: 1,
+        'b' => 2,
+      })
+    ).to be nil
+  end
+  
+end # NRSER.guess_name_type

data/spec/nrser/types/attrs_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe "NRSER::Types.length" do
+  subject { NRSER::Types.method :length }
+  
+  context "zero length" do
+    kwds = {
+      accepts: [ '', [], {}, ],
+      rejects: [ 'x', [1], {x: 1} ],
+    }
+    
+    # Three ways to cut it:
+    it_behaves_like 'Type maker method', args: [ length: 0 ], **kwds
+    it_behaves_like 'Type maker method', args: [ 0 ], **kwds
+    it_behaves_like 'Type maker method', args: [ min: 0, max: 0], **kwds
+      
+  end # zero length
+  
+  it_behaves_like 'Type maker method',
+    args:     [ {min: 3, max: 5}, name: '3to5Type' ],
+    
+    accepts: [
+      [1, 2, 3],
+      [1, 2, 3, 4],
+      [1, 2, 3, 4, 5],
+    ],
+    
+    rejects: [
+      [1, 2],
+      [1, 2, 3, 4, 5, 6]
+    ],
+    
+    and_is_expected: {
+      to: {
+        have_attributes: {
+          name: '3to5Type',
+        }
+      }
+    }
+    
+end # NRSER::Types.length