nrser 0.3.9 → 0.3.10

data/lib/nrser/log/logger.rb

@@ -9,6 +9,11 @@
 
 require 'semantic_logger'
 
+# Project / Package
+# ----------------------------------------------------------------------------
+
+require 'nrser/functions/text/format'
+
 
 # Definitions
 # =======================================================================
@@ -38,7 +43,7 @@ class NRSER::Log::Logger < SemanticLogger::Logger
     # @param [NRSER::Log::Logger] logger
     #   The logger to use if the block raises.
     # 
-    # @param [*] on_fail:
+    # @param [*] on_fail
     #   Value to return when `&block` raises.
     # 
     def initialize logger, on_fail: nil
@@ -109,7 +114,7 @@ class NRSER::Log::Logger < SemanticLogger::Logger
   # easier to work with than the standard logging methods' multiple valid
   # argument formats.
   # 
-  # @param [Array] *args
+  # @param [Array] args
   #   Valid arguments for {SemanticLogger::Logger#debug}, etc. - see notes
   #   above.
   # 
@@ -245,13 +250,13 @@ class NRSER::Log::Logger < SemanticLogger::Logger
   #   Name of the class, module, or other identifier for which the log messages
   #   are being logged
   #
-  # @param [nil | Symbol] level:
+  # @param [nil | Symbol] level
   #   Only allow log entries of this level or higher to be written to this
   #   appender For example if set to :warn, this appender would only log
   #   `:warn` and `:fatal` log messages when other appenders could be logging
   #   `:info` and lower.
   #
-  # @param [nil | Regexp | Proc<(SemanticLogger::Log) => Boolean>] filter:
+  # @param [nil | Regexp | Proc<(SemanticLogger::Log) => Boolean>] filter
   #   1.  {RegExp}: Only include log messages where the class name matches
   #       the supplied regular expression. All other messages will be
   #       ignored.
@@ -377,7 +382,7 @@ class NRSER::Log::Logger < SemanticLogger::Logger
   #     what_is_your_favorite_color?
   #   end
   # 
-  # @param **options
+  # @param [Hash] options
   #   Passed to {Catcher#initialize}.
   # 
   # @return [Catcher]
@@ -400,7 +405,7 @@ class NRSER::Log::Logger < SemanticLogger::Logger
   # @param [Symbol?] level
   #   One of {SemanticLogger::LEVELS} or `nil` to use the global default level.
   # 
-  # @param [Proc<() => RESULT] &block
+  # @param [Proc<() => RESULT>] block
   #   Block to execute with the `level`.
   # 
   # @return [RESULT]
@@ -416,6 +421,49 @@ class NRSER::Log::Logger < SemanticLogger::Logger
       self.level = prior_level
     end
   end
+
+
+  # Let 'em know they done wrong.
+  # 
+  # Which is funny, because only I use the library, and probably only I will
+  # ever use this library. So I'm basically nagging my-fucking-self. Sad.
+  # 
+  # @param [Array] message
+  #   Message segments, formatted with {NRSER.fmt_msg}.
+  # 
+  # @param [String] method
+  #   Something about what method it is.
+  # 
+  # @param [String?] alternative
+  #   Optionally (hopefully) something about what I should be using.
+  # 
+  # @param [Integer] max_stack_lines
+  #   How many lines of the stack to spew out (it can get real big real easy).
+  # 
+  # @return [nil]
+  # 
+  def deprecated *message, method:, alternative: nil, max_stack_lines: 16
+    kwds = { method: method }
+
+    kwds[:alternative] = alternative if alternative
+
+    if max_stack_lines > 0
+      kwds[:stack] =  NRSER::ellipsis \
+                        caller,
+                        max_stack_lines,
+                        omission: '[ ...omitted... ]'
+    end
+
+    if message.empty?
+      message = [ "Method", method, "has been DEPRECIATED" ]
+    else
+      message = [ 'DEPRECIATED:', *message ]
+    end
+
+    warn NRSER.fmt_msg( *message ), **kwds
+
+    nil
+  end # #deprecated
   
   
 end # class NRSER::Log::Logger

data/lib/nrser/log/mixin.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+
 # Definitions
 # =======================================================================
 
@@ -53,7 +54,7 @@ module NRSER::Log::Mixin
   # Instance Methods
   # ========================================================================
   
-  # Gets the {NRSER::Log:Logger} for use in the instance. This will be the
+  # Gets the {NRSER::Log::Logger} for use in the instance. This will be the
   # class logger from {ClassMethods#logger} unless the instance has a
   # `#create_logger` method.
   # 

data/lib/nrser/log/plugin.rb

@@ -98,23 +98,23 @@ class Plugin
   #   Though the logging methods don't use a block at this time, it's there
   #   for completeness and possible futures.
   # 
-  # @param [Symbol] level:
+  # @param [Symbol] level
   #   The log level of the call; one of {SemanticLogger::LEVELS}.
   # 
-  # @param [String?] message:
+  # @param [String?] message
   #   Log message.
   # 
-  # @param [Hash?] payload:
+  # @param [Hash?] payload
   #   Map of names to values to log.
   # 
-  # @param [Object?] exception:
+  # @param [Object?] exception
   #   An error to log. This will be an {Exception} in MRI, but *won't* be in
   #   JRuby and possibly other runtimes.
   # 
-  # @param [Object?] metric:
+  # @param [Object?] metric
   #   I don't know what this is. I found it in the SemLog code.
   # 
-  # @param [Proc] &block
+  # @param [Proc] block
   #   Block to pass to the {#logger}'s `level` method. Not currently used
   #   (see note above).
   # 

data/lib/nrser/log/types.rb

@@ -40,38 +40,55 @@ module  Log
 #   it when loading up.
 #   
 module Types
-  extend NRSER::Types::Factory
+  extend t::Factory
   
-  def_factory :level do |
-    name: 'LogLevel',
-    from_s: ->( string ) { string.to_sym },
-    **options
-  |
-    t.in SemanticLogger::LEVELS, from_s: from_s, name: name, **options
-  end
+  #@!method self.LogLevel **options
+  #   A member of {SemanticLogger::LEVELS}.
+  #   
+  #   @param [Hash] options
+  #     Passed to {Type#initialize}.
+  #   
+  #   @return [Type]
+  #   
+  def_type        :LogLevel,
+    aliases:      [ :level ],
+    from_s:       ->( string ) { string.to_sym },
+  &->( **options ) do
+    t.In SemanticLogger::LEVELS, **options
+  end # .LogLevel
   
   
-  def_factory :stdio do |
-    name: 'StdIO',
-    
-    from_s: ->( string ) {
-      case string
-      when '$stdout'
-        $stdout
-      when '$stderr'
-        $stderr
-      when 'STDOUT'
-        STDOUT
-      when 'STDERR'
-        STDERR
-      end
-    },
-    
-    **options
-  |
-    t.is_a IO, name: name, from_s: from_s, **options
-  end
-  
+  #@!method self.StdIO **options
+  #   An {IO} instance with {Type#from_s} mapping:
+  #   
+  #       '$stdio'  -> $stdio
+  #       '$stderr' -> $stderr
+  #       'STDOUT'  -> STDOUT
+  #       'STDERR'  -> STDERR
+  #   
+  #   @param [Hash] options
+  #     Passed to {Type#initialize}.
+  #   
+  #   @return [Type]
+  #   
+  def_type        :StdIO,
+    aliases:      [ :stdio ],
+    from_s:       ->( string ) {
+                    case string
+                    when '$stdout'
+                      $stdout
+                    when '$stderr'
+                      $stderr
+                    when 'STDOUT'
+                      STDOUT
+                    when 'STDERR'
+                      STDERR
+                    end
+                  },
+  &->( **options ) do
+    t.IsA IO, **options
+  end # .StdIO
+
 end # module Types
 
 

data/lib/nrser/mean_streak.rb

@@ -90,14 +90,6 @@ class NRSER::MeanStreak
   end
   
   
-  # @todo Document parse method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
   def parse source, **options
     NRSER::MeanStreak::Document.parse \
       source,

data/lib/nrser/mean_streak/document.rb

@@ -47,9 +47,6 @@ class NRSER::MeanStreak::Document
   
   # @todo Document from method.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
   # @return [NRSER::MeanStreak::Document]
   #   @todo Document return value.
   # 
@@ -166,7 +163,7 @@ class NRSER::MeanStreak::Document
   # Computes the *byte* index for a `line` and `column` in the source, both
   # of which *are in bytes*.
   # 
-  # @param [Integer] line:
+  # @param [Integer] line
   #   
   # 
   def source_byte_index line:, column:

data/lib/nrser/message.rb

@@ -76,10 +76,10 @@ module NRSER
     # @param [String | Symbol] symbol
     #   Name of target method.
     # 
-    # @param [Array] *args
+    # @param [Array] args
     #   Any arguments that should be sent.
     # 
-    # @param [nil | #call] &block
+    # @param [nil | #call] block
     #   Optional block that should be sent.
     # 
     def initialize symbol, *args, &block
@@ -146,7 +146,7 @@ module NRSER
     # @param [Object] receiver
     #   Object that the message will be sent to.
     # 
-    # @param [Boolean] publicly:
+    # @param [Boolean] publicly
     #   When `true`, the message will be sent via {Object#public_send}. This is
     #   the default behavior.
     #   

data/lib/nrser/meta/README.md

@@ -0,0 +1,4 @@
+NRSER::Meta Module
+========================================================================
+
+Meta-programming tools.

data/lib/nrser/meta/lazy_attr.rb

@@ -63,10 +63,10 @@ class LazyAttr < MethodDecorators::Decorator
   #   
   #   It's just `target.receiver`, but the API is how it is.
   # 
-  # @param [Array] *args
+  # @param [Array] args
   #   Any arguments the decorated method was called with.
   # 
-  # @param [Proc?] &block
+  # @param [Proc?] block
   #   The block the decorated method was called with (if any).
   # 
   # @return

data/lib/nrser/meta/source/location.rb

@@ -56,7 +56,7 @@ class NRSER::Meta::Source::Location < Hamster::Vector
   # @param [Enumerable<Method>] methods
   #   Methods you want the source locations for.
   # 
-  # @param [Boolean] only_valid:
+  # @param [Boolean] only_valid
   #   When `true` filter the results to only those that are {#valid?}.
   # 
   # @return [Hash<Symbol, NRSER::Meta::Source::Location>]

data/lib/nrser/props.rb

@@ -1,12 +1,36 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# ========================================================================
+
+# Project / Package
+# ------------------------------------------------------------------------
+
 require_relative './props/class_methods'
 require_relative './props/instance_methods'
 
 
+# Refinements
+# ========================================================================
+
 require 'nrser/refinements/types'
 using NRSER::Types
 
 
-module NRSER::Props
+# Namespace
+# ========================================================================
+
+module  NRSER
+
+
+# Definitions
+# ========================================================================
+
+# @todo
+#   This really needs a write-up... but it's not a very simple thing.
+# 
+module Props
   DEFAULT_CLASS_KEY = '__class__';
   
   def self.included base
@@ -25,7 +49,8 @@ module NRSER::Props
   # @param [Hash<String, Object>] data
   #   Data hash to load from.
   # 
-  # @param
+  # @param [String] class_key
+  #   The key name to look for the class name in.
   # 
   # @return [NRSER::Props::Props]
   #   Instance of a propertied class.
@@ -84,4 +109,10 @@ module NRSER::Props
     klass.from_data data
     
   end # .UNSAFE_load_instance_from_data
-end
+end # module Props
+
+
+# /Namespace
+# ========================================================================
+
+end # module NRSER

data/lib/nrser/props/class_methods.rb

@@ -126,7 +126,8 @@ module NRSER::Props::ClassMethods
   
   # Get an instance from a source.
   # 
-  # @experimental
+  # @status
+  #   Experimental
   # 
   # @param [self | String | Hash] source
   # @return [self]

data/lib/nrser/props/instance_methods.rb

@@ -69,7 +69,7 @@ module NRSER::Props::InstanceMethods
   # end # #initialize_props
   
   
-  # @param [Proc<(KEY, CURRENT, UPDATE) => VALUE>] &block
+  # @param [Proc<(KEY, CURRENT, UPDATE) => VALUE>] block
   #   Optional block to handle conflicts.
   # 
   def merge other, &block
@@ -87,10 +87,10 @@ module NRSER::Props::InstanceMethods
   
   # Create a new hash with property names mapped to values.
   # 
-  # @param [Boolean] only_own:
+  # @param [Boolean] only_own
   #   When `true`, don't include parent properties.
   # 
-  # @param [Boolean] only_primary:
+  # @param [Boolean] only_primary
   #   When `true`, don't include sourced properties.
   # 
   # @return [Hash<Symbol, Object>]
@@ -118,16 +118,16 @@ module NRSER::Props::InstanceMethods
   # supports symbol values, they have poor portability across languages,
   # and they mean the same thing in this situation.
   # 
-  # @param [Boolean] only_own:
+  # @param [Boolean] only_own
   #   When `true`, don't include parent properties.
   # 
-  # @param [Boolean] only_primary:
+  # @param [Boolean] only_primary
   #   When `true`, don't include sourced properties.
   # 
-  # @param [Boolean] add_class:
+  # @param [Boolean] add_class
   #   Add a special key with the class' name as the value.
   # 
-  # @param [String] class_key:
+  # @param [String] class_key
   #   Name for special class key.
   # 
   # @return [Hash<String, *>]
@@ -158,7 +158,7 @@ module NRSER::Props::InstanceMethods
   
   # Get a JSON {String} encoding the instance's data.
   # 
-  # @param [Array] *args
+  # @param [Array] args
   #   I really don't know. `#to_json` takes at last one argument, but I've
   #   had trouble finding a spec for it :/
   # 
@@ -171,7 +171,7 @@ module NRSER::Props::InstanceMethods
   
   # Get a YAML {String} encoding the instance's data.
   # 
-  # @param [Array] *args
+  # @param [Array] args
   #   I really don't know... whatever {YAML.dump} sends to it i guess.
   # 
   # @return [String]