nrser 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e9a0b7b61d0a481af1ca35a8eb86e7ab13aff165
-  data.tar.gz: e7c16292a7f5ccfa34ce0e490a7f91313f9e34e5
+  metadata.gz: c4c0b136095e4afd7f800b70365fef71ab0d6aa8
+  data.tar.gz: 0e7ae07d35167aef235790e048469175e278678d
 SHA512:
-  metadata.gz: e085701c29d0a89e2983734e8a2d120fe1d03248cf2d8bf5644761f1e00c5fd8d20bcf676a09785b312cb85c81cd1203330d5011ffcf956916f95dae3cdec16f
-  data.tar.gz: 68bd8090335751c9ee51f2026c33d23acecdb4faad507b89879fe036fb3758f79a3ba934682a26a6613601ce36b129bd3048ee62613b8751e0089f0d32cf4b58
+  metadata.gz: dca7159d865ba58bb26a0fe3a24f4cdab90c09416509cc7f7d466aad6c5a23dd5fa6f5f0d35b4adb9a6d2e93c9ea52f03f8f63b03f237e5e3cabc3374f258d5f
+  data.tar.gz: 4de1a2e02822d68a529f37ce1bcf53f25c4f8100284fb841c3bf254509d0f0a85adacdc823c1a857da5de7f0d8c9911214bc3e1ab4984d576a468aaba3646d75

data/lib/nrser/log/logger.rb

@@ -64,39 +64,161 @@ class NRSER::Log::Logger < SemanticLogger::Logger
   end # class Catcher
   
   
-  class Notifier
-    
-    # Construction
-    # ========================================================================
-    
-    # Instantiate a new `Notifier`.
-    # 
-    # @param [NRSER::Log::Logger] logger
-    #   The logger to use if the block raises.
-    # 
-    # @param [*] on_fail:
-    #   Value to return when `&block` raises.
-    # 
-    def initialize logger
-      @logger = logger
-    end # #initialize
+  # Under JRuby a java exception is not a Ruby Exception
+  #   
+  #   Java::JavaLang::ClassCastException.new.is_a?(Exception) => false
+  # 
+  def self.is_exception? value
+    value.is_a?( Exception) ||
+      [:backtrace, :message].all? { |name| value.respond_to? name }
+  end
+  
+  
+  # Normalizes the valid argument formats to {SemanticLogger::Logger}'s
+  # "standard logging methods" into a keywords hash.
+  # 
+  # By "standard logging methods", we mean {SemanticLogger::Logger#debug},
+  # {SemanticLogger::Logger#info}, etc., as detailed in the
+  # [Semantic Logger API][] documentation.
+  # 
+  # [Semantic Logger API]: https://rocketjob.github.io/semantic_logger/api.html
+  # 
+  # Semantic Logger documents the standard logging methods API as
+  # 
+  #     log.info(message, payload_or_exception = nil, exception = nil, &block)
+  # 
+  # or
+  # 
+  #     logger.info(
+  #       message: String?,
+  #       payload: Hash?,
+  #       exception: Object?,
+  #       **metric_keywords
+  #     )
+  # 
+  # Which means that the hash returned by this method can be used as the
+  # argument to the standard logging methods:
+  # 
+  #     def proxy_info_call *args, &block
+  #       logger.info **NRSER::Log::Logger.args_to_kwds( *args ), &block
+  #     end
+  # 
+  # This makes this method very useful when pre-processing log call arguments,
+  # as is done in {NRSER::Log::Plugin} before passing the resulting keywords
+  # to {NRSER::Log::Plugin#call} because the hash this method returns is much
+  # easier to work with than the standard logging methods' multiple valid
+  # argument formats.
+  # 
+  # @param [Array] *args
+  #   Valid arguments for {SemanticLogger::Logger#debug}, etc. - see notes
+  #   above.
+  # 
+  # @return [Hash<Symbol, Object>]
+  #   Always has the following keys (**all** of which can have `nil` value):
+  #   
+  #   -   `message: String?` - we don't actually check that it's a {String},
+  #       but that seems to be pretty much what Semantic Logger expects.
+  #       
+  #   -   `payload: Hash?` - A hash of names to values to log. By convention
+  #       names are {Symbol}, though I'm not sure what happens if they are not.
+  #       
+  #   -   `exception: Object?` - An error to log. This will be an {Exception}
+  #       in MRI. In JRuby, and perhaps elsewhere, they won't be, but they
+  #       should always respond to `#message` and `#backtrace`.
+  #       
+  #   -   `metric: Object?` -
+  # 
+  def self.args_to_kwds *args
+    log_kwds = {
+      message: nil,
+      payload: nil,
+      exception: nil,
+      metric: nil,
+    }
     
+    case args.length
+    when 0
+      # pass - they all stay `nil` (which it seems SemLog allows, so we'll
+      # stick to it)
     
-    # Instance Methods
-    # ========================================================================
+    when 1
+      case args[0]
+      when Hash
+        if [:message, :payload, :exception, :metric].
+              any? { |key| args[0].key? key }
+          log_kwds = args[0]
+        else
+          # It's the payload
+          log_kwds[:payload] = args[0]
+        end
+      else
+        if is_exception? args[0]
+          # It's the exception
+          log_kwds[:exception] = args[0]
+        else
+          # It's got to be the message
+          log_kwds[:message] = args[0]
+        end
+      end
     
-    SemanticLogger::LEVELS.each do |level|
-      define_method level do |message = nil, payload = nil, &block|
-        begin
-          block.call
-        rescue Exception => error
-          @logger.send level, message, payload, error
-          @on_fail
+    when 2
+      if args[0].is_a? Hash
+        log_kwds[:payload] = args[0]
+        log_kwds[:exception] = args[1]
+      else
+        log_kwds[:message] = args[0]
+        
+        if args[1].is_a? Hash
+          log_kwds[:payload] = args[1]
+        else
+          log_kwds[:exception] = args[1]
         end
       end
+    
+    when 3
+      log_kwds[:message] = args[0]
+      log_kwds[:payload] = args[1]
+      log_kwds[:exception] = args[2]
+    
+    else
+      raise NRSER::ArgumentError.new \
+        "Too many args dude - max 3",
+        args: args
+      
     end
     
-  end
+    log_kwds
+    
+  end # .normalize_log_args
+  
+  
+  # Install a plugin, dynamically adding it's
+  # {NRSER::Log::Plugin.method_name} instance method.
+  # 
+  # @param [Class<NRSER::Log::Plugin>] plugin_class
+  #   The plugin class to add.
+  # 
+  # @return [nil]
+  # 
+  # @raise [NRSER::ConflictError]
+  #   If this class already has an instance method defined with the name
+  #   returned from `plugin_class.method_name`.
+  # 
+  def self.plugin plugin_class
+    method_name = plugin_class.method_name
+    
+    if instance_methods.include? method_name.to_sym
+      raise NRSER::ConflictError.new \
+        "Can not install", plugin_class.safe_name,
+        "Logger plugin: instance method", method_name, "already defined"
+    end
+    
+    define_method method_name do |*args, &block|
+      plugin_class.new self, *args, &block
+    end
+    
+    nil
+  end # .plugin
   
   
   # Attributes
@@ -185,6 +307,41 @@ class NRSER::Log::Logger < SemanticLogger::Logger
   # Instance Methods
   # ========================================================================
   
+  # Log message at the specified level
+  def build_log level,
+                index,
+                message = nil,
+                payload = nil,
+                exception = nil,
+                &block
+    log        = SemanticLogger::Log.new name, level, index
+    should_log =
+      if payload.nil? && exception.nil? && message.is_a?( Hash )
+        # Check if someone just logged a hash payload instead of meaning to call semantic logger
+        if  message.key?( :message ) ||
+            message.key?( :payload ) ||
+            message.key?( :exception ) ||
+            message.key?( :metric )
+          log.assign message
+        else
+          log.assign_positional nil, message, nil, &block
+        end
+      else
+        log.assign_positional message, payload, exception, &block
+      end
+    
+    # Log level may change during assign due to :on_exception_level
+    [ log, should_log && should_log?( log ) ]
+  end
+  
+  
+  # Log message at the specified level
+  # def log_internal *args, &block
+  #   log, should_log = build_log *args
+  #   self.log( log ) if should_log
+  # end
+  
+  
   # A sweet way to try something and just log any {Exception}.
   # 
   # Useful for situations where the operation is question is not necessary

data/lib/nrser/log/plugin.rb

@@ -0,0 +1,153 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Need {SemanticLogger::Logger}
+require 'semantic_logger'
+
+
+# Refinements
+# =======================================================================
+
+
+# Namespace
+# =======================================================================
+
+module  NRSER
+module  Log
+
+
+# Definitions
+# =======================================================================
+
+# Abstract base class that wraps a {NRSER::Log::Logger} and exposes the
+# level logging methods - `#debug`, `#info`, etc. - routing those calls
+# through it's {#call} method and on to the logger's method, allowing
+# concrete subclasses to hook into those calls and provide additional
+# functionality and logic.
+# 
+# Convention is
+# 
+# @abstract
+# 
+# @see NRSER::Log::Logger::Catcher
+# @see NRSER::Log::Logger::Notifier
+# 
+# @todo
+#   Make plugins "stackable".
+#   
+#   Not sure if this example in particular would make any sense, but you can
+#   get the idea:
+#   
+#       logger.notify.catcher.warn
+# 
+class Plugin
+  
+  # Class Methods
+  # ========================================================================
+  
+  # The {NRSER::Log::Logger} method name that will create plugin instances.
+  # 
+  # Looks for the `@method_name` class instance variable, and defaults to
+  # `safe_name.demodulize.underscore` if that is not found.
+  # 
+  # @return [Symbol | String]
+  # 
+  def self.method_name
+    @method_name || safe_name.demodulize.underscore
+  end # .method_name
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # The wrapped logger instance.
+  # 
+  # @return [NRSER::Log::Logger]
+  #     
+  attr_reader :logger
+  
+  
+  # Construction
+  # ========================================================================
+  
+  # Instantiate a new plugin instance.
+  # 
+  # @param [NRSER::Log::Logger] logger
+  #   The wrapper logger instance.
+  # 
+  def initialize logger
+    @logger = logger
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # This is where realizing subclasses can hook into log calls.
+  # 
+  # This base implementation just calls the `level` method on {#logger}
+  # with the `args` and `block`.
+  # 
+  # @note
+  #   Though the logging methods don't use a block at this time, it's there
+  #   for completeness and possible futures.
+  # 
+  # @param [Symbol] level:
+  #   The log level of the call; one of {SemanticLogger::LEVELS}.
+  # 
+  # @param [String?] message:
+  #   Log message.
+  # 
+  # @param [Hash?] payload:
+  #   Map of names to values to log.
+  # 
+  # @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:
+  #   I don't know what this is. I found it in the SemLog code.
+  # 
+  # @param [Proc] &block
+  #   Block to pass to the {#logger}'s `level` method. Not currently used
+  #   (see note above).
+  # 
+  def call level:, message:, payload:, exception:, metric:, &block
+    logger.send \
+      level,
+      message: message,
+      payload: payload,
+      exception: exception,
+      metric: metric,
+      &block
+  end
+  
+  
+  # Dynamically define each logging method.
+  SemanticLogger::LEVELS.each do |level|
+    define_method level do |*args, &block|
+      call level: level, **NRSER::Log::Logger.args_to_kwds( *args ), &block
+    end
+  end
+  
+  
+  # @return [String]
+  #   Short string description of the instance.
+  def to_s
+    "#<#{ self.class.safe_name } #{ logger }>"
+  end
+  
+end # class Plugin
+
+
+# /Namespace
+# =======================================================================
+
+end # module Log
+end # module NRSER

data/lib/nrser/types/bounded.rb

@@ -1,7 +1,4 @@
-require 'nrser/refinements'
 require 'nrser/types/type'
-
-using NRSER
   
 module NRSER::Types
   class Bounded < NRSER::Types::Type

data/lib/nrser/types/is_a.rb

@@ -1,6 +1,4 @@
-require 'nrser/refinements'
 require 'nrser/types/type'
-using NRSER
 
 module NRSER::Types
   # Type satisfied by class membership (or mixin presence for modules).

data/lib/nrser/types/numbers.rb

@@ -1,10 +1,8 @@
-require 'nrser/refinements'
 require 'nrser/types/type'
 require 'nrser/types/is_a'
 require 'nrser/types/combinators'
 require 'nrser/types/bounded'
 
-using NRSER
   
 module NRSER::Types
   # Parse a string into a number.

data/lib/nrser/version.rb

@@ -18,7 +18,7 @@ module NRSER
   # 
   # @return [String]
   # 
-  VERSION = '0.3.5'
+  VERSION = '0.3.6'
   
   
   module Version

data/spec/lib/nrser/functions/merge_by_spec.rb

@@ -1,9 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
-
 # NRSER.merge_by
 # ========================================================================
 # 

data/spec/lib/nrser/functions/tree/each_branch_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 describe "NRSER.each_branch" do
   
   subject { NRSER.method :each_branch }
@@ -65,7 +60,7 @@ describe "NRSER.each_branch" do
         input = [:x, :y, :z]
         result = {}
         super().call( input ) { |index, value|
-          result[index] = value 
+          result[index] = value
         }
         result
       }
@@ -79,4 +74,3 @@ describe "NRSER.each_branch" do
   end # called with a block
   
 end # NRSER.each_branch
-

data/spec/lib/nrser/functions/tree/map_branch_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 describe "NRSER.map_branches" do
 # ========================================================================
   

data/spec/lib/nrser/functions/tree/map_tree_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 describe_method "NRSER.map_tree" do
 # ========================================================================
   

data/spec/lib/nrser/functions/tree/transform_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 describe "NRSER.transform" do
   subject { NRSER.transform tree, source }
   

data/spec/lib/nrser/functions/tree/transformer_spec.rb

@@ -1,10 +1,3 @@
-# Refinements
-# =======================================================================
-
-require 'nrser/refinements'
-using NRSER
-
-
 # Examples
 # =====================================================================
 
@@ -135,7 +128,7 @@ describe_method "NRSER.transformer" do
             users: {
               { contact_id: address.parent.id } => {
                 addresses: {
-                  { 
+                  {
                     address_id: address.id } => {
                     district:   address[:address],
                     line_1:     address[:street2],
@@ -176,4 +169,3 @@ describe_method "NRSER.transformer" do
   
   
 end # NRSER.transform
-

data/spec/lib/nrser/op/message_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 
@@ -18,13 +13,13 @@ describe NRSER::Message, type: :class do
         
         describe_called_with NRSER::Message.new( :length ) do
           it { is_expected.to eq [0, 1, 2] }
-        end # called with 
+        end # called with
         
         describe_called_with NRSER::Message.new( :first ) do
           it { is_expected.to eq [nil, 1, 1] }
         end # called with :first
         
-      end # enum 
+      end # enum
       
     end # mapping an Enumerable using &message
     

data/spec/lib/nrser/refinements/format_exception_spec.rb

@@ -1,11 +1,6 @@
-require 'spec_helper'
-require 'nrser/refinements'
-
-using NRSER
-
 describe "NRSER.format_exception" do
   let(:error) {
-    begin 
+    begin
       raise StandardError.new "blah blah blah"
     rescue Exception => e
       e
@@ -17,4 +12,4 @@ describe "NRSER.format_exception" do
     expect( str ).to start_with "blah blah blah (StandardError):"
     expect( str.lines.drop(1) ).to all( start_with '  ' )
   end
-end
+end

data/spec/lib/nrser/refinements/indent_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-require 'nrser/refinements'
-
-using NRSER
-
 describe "NRSER.indent" do
   it "refines String to add indent" do
     expect(

data/spec/lib/nrser/refinements/pathname_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-require 'nrser/refinements'
-
-using NRSER
-
 describe 'Pathname' do
   
   describe '#start_with?' do

data/spec/lib/nrser/types/pairs_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 
@@ -38,4 +33,3 @@ describe "NRSER::Types.hash_pair" do
 end # NRSER::Types.hash_pair
 
 # ************************************************************************
-

data/spec/lib/nrser/types/strings_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 

data/spec/lib/nrser/types/symbols_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 

data/spec/lib/nrser/types/tuples_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 

data/spec/lib/nrser/types_spec.rb

@@ -1,8 +1,3 @@
-require 'spec_helper'
-
-require 'nrser/refinements'
-using NRSER
-
 require 'nrser/refinements/types'
 using NRSER::Types
 
@@ -203,4 +198,4 @@ describe NRSER::Types do
     end
   end # #from_repr
   
-end # QB::Types
+end # QB::Types

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nrser
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-25 00:00:00.000000000 Z
+date: 2018-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hamster
@@ -331,7 +331,7 @@ files:
 - lib/nrser/log/formatters/mixin.rb
 - lib/nrser/log/logger.rb
 - lib/nrser/log/mixin.rb
-- lib/nrser/log/notify.rb
+- lib/nrser/log/plugin.rb
 - lib/nrser/mean_streak.rb
 - lib/nrser/mean_streak/document.rb
 - lib/nrser/message.rb

data/lib/nrser/log/notify.rb

@@ -1,94 +0,0 @@
-# encoding: UTF-8
-# frozen_string_literal: true
-
-# Requirements
-# =======================================================================
-
-# Stdlib
-# -----------------------------------------------------------------------
-
-# Deps
-# -----------------------------------------------------------------------
-
-# Project / Package
-# -----------------------------------------------------------------------
-
-# Need {NRSER::LazyAttr} decorator.
-require 'nrser/meta/lazy_attr'
-
-
-# Namespace
-# =======================================================================
-
-module  NRSER
-module  Log
-
-
-# Definitions
-# =======================================================================
-
-# Abstraction to attempt to notify interactive users.
-# 
-module Notify
-  
-  +NRSER::LazyAttr
-  # Is the `terminal-notifier` gem available?
-  # 
-  # [terminal-notifier][] is not an NRSER dependency since it does not make
-  # sense for many systems and situations. It must be installed separately.
-  # 
-  # [terminal-notifier]: https://rubygems.org/gems/terminal-notifier
-  # 
-  # Tests by trying to `require` it.
-  # 
-  # @return [Boolean]
-  # 
-  def self.terminal_notifier?
-    begin
-      require 'terminal-notifier'
-    rescue LoadError => error
-      false
-    else
-      true
-    end
-  end # .terminal_notifier?
-  
-  
-  +NRSER::LazyAttr
-  # Can we send notification to the user?
-  # 
-  # Right now, only {.terminal_notifier?} is tested, but we can add more
-  # options in the future.
-  # 
-  # @return [Boolean]
-  # 
-  def self.available?
-    terminal_notifier?
-  end # .available?
-  
-  
-  # Send a notification to the use *if* notifications are {.available?}.
-  # 
-  # 
-  def self.notify *args, &block
-    return false unless available?
-    
-    notify! *args, &block
-  end
-  
-  
-  def self.notify! *args, &block
-    require 'terminal-notifier'
-    
-    TerminalNotifier.notify *args, &block
-  end
-  
-  
-end # module Notify
-
-
-# /Namespace
-# =======================================================================
-
-end # module Log
-end # module NRSER