nrser 0.3.9 → 0.3.10

data/lib/nrser/labs/i8/struct.rb

@@ -0,0 +1,167 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/errors/argument_error'
+require 'nrser/labs/i8'
+
+require_relative './struct/hash'
+require_relative './struct/vector'
+
+
+# Refinements
+# ========================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+# Namespace
+# ========================================================================
+
+module  I8
+  
+
+# Definitions
+# ========================================================================
+
+# `I8::Struct` is an immutable rendition of the Ruby standard lib `::Struct`
+# using the {NRSER::Props} system.
+# 
+# It's intended to help make it quick and easy to create little immutable
+# propertied objects, with all the type-checking and serialization stuff
+# that comes with {NRSER::Props}.
+# 
+# `Struct` itself is a module with a {.new} method that creates new subclasses
+# of either {I8::Struct::Hash} or {I8::Struct::Vector}, which themselves 
+# are respective subclasses of {I8::Hash} and {I8::Vector}, and include
+# {NRSER::Props::Immutable::Hash} and {NRSER::Props::Immutable::Vector}.
+# 
+# ### Identifying Classes Built by `I8::Struct` 
+# 
+# Both {I8::Struct::Hash} and {I8::Struct::Vector} also include `I8::Struct`
+# itself for the convenience of shit like:
+# 
+#     Point = I8::Struct.new x: t.int, y: t.int
+#     
+#     Point.included_modules.include? I8::Struct
+#     #  => true
+#     
+#     p = Point.new x: 1, y: 2
+#     p.is_a? I8::Struct
+#     # => true
+# 
+# `I8::Struct` has only class (static) methods, so no functionality is 
+# actually added from `include I8::Struct`.
+# 
+# ### Gotchas
+# 
+# The code below *doesn't* work how you might want or expect it:
+# 
+#     Point = I8::Struct.new x: t.int, y: t.int
+#     Point.is_a? I8::Struct
+#     # => false
+# 
+# Opposed to how {Class} works:
+# 
+#     C = Class.new
+#     C.is_a? Class
+#     # => true
+# 
+# However, this *is* the same as how the stdlib's [::Struct][] behaves:
+# 
+#     S = ::Struct.new :x
+#     S.is_a? ::Struct
+#     # => false
+# 
+# [::Struct]: https://ruby-doc.org/core/Struct.html
+# 
+# @example One-Liner
+#   Person = I8::Struct.new name: t.non_empty_str, age: t.non_neg_int
+#   nrser = Person.new name: "Neil", age: 34
+# 
+# @example Extend a `I8::Struct` to add methods
+#   class Rectangle \
+#     < I8::Struct.new( width: t.non_neg_int, length: t.non_neg_int )
+#     
+#     def area
+#       width * length
+#     end
+#     
+#   end # class Rectangle
+# 
+module Struct
+  
+  # Check args that were passed to {.new}.
+  # 
+  # @!visibility private
+  # 
+  # @param vector_prop_defs (see .new)
+  # @param hash_prop_defs   (see .new)
+  # 
+  def self.check_new_args! vector_prop_defs, hash_prop_defs
+    
+    unless  (vector_prop_defs.empty? && !hash_prop_defs.empty?) ||
+            (!vector_prop_defs.empty? && hash_prop_defs.empty?)
+      
+      raise NRSER::ArgumentError.new \
+        "Exactly one of *args or **kwds must be empty",
+        
+        args: vector_prop_defs,
+        
+        kwds: hash_prop_defs,
+        
+        details: -> {%{
+          {I8::Struct.new} proxies to either
+          
+          1.  {I8::Struct::Vector.new}
+          2.  {I8::Struct::Hash.new}
+          
+          depending on *where* the property definitions are passed:
+          
+          1.  Positionally in `*args` -> {I8::Struct::Vector.new}
+          2.  By name in `**kwds` -> {I8::Struct::Hash.new}
+          
+          Examples:
+          
+          1.  Create a Point struct backed by an {I8::Vector}:
+              
+                  Point = I8::Struct.new [x: t.int], [y: t.int]
+              
+          2.  Create a Point struct backed by an {I8::Hash}:
+              
+                  Point = I8::Struct.new x: t.int, y: t.int
+          
+        }}
+      
+    end # unless vector_prop_defs.empty? XOR hash_prop_defs.empty?
+    
+  end # .check_new_args!
+  
+  private_class_method :check_new_args!
+  
+  
+  def self.new *vector_prop_defs, **hash_prop_defs, &class_body
+    check_new_args! vector_prop_defs, hash_prop_defs
+    
+    if !vector_prop_defs.empty?
+      raise NotImplementedError.new "I8::Struct::Vector is TODO, sorry"
+      # I8::Struct::Vector.new *vector_prop_defs, &class_body
+    else
+      I8::Struct::Hash.new **hash_prop_defs, &class_body
+    end
+  end
+  
+  
+end # module Struct
+
+
+# /Namespace
+# ========================================================================
+
+end # module I8
+

data/lib/nrser/labs/i8/struct/hash.rb

@@ -0,0 +1,140 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'nrser/errors/argument_error'
+require 'nrser/props/immutable/hash'
+
+
+# Refinements
+# ========================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+# Namespace
+# ========================================================================
+
+module  I8
+module  Struct
+  
+
+# Definitions
+# ========================================================================
+
+# Base class for {I8::Hash}-based "propertied" ({NRSER::Props}) structs 
+# created by {I8::Struct.new}.
+# 
+# @see I8::Struct
+# @see NRSER::Props
+# @see NRSER::Props::Immutable::Hash
+# 
+class Hash < I8::Hash
+
+  include I8::Struct
+  include NRSER::Props::Immutable::Hash
+
+  # This method does two totally different things depending on what `self`
+  # is:
+  # 
+  # 1.  If `self` is {I8::Struct::Hash}, we want to build a new struct class.
+  #     
+  # 2.  Otherwise, we want to defer up to `super` to create a new instance
+  #     of `self`.
+  # 
+  # @overload self.new **prop_defs, &class_body
+  #   When `self` **is** {I8::Struct::Hash}, the method builds a new 
+  #   subclass, along the lines of how {I8::Struct.new} and `::Struct.new`
+  #   work.
+  #    
+  #   @example
+  #     Point = I8::Struct::Hash.new x: t.int, y: t.int
+  #     # => Point
+  #   
+  #   @param [Hash<Symbol, (NRSER::Types::Type | Hash<Symbol, Object>)>] prop_defs
+  #     Map of property names to the value(s) needed to create them.
+  #     
+  #     `prop_defs` values can each be:
+  #     
+  #     1.  {NRSER::Types::Type} - used as the {NRSER::Props::Prop#type}, with
+  #         all the {NRSER::Props::Prop}'s other values left as defaults.
+  #         
+  #     2.  {Hash<Symbol, Object>} - full prop configuration, passed in to
+  #         {NRSER::Props::Metadata#prop}.
+  #   
+  #   @param [Proc?] class_body
+  #     Optional block to evaluate as the new class's body.
+  #   
+  #   @return [Class<I8::Struct::Hash>]
+  #     New structure class.
+  # 
+  # @overload self.new *args, **kwds, &block
+  #   When `self` **is not** {I8::Struct::Hash}, this method simply forwards
+  #   all parameters up to it's super method, which will create a new 
+  #   instance as usual.
+  #   
+  #   @example
+  #     Point < I8::Struct::Hash
+  #     # => true
+  #     
+  #     Point.new x: 1, y: 2 # Passes through to super method to construct
+  #     # => Point[:y => 2, :x => 1]
+  #   
+  #   @return [I8::Struct::Hash]
+  #     New instance.
+  # 
+  def self.new *args, **kwds, &block
+    # Are we {I8::Struct::Hash}? (See method doc).
+    if self == I8::Struct::Hash
+      # Yes, we are. Time to build a new struct class.
+      
+      # Make sure we weren't given an positional `args`.
+      unless args.empty?
+        raise NRSER::ArgumentError.new \
+          "Can not supply positional args when building new",
+          "{I8::Struct::Hash}",
+          args: args,
+          kwds: kwds
+      end
+
+      # Create the new subclass
+      Class.new( I8::Struct::Hash ) do
+        kwds.each do |name, value|
+          prop_kwds = t.match value,
+            t.type, ->( type ) {{ type: type }},
+            t.hash_, value
+          
+          prop name, **prop_kwds
+        end
+        
+        class_exec &block if block
+      end
+
+    else
+      # No, we are a built struct. Defer up to `super` to create an instance.
+      
+      # NOTE  Weirdness ahead. See NOTE in {I8::Struct::Vector.new}
+      if kwds.empty?
+        super( *args, &block )
+      else
+        super( *args, **kwds, &block )
+      end
+
+    end
+  end # .new
+
+end # class Hash
+
+
+# /Namespace
+# ========================================================================
+
+end # module  Struct
+end # module  I8
+

data/lib/nrser/labs/i8/struct/vector.rb

@@ -0,0 +1,149 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'nrser/errors/argument_error'
+require 'nrser/props/immutable/vector'
+
+
+# Refinements
+# ========================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+# Namespace
+# ========================================================================
+
+module  I8
+module  Struct
+  
+
+# Definitions
+# ========================================================================
+
+# Base class for {I8::Vector}-based "propertied" ({NRSER::Props}) structs 
+# created by {I8::Struct.new}.
+# 
+# @see I8::Struct
+# @see NRSER::Props
+# @see NRSER::Props::Immutable::Vector
+# 
+class Vector < I8::Vector
+  include I8::Struct
+  include NRSER::Props::Immutable::Vector
+  
+  # Check out {I8::Struct::Hash} for a general idea of how this method works,
+  # I don't want to duplicate the explanation.
+  # 
+  # @overload self.new *prop_defs, &class_body
+  #   Create a new struct class.
+  #   
+  #   @example Using array-wrapping for prop defs
+  #     Point = I8::Struct::Vector.new [x: t.int], [y: t.int]
+  #     # => Point
+  # 
+  #   @example Using hashes for prop defs
+  #     Point = I8::Struct::Vector.new( {x: t.int}, {y: t.int} )
+  #     # => Point
+  # 
+  # @example Providing additional prop options
+  #     Point = I8::Struct::Vector.new \
+  #       [x: {type: t.int, default: 0}],
+  #       [y: {type: t.int, default: 0}]
+  #     # => Point
+  #   
+  #   @param [Array] prop_defs
+  #     Each entry must be a pair; the first entry must be the name as a
+  #     symbol, the second is either the prop's type or a hash of options
+  #     for creating the prop.
+  #     
+  #     Look at the examples.
+  #   
+  #   @param [Proc?] class_body
+  #     Optional block to evaluate as the new class's body.
+  #   
+  #   @return [Class<I8::Struct::Vector>]
+  #     New structure class.
+  # 
+  # @overload self.new *args, **kwds, &block
+  #   Create a new instance.
+  #   
+  #   @return [I8::Struct::Vector]
+  #     New instance.
+  # 
+  def self.new *args, **kwds, &block
+    # Are we {I8::Struct::Vector}? (See method doc).
+    if self == I8::Struct::Vector
+      unless kwds.empty?
+        raise NRSER::ArgumentError.new \
+          "Can not supply keyword args",
+          args: args,
+          kwds: kwds
+      end
+  
+      # Unwrap `[name: type]` format
+      prop_defs = args.map { |prop_def|
+        if  ::Array === prop_def &&
+            prop_def.length == 1 &&
+            ::Hash === prop_def[0]
+          prop_def[0]
+        else
+          prop_def
+        end
+      }
+      
+      # Check we have a list of pairs with label keys
+      t.array( t.pair( key: t.label ) ).check! prop_defs
+      
+      Class.new( I8::Struct::Vector ) do
+        prop_defs.each_with_index do |pair, index|
+          name, value = pair.first
+          
+          kwds = t.match value,
+            t.type, ->( type ) {{ type: type }},
+            t.hash_, value
+          
+          prop name, **kwds, index: index
+        end
+        
+        class_exec &block if block
+      end
+
+    else
+      # No, we are a built struct. Defer up to `super` to create an instance.
+
+      # NOTE  This is... weird. Just doing the normal
+      #       
+      #           super( *args, **kwds, &block )
+      #       
+      #       results in `*args` becoming `[*args, {}]` up the super chain
+      #       when `kwds` is empty.
+      #       
+      #       I can't say I can understand it, but I seem to be able to fix
+      #       it.
+      # 
+      if kwds.empty?
+        super( *args, &block )
+      else
+        super( *args, **kwds, &block )
+      end
+
+    end
+  end # .new
+  
+end # class Struct::Vector
+
+
+# /Namespace
+# ========================================================================
+
+end # module  Struct
+end # module  I8
+