nrser 0.3.9 → 0.3.10

data/lib/nrser/types/shape.rb

@@ -2,79 +2,150 @@
 # encoding: UTF-8
 
 
+# Requirements
+# ========================================================================
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+require_relative './type'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
 # Definitions
 # =======================================================================
 
-module NRSER::Types
+# Create a {Shape} type that parameterizes {#pairs} of object keys and {Type}
+# values.
+# 
+# Members of the type are values `v` for which for all keys `k` and 
+# paired value types `t_k` `v[k]` is a member of `t_k`:
+# 
+#     shape.pairs.all? { |k, t_k| t_k.test? v[k] }
+# 
+# @note
+#   Construct shape types using the {.Shape} factory.
+# 
+class Shape < Type  
   
-  class Shape < Type
-    
-    
-    # Attributes
-    # ========================================================================
-    
-    # TODO document `pairs` attribute.
-    # 
-    # @return [Hash]
-    #     
-    attr_reader :pairs
-    
-    
-    # Constructor
-    # ======================================================================
-    
-    # Instantiate a new `NRSER::Types::Shape`.
-    def initialize pairs, **options
-      super **options
-      @pairs = pairs.map { |k, v|
-        [k, NRSER::Types.make( v )]
-      }.to_h.freeze
-    end # #initialize
-    
-    
-    # Instance Methods
-    # ======================================================================
-    
-    def test? value
-      begin
-        @pairs.all? { |k, v|
-          v === value[k]
-        }
-      rescue
-        false
-      end
+  # Attributes
+  # ========================================================================
+  
+  # TODO document `pairs` attribute.
+  # 
+  # @return [Hash]
+  #     
+  attr_reader :pairs
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `NRSER::Types::Shape`.
+  def initialize pairs, **options
+    super **options
+    @pairs = pairs.map { |k, v|
+      [k, NRSER::Types.make( v )]
+    }.to_h.freeze
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  def test? value
+    begin
+      @pairs.all? { |k, v| v === value[k] }
+    rescue
+      false
     end
-    
-    def explain
-      inner = @pairs.map { |k, v|
-        "[#{ k.inspect }]→#{ v.name }"
-      }.join( ", " )
-      
-      if @pairs.count == 1
-        inner
+  end
+
+
+  # @!group Display Instance Methods
+  # --------------------------------------------------------------------------
+  
+  def string_format pre:, post:, method:, spaces: true
+    space = spaces ? ' ' : ''
+
+    inner = @pairs.map { |k, v|
+      key_part = if k.is_a? Symbol
+        "#{ k }:#{ space }"
       else
-        '(' + inner + ')'
+        "#{ k.inspect }#{ space }=>#{ space }"
       end
-    end
-    
-    def has_from_data?
-      pairs.values.all? { |type| type.has_from_data? }
-    end
-    
-    
-    def custom_from_data data
-      pairs.map { |key, type|
-        [ key, type.from_data( data[key] ) ]
-      }.to_h
-    end
-    
-  end # class Shape
+
+      key_part + v.public_send( method )
+    }
+
+    pre + inner.join( ",#{ space }" ) + post
+  end
+
+
+  def default_symbolic
+    string_format pre: '{', post: '}', method: :symbolic
+  end
+
+
+  def explain
+    string_format pre: 'Shape<', post: '>', method: :explain
+  end
+
+  # @!endgroup Display Instance Methods # ************************************
+  
+
+  def has_from_data?
+    pairs.values.all? { |type| type.has_from_data? }
+  end
   
   
-  def_factory(
-    :shape,
-  ) do |pairs, **options|
-    Shape.new pairs, **options
+  def custom_from_data data
+    pairs.map { |key, type|
+      [ key, type.from_data( data[key] ) ]
+    }.to_h
   end
   
-end # module NRSER::Types
+end # class Shape
+
+
+# @!group Shape Type Factories
+# ----------------------------------------------------------------------------
+
+#@!method self.Shape pairs, **options
+#   Create a {Shape} type that parameterizes `pairs` of object keys and {Type}
+#   values.
+#   
+#   Members of the type are values `v` for which for all keys `k` and 
+#   paired value types `t_k` `v[k]` is a member of `t_k`:
+#   
+#       shape.pairs.all? { |k, t_k| t_k.test? v[k] }
+#   
+#   @param [Hash<Object, TYPE>] pairs
+#     See {Shape#initialize}.
+# 
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Shape]
+#   
+def_type          :Shape,
+  parameterize:   true,
+&->( pairs, **options ) do
+  Shape.new pairs, **options
+end # .Shape
+
+# @!endgroup Shape Type Factories # ******************************************
+
+
+# /Namespace
+# ========================================================================
+
+end # module Types
+end # module NRSER
+

data/lib/nrser/types/strings.rb

@@ -1,72 +1,198 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+
+# Requirements
+# ========================================================================
+
+# Project / Package
+# ------------------------------------------------------------------------
+
 require_relative './is'
 require_relative './is_a'
-require_relative './attrs'
+require_relative './attributes'
 require_relative './not'
 
   
-module NRSER::Types
-  
-  # @!group Type Factory Functions
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
+# Definitions
+# ========================================================================
   
-  def_factory(
-    :String,
-    aliases: [ :str, :string ],
-  ) do |length: nil, encoding: nil, **options|
-    if [length, encoding].all?( &:nil? )
-      IsA.new ::String, from_s: ->(s) { s }, **options
-      
+# @!group String Type Factories
+# ----------------------------------------------------------------------------
+
+#@!method self.String length: nil, encoding: nil, **options
+#   Get a {Type} whose members {.IsA} {::String}, along with some other optional
+#   common attribute checks ({::String#length} and {::String#encoding}).
+#   
+#   If `encoding:` is specified and no `from_s:` is provided, will add a
+#   {Type#form_s} that attempts to transcode strings that are not already in the
+#   target encoding (via a simple `String#encode( encoding )`).
+#   
+#   If you for some reason don't want {Type#from_s} to try to transcode, just 
+#   provide a `from_s:` {Proc} that doesn't do it - `->( s ) { s }` to just
+#   use whatever tha cat drags in.
+#   
+#   If `from_s` is otherwise not provided, adds the obvious identity function.
+#   
+#   @param [nil | Integer | {min: Integer?, max: Integer?, length: Integer?}]
+#     length
+#     Optionally admit only strings of a specified length. This does not affect
+#     any default `from_s` - loaded strings must already be the specific length.
+#   
+#   @param [String] encoding
+#     Optional {::String#encoding} check. See notes above regarding default
+#     `from_s` that may be added.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :String,
+  aliases:      [ :str ],
+&->( length: nil, encoding: nil, **options ) do
+
+  if [ length, encoding ].all?( &:nil? )
+    # Give 'er the obvious `#from_s` if she don't already have one
+    options[:from_s] ||= ->( s ) { s }
+
+    IsA.new ::String, **options
+    
+  else
+    types = [ IsA.new( ::String ) ]
+    types << self.Length( length ) if length
+
+    if encoding
+      # If we didn't get a `from_s`, provide one that will try to transcode to
+      # `encoding` (unless it's already there)
+      options[:from_s] ||= ->( string ) {
+        if string.encoding == encoding
+          string
+        else
+          string.encode encoding
+        end
+      }
+
+      types << self.Attributes( encoding: encoding )
+
     else
-      types = [str]
-      types << self.length( length ) if length
-      types << attrs( encoding: encoding ) if encoding
-      
-      intersection *types, **options
+      # We don't need to handle encoding, so set the obvious `#from_s` if 
+      # one was not provided
+      options[:from_s] ||= ->( s ) { s }
+
     end
-  end # String
-  
-  
-  # Get a {Type} only satisfied by empty strings.
-  # 
-  # @param [String] name: (default 'EmptyString')
-  # 
- def_factory(
-   :EmptyString,
-   aliases: [ :empty_str, :empty_string ],
-  ) do |name: 'EmptyString', **options|
-    str length: 0, name: name, **options
-  end
-  
-  
- def_factory(
-   :NonEmptyString,
-   aliases: [ :non_empty_str, :non_empty_string ],
-  ) do |name: 'NonEmptyString', **options|
-    str length: {min: 1}, name: name, **options
-  end
-  
-  
- def_factory(
-   :Character,
-   aliases: [ :char, :character ],
-  ) do |name: 'Character', **options|
-    str length: 1, name: name, **options
+    
+    self.Intersection *types, **options
   end
-  
-  
-  # A type satisfied by UTF-8 encoded strings.
-  # 
-  # @param [String] name: (default 'UTF8String')
-  # 
-  def_factory :uft_8, aliases: [:utf8] do |name: 'UTF8String', **options|
-    str encoding: Encoding::UTF_8, name: name, **options
-  end
-  
-  
-  def_factory(
-    :utf_8_char,
-    aliases: [:utf8_char]
-  ) do |name: 'UTF8Character', **options|
-    str length: 1, encoding: Encoding::UTF_8, name: name, **options
-  end
-  
-end # NRSER::Types
+
+end # .String
+
+
+#@!method self.EmptyString encoding: nil, **options
+#   Get a {Type} only satisfied by empty strings.
+#   
+#   @param encoding (see .String)
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :EmptyString,
+  aliases:      [ :empty_str ],
+&->( encoding: nil, **options ) do
+  self.String **options, length: 0, encoding: encoding
+end # .EmptyString
+
+
+#@!method self.NonEmptyString encoding: nil, **options
+#   {.String} of length `1` or more.
+#   
+#   @param encoding (see .String)
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :NonEmptyString,
+  aliases:      [ :non_empty_str ],
+&->( encoding: nil, **options ) do
+  self.String  **options, length: {min: 1}, encoding: encoding
+end # .NonEmptyString
+
+
+#@!method self.Character encoding: nil, **options
+#   {.String} of length `1` (Ruby lacks a character class).
+#   
+#   @param encoding (see .String)
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Character,
+  aliases:      [ :char ],
+&->( encoding: nil, **options ) do
+  self.String **options, length: 1, encoding: encoding
+end # .Character
+
+
+#@!method self.UTF8String length: nil, **options
+#   A type satisfied by UTF-8 encoded {.String}.
+#   
+#   @param length (see .String)
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :UTF8String,
+  # NOTE        "UTF8String".underscore -> "utf8_string"
+  aliases:      [ :utf_8_string,
+                  :utf8,
+                  :utf_8,
+                  :utf8_str,
+                  :utf_8_str ],
+&->( length: nil, **options ) do
+  self.String **options, length: length, encoding: Encoding::UTF_8
+end # .UTF8String
+
+
+#@!method self.UTF8Character **options
+#   A type satisfied by UTF-8 encoded {.Character}.
+#   
+#   @param encoding (see .String)
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :UTF8Character,
+  # NOTE        "UTF8Character".underscore -> "utf8_character"
+  aliases:      [ :utf_8_character,
+                  :utf8_char,
+                  :utf_8_char ],
+&->( **options ) do
+  self.Character **options, encoding: Encoding::UTF_8
+end # .UTF8Character
+
+
+# @!endgroup String Type Factories # *****************************************
+
+
+# /Namespace
+# ========================================================================
+
+end # module Types
+end # module NRSER