nrser 0.3.9 → 0.3.10

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

@@ -0,0 +1,211 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/labs/i8'
+
+
+# HACK
+class Object
+  def if proc_able, &block
+    block.call( self ) if proc_able.to_proc.call( self )
+  end
+
+  def unless proc_able, &block
+    block.call( self ) unless proc_able.to_proc.call( self )
+  end
+end
+
+# Namespace
+# ========================================================================
+
+module  I8
+
+
+# Definitions
+# =======================================================================
+
+class Surjection
+  
+  include Hamster::Immutable
+
+  
+  # Class Methods
+  # ========================================================================
+
+  def self.[] pairs = {}
+    new pairs
+  end
+
+
+  def self.alloc hash
+    allocate.tap { |instance| instance.instance_variable_set :@hash, hash }
+  end
+
+
+  # Construction
+  # ========================================================================
+
+  def initialize pairs = {}
+    @hash = I8::Hash[
+      pairs.each_with_object( {} ) { |(keys, value), hash|
+        set = I8::Set.new keys
+        if hash.key? value
+          hash[value] |= set
+        else
+          hash[value] = set
+        end
+      }
+    ]
+
+    @hash.values.combination( 2 ).each do |a, b|
+      ( a & b ).unless( :empty? ) { |intersection|
+        raise NRSER::ConflictError.new \
+          "Sets", a, "and", b, "are not disjoint, sharing", intersection
+      }
+    end
+  end
+
+
+  # Instance Methods
+  # ========================================================================
+
+  def call arg
+    @hash.each { |value, set| return value if set.include?( arg ) }
+    nil
+  end
+
+  # The Ruby hash-ish aliases (as methods for easy subclass overrides)
+
+  # @see #call
+  def get key;  call key; end
+  # @see #call
+  def []  key;  call key; end
+
+
+  def put arg, value
+    if domain.include?( arg ) && call( arg ) != value
+      raise NRSER::ConflictError.new "Already mapping", arg, "to", call( arg )
+    end
+
+    if value? value
+      # We already have a set of keys mapping to the value
+      if @hash[value].include? arg
+        # And it already has the key, so we can just return this instance
+        self
+      else
+        # The key set we have for the value does not have the key in it.
+        # 
+        # We need to 
+        # 
+        # 1.  Create a new hash with the key in the value's key set.
+        # 2.  Allocate a new surjection.
+        # 3.  set that as it's hash.
+        # 
+        self.class.alloc @hash.put( value ) { |set| set.add arg }
+      end
+    else
+      # We don't have a set of keys for that value
+      self.class.alloc @hash.put( value, I8::Set[ arg ] )
+    end
+  end
+
+  # The standard aliases (as methods for easy subclass overrides)
+  def store *args, █ put *args, █ end
+
+
+  # The domain of the surjection (or "keys" in Ruby-Hash-y lingo).
+  # 
+  # @return [I8::Set]
+  # 
+  def domain
+    @hash.each_value.reduce I8::Set.empty, :|
+  end
+
+
+  # The Ruby-Hash-y way of finding out if an object is in the {#domain}.
+  # 
+  # Functionally the same as `surjection.domain.include? obj`.
+  # 
+  # @param [Object] key
+  # @return [Boolean]
+  # 
+  def key? key
+    # domain.include? key
+    @hash.each_value.any? { |key_set| key_set.include? key }
+  end
+
+  # The standard aliases (as methods for easy subclass overrides)
+
+  # @see #key?
+  def has_key?  key; key? key; end
+  # @see #key?
+  def include?  key; key? key; end
+  # @see #key?
+  def member?   key; key? key; end
+
+
+  # The codomain of the surjection (or "values" in Ruby-Hash-y lingo).
+  # 
+  # @return [I8::Set]
+  # 
+  def codomain
+    I8::Set.new @hash.keys
+  end
+
+  # The Ruby-Hash-y name (as a method for easy subclass overrides)
+
+  # @see #codomain
+  def values; codomain; end
+
+
+  # Is `value` in the surjection's {#codomain}?
+  # 
+  # @param [Object] value
+  # @return [Boolean]
+  # 
+  def value? value
+    @hash.key? value
+  end
+
+  # The standard aliases (as methods for easy subclass overrides)
+
+  # @see #value?
+  def has_value? value; value? value; end
+
+
+  def inspect
+    to_s_with :inspect
+  end
+
+
+  def to_s
+    to_s_with :to_s
+  end
+
+  
+  protected
+  # ========================================================================
+    
+    def to_s_with method_name
+      "#{ self.class }[" +
+      @hash.each_pair.map { |value, set|
+        "{#{set.map(&method_name).join(', ')}}=>#{value.send method_name}"
+      }.join( ', ' ) +
+      ']'
+    end
+    
+  public # end protected ***************************************************
+
+end # class Surjection
+
+
+# /Namespace
+# ========================================================================
+
+end # module I8

data/lib/nrser/labs/lots/consumer.rb

@@ -1,6 +1,18 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Labs
+module  LOTS
+
+
+# Definitions
+# ========================================================================
+
 class Consumer
   def initialize
     @consumed = []
@@ -102,3 +114,10 @@ class BoolOptConsumer < Consumer
 
 end # class BoolOptConsumer
 
+
+# /Namespace
+# ========================================================================
+
+end # module LOTS
+end # module Labs
+end # module NRSER

data/lib/nrser/labs/lots/parser.rb

@@ -1,5 +1,18 @@
+# encoding: UTF-8
+# frozen_string_literal: true
 
 
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Labs
+module  LOTS
+
+
+# Definitions
+# ========================================================================
+
 class Parser
   def initialize consumers:, tokens:
     @consumers = consumers
@@ -7,4 +20,11 @@ class Parser
   end
 
   
-end
+end
+
+# /Namespace
+# ========================================================================
+
+end # module LOTS
+end # module Labs
+end # module NRSER

data/lib/nrser/labs/stash.rb

@@ -46,7 +46,7 @@ class NRSER::Stash < ::Hash
   
   # Save {Hash#[]=} as {#_raw_put} for directly writing keys and values.
   # 
-  # @protected
+  # @!visibility protected
   # 
   alias_method :_raw_put, :[]=
   protected :_raw_put
@@ -55,7 +55,7 @@ class NRSER::Stash < ::Hash
   # Save {Hash#update} as {#_raw_update} for directly writing many key/value
   # pairs.
   # 
-  # @protected
+  # @!visibility protected
   # 
   # @note
   #   This is a hold-over from {HashWithIndifferentAccess}; not currently in
@@ -67,7 +67,7 @@ class NRSER::Stash < ::Hash
   
   # Save {Hash#key?} direct querying of key presence.
   # 
-  # @protected
+  # @!visibility protected
   # 
   alias_method :_raw_key?, :key?
   protected :_raw_key?
@@ -178,7 +178,7 @@ class NRSER::Stash < ::Hash
   #   hash_2['key'] = 12
   #   hash_1.update(hash_2) { |key, old, new| old + new } # => {"key"=>22}
   # 
-  # @param [Proc<(KEY, CURRENT, UPDATE) => VALUE>] &block
+  # @param [Proc<(KEY, CURRENT, UPDATE) => VALUE>] block
   #   Optional block to handle key conflicts.
   # 
   # @return [self]

data/lib/nrser/log.rb

@@ -104,14 +104,6 @@ module NRSER::Log
   # @!group Utility Class Methods
   # ------------------------------------------------------------------------
   
-  # @todo Document logger_name_and_type method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
   def self.logger_type_and_name_from subject
     case subject
     when String
@@ -184,7 +176,7 @@ module NRSER::Log
   # 
   # @see https://github.com/rocketjob/semantic_logger/blob/97247126de32e6ecbf74cbccaa3b3732768d52c5/lib/semantic_logger/semantic_logger.rb#L454
   # 
-  # @param [Symbol | String | Integer]
+  # @param [Symbol | String | Integer] level
   #   Representation of a level in one of the following formats:
   #   
   #   1.  {Symbol} - verified as member of {SemanticLogger::LEVELS} and
@@ -299,7 +291,7 @@ module NRSER::Log
   
   # Try to find a log level in the ENV.
   # 
-  # @param [String | false | nil] prefix:
+  # @param [String | false | nil] prefix
   #   The prefix to look under.
   # 
   # @return [nil]
@@ -340,18 +332,30 @@ module NRSER::Log
   # --------------------------------------------------------------------------
   
   # Setup logging.
-  # 
-  # @param [String | false | nil] env_var_prefix:
-  #   Prefix to ENV var names to look for logging setup config under,
-  #   like `<prefix>_LOG_LEVEL`, `<prefix>_DEBUG` and `<prefix>_TRACE`.
-  #   
-  #   If `nil` (the default), we'll try to use `application` to guess a
-  #   prefix.
-  #   
+  #
+  # @param [String | false | nil] env_var_prefix Prefix to ENV var names to look
+  #   for logging setup config under, like `<prefix>_LOG_LEVEL`,
+  #   `<prefix>_DEBUG` and `<prefix>_TRACE`.
+  #
+  #   If `nil` (the default), we'll try to use `application` to guess a prefix.
+  #
   #   You can disable any ENV lookups by passing `false`.
-  # 
+  #
+  # @param [Boolean] sync Enables or disables synchronous logging, where the log
+  #   message is processed entirely in the logging thread before the log call
+  #   returns.
+  #
+  #   {SemanticLogger} offloads log formating and writing to a separate thread
+  #   in it's standard configuration, an approach presumably aimed at
+  #   performance, but one that can be problematic when logging mutable values
+  #   that may change between the log call and the log serialization.
+  #   
+  #   See
+  #   {file:doc/known_issues_and_gotchas/semantic_logger_and_mutable_values.md 
+  #     SemanticLogger and Mutable Values}.
+  #
   # @return [nil]
-  # 
+  #
   def self.setup! level: nil,
                   dest: nil,
                   sync: nil,
@@ -448,7 +452,7 @@ module NRSER::Log
   # Call {.setup!} with some default keywords that are nice for interactive
   # session (console/REPL) usage.
   # 
-  # @param [Boolean] add_main_logger:
+  # @param [Boolean] add_main_logger
   #   Define a `logger` method at the top level (global) that gets a logger
   #   for the main object.
   # 

data/lib/nrser/log/appender/sync.rb

@@ -69,17 +69,21 @@ class NRSER::Log::Appender::Sync
 
   # Construct a sync appender.
   #
-  # @param [SemanticLogger]
-  #   name: [String]
-  #     Name to use for the log thread and the log name when logging any errors from this appender.
-  #
-  #   lag_threshold_s [Float]
-  #     Log a warning when a log message has been on the queue for longer than this period in seconds.
-  #     Default: 30
-  #
-  #   lag_check_interval: [Integer]
-  #     Number of messages to process before checking for slow logging.
-  #     Default: 1,000
+  # @param [SemanticLogger::Subscriber] appender
+  #   The appender this appender will attempt to append to when there are  
+  #   pending appendables to append. Apparently.
+  #   
+  #   Sorry, I just ended up here trying to clear out Yard warnings so I can 
+  #   maybe figure out why it's all of sudden shitting the bed. Guess I needed
+  #   a break.
+  #   
+  #   In truth I don't even think it needs to be a Subscriber, but that's 
+  #   probably the easiest way to think about it.
+  # 
+  # @param [String] name
+  #   Name to use for the log thread and the log name when logging any errors 
+  #   from this appender.
+  # 
   def initialize  appender:, name: appender.class.safe_name
     @appender = appender
   end

data/lib/nrser/log/formatters/color.rb

@@ -51,9 +51,6 @@ class NRSER::Log::Formatters::Color < ::SemanticLogger::Formatters::Color
   
   # @todo Document default_color_map method.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
   # @return [SemanticLogger::Formatters::Color::ColorMap]
   # 
   def self.default_color_map

data/lib/nrser/log/formatters/mixin.rb

@@ -160,7 +160,7 @@ module NRSER::Log::Formatters::Mixin
   #   # >
   #   # => true
   # 
-  # @param [Array<Symbol>] *tokens
+  # @param [Array<Symbol>] tokens
   #   Optional list of token symbols to set as the header format.
   #   
   #   When empty, the method works as a getter, returning the current header
@@ -184,7 +184,7 @@ module NRSER::Log::Formatters::Mixin
   # 
   # @see #header
   # 
-  # @param [Array<Symbol>] *tokens
+  # @param [Array<Symbol>] tokens
   #   Token symbols to set as the header format.
   # 
   # @return [HeaderTokens]
@@ -202,7 +202,7 @@ module NRSER::Log::Formatters::Mixin
   # 
   # @see #header
   # 
-  # @param [Array<Symbol>] *tokens
+  # @param [Array<Symbol>] tokens
   #   When not empty, sets the body to those tokens in that order.
   #   
   #   When empty, the current body is returned.
@@ -225,7 +225,7 @@ module NRSER::Log::Formatters::Mixin
   # 
   # @see #header
   # 
-  # @param [Array<Symbol>] *tokens
+  # @param [Array<Symbol>] tokens
   #   Token symbols to set as the body format.
   # 
   # @return [HeaderTokens]