nrser 0.3.9 → 0.3.10

data/lib/nrser/rspex/example_group/describe_source_file.rb

@@ -20,7 +20,7 @@ module NRSER::RSpex::ExampleGroup
   # 
   # @param *description (see #describe_x)
   # 
-  # @param [Hash<Symbol, Object>] **metadata
+  # @param [Hash<Symbol, Object>] metadata
   #   RSpec metadata to set for the example group.
   #   
   #   See the `metadata` keyword argument to {#describe_x}.

data/lib/nrser/rspex/example_group/describe_spec_file.rb

@@ -38,10 +38,10 @@ module NRSER::RSpex::ExampleGroup
   #   2.  Built description would need to be conditional on what metadata
   #       was found.
   # 
-  # @param [String] description:
+  # @param [String] description
   #   A description of the spec file to add to the RSpec description.
   # 
-  # @param [String] spec_path:
+  # @param [String] spec_path
   #   The path to the spec file (just feed it `__FILE__`).
   #   
   #   Probably possible to extract this somehow without having to provide it?
@@ -85,5 +85,7 @@ module NRSER::RSpex::ExampleGroup
       &describe_x_body
     
   end # #describe_spec_file
+
+  alias_method :SPEC_FILE, :describe_spec_file
   
 end # module NRSER::RSpex::ExampleGroup

data/lib/nrser/rspex/example_group/describe_when.rb

@@ -9,7 +9,7 @@ module NRSER::RSpex::ExampleGroup
   # 
   # @param *description (see #describe_x)
   # 
-  # @param [Hash<Symbol, Object>] **bindings
+  # @param [Hash<Symbol, Object>] bindings
   #   See the `bindings` keyword arg in {#describe_x}.
   # 
   # @param &body (see #describe_x)
@@ -30,6 +30,7 @@ module NRSER::RSpex::ExampleGroup
   # Short names (need `_` pre 'cause of `when` Ruby keyword, and suffix fucks
   # up auto-indent in Atom/VSCode)
   alias_method :_when, :describe_when
+  alias_method :WHEN, :describe_when
   
   
 end # module NRSER::RSpex::ExampleGroup

data/lib/nrser/rspex/example_group/describe_x.rb

@@ -11,18 +11,18 @@ module NRSER::RSpex::ExampleGroup
   # if you want the RSpex functionality but absolutely have to set some
   # metadata key that we use for something else.
   # 
-  # @param [Array] *description
+  # @param [Array] description
   #   Optional list of elements that compose the custom description.
   #   
   #   Will be passed to {NRSER::RSpex::Format.description} to produce the
   #   string value that is in turn passed to {RSpec.describe}.
   # 
-  # @param [Symbol] type:
+  # @param [Symbol] type
   #   The RSpex "type" of the example group, which is used to determine the
   #   prefix of the final description and is assigned to the `:type` metadata
   #   key.
   # 
-  # @param [Hash<Symbol, Object>] metadata:
+  # @param [Hash<Symbol, Object>] metadata
   #   [RSpec metadata][] to add to the new example group.
   #   
   #   In addition to the keys RSpec will reject, we prohibit `:type` *unless*
@@ -33,7 +33,7 @@ module NRSER::RSpex::ExampleGroup
   #   
   #   [RSpec metadata]: https://relishapp.com/rspec/rspec-core/docs/metadata/user-defined-metadata
   # 
-  # @param [Hash<Symbol, Object>] bindings:
+  # @param [Hash<Symbol, Object>] bindings
   #   Name to value pairs to bind in the new example group.
   #   
   #   All values will be bound at the example group and example levels -
@@ -41,7 +41,7 @@ module NRSER::RSpex::ExampleGroup
   #   group level, while they will be automatically unwrapped at the
   #   example level (as the requisite context is available there).
   # 
-  # @param [Boolean] bind_subject:
+  # @param [Boolean] bind_subject
   #   When `true` (and there is a `subject_block`) bind the `subject` inside
   #   the new example group.
   # 

data/lib/nrser/rspex/format.rb

@@ -114,14 +114,6 @@ module NRSER::RSpex::Format
   end
   
   
-  # @todo Document format_type method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
   def self.prepend_type type, description
     return description if type.nil?
     
@@ -160,13 +152,6 @@ module NRSER::RSpex::Format
   end
   
   
-  # @todo Document format method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [String]
-  # 
   def self.description *parts, type: nil
     parts.
       flat_map { |part|

data/lib/nrser/sugar/method_missing_forwarder.rb

@@ -21,7 +21,7 @@ class NRSER::MethodMissingForwarder < BasicObject
   # Instantiate a new `NRSER::MethodMissingForwarder` holding the forwarding
   # block.
   # 
-  # @param [Proc<(symbol:Symbol, *args, &block)>] &forwarder
+  # @param [Proc<(symbol:Symbol, *args, &block)>] forwarder
   #   Block that will receive all calls to {#method_missing}.
   # 
   def initialize &forwarder
@@ -37,10 +37,10 @@ class NRSER::MethodMissingForwarder < BasicObject
   # @param [Symbol] symbol
   #   The name of the method that was called.
   # 
-  # @param [Array] *args
+  # @param [Array] args
   #   Any parameters the missing method was called with.
   # 
-  # @param [Proc?] &block
+  # @param [Proc?] block
   #   The block the method was called with, if any.
   # 
   def method_missing symbol, *args, &block

data/lib/nrser/sys/env/path.rb

@@ -92,7 +92,7 @@ class NRSER::Sys::Env::Path
   # @param [String] path
   #   Path to test against.
   # 
-  # @param [Array<String | Proc<String=>Boolean> | Regexp>] *patterns
+  # @param [Array<String | Proc<String=>Boolean> | Regexp>] patterns
   #   Patterns to test:
   #   
   #   -   `String` - test if it and `path` are equal (`==`)
@@ -126,14 +126,6 @@ class NRSER::Sys::Env::Path
   end # .matches_pattern?
   
   
-  # @todo Document from_env method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
   def self.from_ENV env_key
     new ENV[env_key.to_s], env_key: env_key
   end # .from_env
@@ -260,7 +252,7 @@ class NRSER::Sys::Env::Path
   # 
   # @see http://www.rubydoc.info/gems/hamster/Hamster/Vector#each-instance_method
   # 
-  # @param [nil | Proc<(String)=>*>] &block
+  # @param [nil | Proc<(String)=>*>] block
   #   When present, block will be called once for each string path in this
   #   object. First path is most prominent, down to least last.
   # 
@@ -302,23 +294,5 @@ class NRSER::Sys::Env::Path
     @value.to_a
   end
   
-  protected
-  # ========================================================================
-    
-    # Internal method to remove paths that have already been normalized.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def remove_paths paths
-      # method body...
-    end # #remove_paths
-    
-    
-  # end protected
-  
   
 end # class NRSER::Env::Path

data/lib/nrser/types.rb

@@ -15,7 +15,7 @@ require 'nrser/log'
 
 # Stuff to help you define, test, check and match types in Ruby.
 # 
-# {include:file:lib/nrser/types/README.md}
+# Read the documentation {file:lib/nrser/types/README.md here}.
 # 
 module NRSER::Types
   
@@ -29,7 +29,10 @@ module NRSER::Types
   # Mixins
   # ========================================================================
   
+  # Add `.def_type` to define type factories
   extend Factory
+
+  # Add `.logger` and `#logger`.
   include NRSER::Log::Mixin
   
   
@@ -38,8 +41,18 @@ module NRSER::Types
   
   L_PAREN = '(' # '❪'
   R_PAREN = ')' # '❫'
-  RESPONDS_WITH = '→'
-  ASSOC = '=>'
+  RESPONDS_WITH = '→' # '->'
+  ASSOC = '=>' # terrible, don't use: '⇒'
+  LEQ = '≤'
+  GEQ = '≥'
+  COMPLEXES = 'ℂ'
+  REALS = 'ℝ'
+  INTEGERS = 'ℤ'
+  RATIONALS = 'ℚ'
+  UNION = '∪'
+  AND = '&'
+  NOT = '¬' # '~'
+  COMPLEMENT = '∖'
   
   
   # Module Methods
@@ -67,11 +80,11 @@ module NRSER::Types
   # 
   def self.make value
     if value.nil?
-      self.nil
+      self.Nil
     elsif value.is_a? NRSER::Types::Type
       value
     else
-      self.when value
+      self.When value
     end
   end
   
@@ -104,13 +117,34 @@ module NRSER::Types
     make( type ).check! value
   end
   
-  # Old name
-  singleton_class.send :alias_method, :check, :check!
+
+  # Old bang-less name for {.check!}. We like out bangs around here.
+  # 
+  # @deprecated
+  # 
+  # @param    (see .check!)
+  # @return   (see .check!)
+  # @raise    (see .check!)
+  # 
+  def self.check value, type
+    logger.deprecated \
+      method: __method__,
+      alternative: "NRSER::Types.check!"
+    
+    check! value, type
+  end
   
   
   # Create a {NRSER::Types::Type} from `type` with {.make} and test if
   # `value` satisfies it.
   # 
+  # @param [Object] value
+  #   Value to test for membership.
+  # 
+  # @param [TYPE] type
+  #   Type to see if value satisfies. Passed through {.make} to make sure it's
+  #   a {Type} first.
+  # 
   # @return [Boolean]
   #   `true` if `value` satisfies `type`.
   # 
@@ -118,13 +152,29 @@ module NRSER::Types
     make(type).test value
   end
   
+  
+  # Old question-less name for {.test?}. We like our marks around here.
+  # 
+  # @param  (see .test?)
+  # @return (see .test?)
+  # @raise  (see .test?)
+  # 
+  def self.test value, type
+    logger.deprecated \
+      method: __method__,
+      alternative: "NRSER::Types.test?"
+    
+    test? value, type
+  end # .test
+
   # Old name
   singleton_class.send :alias_method, :test, :test?
   
   
+  # My own shitty version of pattern matching!
+  # 
   # @todo
-  #   Switch {NRSER::Types.match} to use `===`! Should allow us to avoid
-  #   making types for everything?
+  #   Doc this crap.
   #   
   def self.match value, *clauses
     if clauses.empty?
@@ -213,11 +263,11 @@ require_relative './types/is_a'
 require_relative './types/where'
 require_relative './types/combinators'
 require_relative './types/maybe'
-require_relative './types/attrs'
+require_relative './types/attributes'
 require_relative './types/in'
 
 require_relative './types/when'
-require_relative './types/any'
+require_relative './types/top'
 require_relative './types/booleans'
 
 # Requires `booleans`
@@ -232,5 +282,6 @@ require_relative './types/hashes'
 require_relative './types/paths'
 require_relative './types/tuples'
 require_relative './types/pairs'
-require_relative './types/trees'
+require_relative './types/collections'
 require_relative './types/shape'
+require_relative './types/selector'

data/lib/nrser/types/README.md

@@ -0,0 +1,76 @@
+About NRSER::Types
+========================================================================
+
+Ah, Neil's Shitty Type System (NSTS).
+
+Kinda like [tcomb][], but for for Ruby, and worse.
+
+Anyways I needed this because I needed some re-usable way for things to make sure they were in some reasonable state at runtime. And it kind-of works for that so far.
+
+[tcomb]: https://github.com/gcanti/tcomb
+
+
+Structure & Design
+------------------------------------------------------------------------
+
+At the bottom of everything, there are *type classes*... which are Ruby classes
+that descend from {NRSER::Types::Type}. We call instances of these classes
+*types*.
+
+Types essentially do one thing: they have a {NRSER::Types::Type#test?} method
+that accepts a single arguments and returns a boolean. If the type returns
+`true` when `#test?` is called with an object, then that object is a member of
+that type. That's it.
+
+Some of those classes, like the universal type {NRSER::Types::Top} - of which
+every object is a member ({NRSER::Types::Top#test?} always returns `true`) - are
+essentially singletons, but many type classes parameterize over values that
+instances hold as variables.
+
+Types are designed to fundamentally immutable once constructed, through the 
+standard practice of storing state in instance variables without write 
+functions (of course, use of methods like `#instance_variable_set` will still
+mutate types - please don't do this, since any future caching will likely 
+reuse instances).
+
+API is basically a collection of module class methods attached to
+{NRSER::Types}, like {NRSER::Types.str} or {NRSER::Types.non_neg_int}.
+
+
+### Type Maker Method Names
+
+I generally went with "short" type names, IDK, to keep things short, and maybe to conflict a bit less with other common names in Ruby.
+
+Some examples:
+
+-   `str`
+-   `bool`
+-   `non_neg_int`
+
+You get the idea. Many have their longer names added as aliases, which I like... would rather have it "just work" with what you type than have to remember what exactly we chose to call stuff.
+
+
+### What to Expect
+
+These method should all return {NRSER::Types::Type} instances, though many will use a refined subclass of {NRSER::Types::Type} like {NRSER::Types::Bounded} or whatever.
+
+I picked this functional approach over a more I guess standard object-oriented architecture - where every type would be it's own class and you would instantiate them - because it's along the line of how [tcomb][] is designed and I think it works pretty well there. It also provides a lot of flexibility as far as combinators and such: we will return a {NRSER::Types::Type} that meets your needs, making no further contract, which allows us a lot more freedom to muck around in the back end.
+
+
+### Them Options
+
+The {NRSER::Types} module methods should all accept a `options` hash as the last argument that will eventually find it's way up to {NRSER::Types::Type#initialize}. Many should accept other arguments as it makes sense.
+
+In cases where the type maker method wants a keyword hash of it's own, I think I've been separating them out into two arguments, like:
+
+    def some_type kwds, options = {}
+      ...
+    end
+
+which is a bit of a pain 'cause you gotta use parens if you want to pass options as well as keywords:
+
+    some_type( {x: 1, y: 3}, name: 'SomeType' )
+
+but you don't run into any conflicts between options and keywords or whatever else, and it's nice to just pick a style and stick with it rather than have to do one or two different 'cause of a conflict.
+
+

data/lib/nrser/types/arrays.rb

@@ -8,161 +8,216 @@
 # -----------------------------------------------------------------------
 
 require_relative './is_a'
+require_relative './top'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
 
 
 # Definitions
 # =======================================================================
+
+# Arrays!
+# 
+# @note
+#   Construct {ArrayType} types using the {.Array} factory.
+# 
+# @todo
+#   Just call this Array?!
+#   
+#   Combine with arrays of a type?!
+# 
+class ArrayType < IsA
+  # Default value to split strings with in {#from_s} if the string provided
+  # does is not recognized as an encoding format (as of writing, JSON is
+  # the only format we attempt to detect).
+  # 
+  # Splits
+  DEFAULT_SPLIT_WITH = /\,\s*/m
   
-module NRSER::Types
+  def initialize split_with: DEFAULT_SPLIT_WITH, **options
+    super ::Array, **options
+    @split_with = split_with
+  end
   
-  class ArrayType < IsA
-    # Default value to split strings with in {#from_s} if the string provided
-    # does is not recognized as an encoding format (as of writing, JSON is
-    # the only format we attempt to detect).
-    # 
-    # Splits
-    DEFAULT_SPLIT_WITH = /\,\s*/m
-    
-    def initialize split_with: DEFAULT_SPLIT_WITH, **options
-      super ::Array, **options
-      @split_with = split_with
-    end
-    
-    
-    def item_type; NRSER::Types.any; end
-    
-    
-    # Called on an array of string items that have been split
-    # from a single string by {#from_s} to convert each individual item before
-    # {#check} is called on the value.
-    # 
-    # {NRSER::Types::ArrayType} implementation is a no-op that just returns
-    # `items` - this method is in place for subclasses to override.
-    # 
-    # @param [Array<String>] items
-    # 
-    # @return [Array]
-    # 
-    def items_from_strings items
-      items
-    end
-    
-    
-    def custom_from_s string
-      # Does it looks like a JSON array?
-      if NRSER.looks_like_json_array? string
-        # It does! Load it
-        begin
-          return JSON.load( string )
-        rescue
-          # pass - if we failed to load as JSON, it may just not be JSON, and
-          # we can try the split approach below.
-        end
-      end
-      
-      # Split it with the splitter and check that
-      items_from_strings( string.split( @split_with ) )
+  
+  def item_type; NRSER::Types.Top; end
+
+
+  # @!group Display Instance Methods
+  # ------------------------------------------------------------------------
+
+  def default_name
+    if item_type == NRSER::Types.Top
+      'Array'
+    else
+      "Array<#{ item_type.name }>"
     end
-    
-  end # ArrayType
+  end
+
+
+  def default_symbolic
+    "[#{ item_type.symbolic }]"
+  end
+
+  # @!endgroup Display Instance Methods # ************************************
   
   
-  # Type for arrays where every entry satisfies a specific type.
+  # Called on an array of string items that have been split
+  # from a single string by {#from_s} to convert each individual item before
+  # {#check} is called on the value.
   # 
-  # Broken out from {ArrayType} so that {TupleType} can inherit from
-  # {ArrayType} and get share it's string handling functionality without
-  # receiving the entry type stuff (which it handles differently).
+  # {NRSER::Types::ArrayType} implementation is a no-op that just returns
+  # `items` - this method is in place for subclasses to override.
   # 
-  class ArrayOfType < ArrayType
-    
-    # Attributes
-    # ======================================================================
-    
-    # Type that all items must satisfy for an array to be a member of this
-    # type.
-    # 
-    # @return [NRSER::Types::Type]
-    #     
-    attr_reader :item_type
-    
-    
-    # Constructor
-    # ======================================================================
-    
-    # Instantiate a new `ArrayOfType`.
-    def initialize item_type, **options
-      super **options
-      @item_type = NRSER::Types.make item_type
-    end # #initialize
-    
-    
-    # Instance Methods
-    # ======================================================================
-    
-    def explain
-      "#{ super() }<#{ item_type.explain }>"
-    end
-    
-    
-    def test? value
-      # Check the super method first, which will test if `value` is an Array
-      # instance, and return `false` if it's not.
-      return false unless super( value )
-      
-      # Otherwise test all the items
-      value.all? &@item_type.method( :test )
-    end
-    
-    
-    # {ArrayOfType} can convert values from strings if it's {#item_type}
-    # can convert values from strings.
-    # 
-    # @return [Boolean]
-    # 
-    def has_from_s?
-      @from_s || @item_type.has_from_s?
-    end
-    
-    
-    def items_from_strings items
-      items.map &@item_type.method( :from_s )
-    end
-    
-    
-    # @todo
-    #   I'm not even sure why this is implemented... was it used somewhere?
-    #   
-    #   It doesn't seems too well thought out... seems like the reality of
-    #   comparing types is much more complicated?
-    # 
-    def == other
-      equal?(other) || (
-        other.class == self.class && @item_type == other.item_type
-      )
+  # @param [Array<String>] items
+  # 
+  # @return [Array]
+  # 
+  def items_from_strings items
+    items
+  end
+  
+  
+  def custom_from_s string
+    # Does it looks like a JSON array?
+    if NRSER.looks_like_json_array? string
+      # It does! Load it
+      begin
+        return JSON.load( string )
+      rescue
+        # pass - if we failed to load as JSON, it may just not be JSON, and
+        # we can try the split approach below.
+      end
     end
     
-  end # class ArrayOfType
+    # Split it with the splitter and check that
+    items_from_strings( string.split( @split_with ) )
+  end
+  
+end # ArrayType
+
+
+# Type for arrays where every entry satisfies a specific type.
+# 
+# Broken out from {ArrayType} so that {TupleType} can inherit from
+# {ArrayType} and get share it's string handling functionality without
+# receiving the entry type stuff (which it handles differently).
+# 
+class ArrayOfType < ArrayType
   
+  # Attributes
+  # ======================================================================
   
-  # {NRSER::Types::ArrayType} / {NRSER::Types::ArrayOfType} factory function.
-  # 
-  # @param [Type | Object] item_type
-  #   Optional type of items.
+  # Type that all items must satisfy for an array to be a member of this
+  # type.
   # 
   # @return [NRSER::Types::Type]
+  #     
+  attr_reader :item_type
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `ArrayOfType`.
+  def initialize item_type, **options
+    super **options
+    @item_type = NRSER::Types.make item_type
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # @!group Display Instance Methods
+  # ------------------------------------------------------------------------
+
+  def explain
+    "Array<#{ item_type.explain }>"
+  end
+
+  # @!endgroup Display Instance Methods # ************************************
+  
+  
+  def test? value
+    # Check the super method first, which will test if `value` is an Array
+    # instance, and return `false` if it's not.
+    return false unless super( value )
+    
+    # Otherwise test all the items
+    value.all? &@item_type.method( :test )
+  end
+  
+  
+  # {ArrayOfType} can convert values from strings if it's {#item_type}
+  # can convert values from strings.
   # 
+  # @return [Boolean]
+  # 
+  def has_from_s?
+    @from_s || @item_type.has_from_s?
+  end
+  
+  
+  def items_from_strings items
+    items.map &@item_type.method( :from_s )
+  end
+  
+  
   # @todo
-  #   Make `list` into it's own looser interface for "array-like" object API.
+  #   I'm not even sure why this is implemented... was it used somewhere?
+  #   
+  #   It doesn't seems too well thought out... seems like the reality of
+  #   comparing types is much more complicated?
   # 
-  def_factory(
-    :array,
-    aliases: [:list],
-  ) do |item_type = any, **options|
-    if item_type == any
-      ArrayType.new **options
-    else
-      ArrayOfType.new item_type, **options
-    end
-  end # #array
+  def == other
+    equal?(other) || (
+      other.class == self.class && @item_type == other.item_type
+    )
+  end
   
-end # NRSER::Types
+end # class ArrayOfType
+
+
+# @!group Array Type Factories
+# ----------------------------------------------------------------------------
+
+# @!method self.Array item_type = self.Top, **options
+#   {NRSER::Types::ArrayType} / {NRSER::Types::ArrayOfType} factory function.
+#   
+#   @param [Type | Object] item_type
+#     Optional type of items. If this is not a {Type}, one will be created from 
+#     it via {NRSER::Types.make}.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [NRSER::Types::Type]
+#   
+#   @todo
+#     Make `list` into it's own looser interface for "array-like" object API.
+#   
+def_type        :Array,
+  parameterize: :item_type,
+  aliases:    [ :list ],
+&->( item_type = self.Top, **options ) do
+  if item_type == self.Top
+    ArrayType.new **options
+  else
+    ArrayOfType.new item_type, **options
+  end
+end # .Array
+
+# @!endgroup Array Type Factories # ******************************************
+
+
+# /Namespace
+# ========================================================================
+
+end # module  Types
+end # module  NRSER