nrser 0.2.0.pre.3 → 0.2.0

data/lib/nrser/logging.rb

@@ -0,0 +1,353 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+require 'semantic_logger'
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './logging/formatters'
+require_relative './logging/appender'
+
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Mix in {.logger} and {#logger} to NRSER for functions to use
+  include SemanticLogger::Loggable
+  
+  # Unified logging support via {SemanticLogger}.
+  # 
+  # @see https://rocketjob.github.io/semantic_logger/index.html
+  # 
+  module Logging
+    
+    # Constants
+    # ============================================================================
+    
+    # Include this guy in modules and classes to add `.logger` and `#logger` methods
+    # that point to their own named logger.
+    # 
+    # Right now, just points to {SemanticLogger::Loggable}, but may expand on that
+    # some time in the future, such as to add `.on`/`#on` methods like the old
+    # `NRSER::Logger` had, etc.
+    # 
+    # @see http://www.rubydoc.info/gems/semantic_logger/SemanticLogger/Loggable
+    # 
+    # @return [Module]
+    # 
+    Mixin = SemanticLogger::Loggable
+    
+    
+    # Mixins
+    # ============================================================================
+    
+    # Mix in {.logger} and {#logger}
+    include Mixin
+    
+    extend SingleForwardable
+    
+    
+    # Delegation
+    # ============================================================================
+     
+    def_single_delegators(
+      SemanticLogger,
+      :application,
+      :application=,
+      :[],
+      # NOTE  These are funky due to different in SemLog's int level and Ruby
+      #       stdlib / Rails logger int levels, so omit for now.
+      #
+      # :index_to_level,
+      # :level_to_index
+    )
+    
+    
+    # Module Attributes
+    # ============================================================================
+    
+    @__mutex = Mutex.new
+    
+    
+    # Module (Class) Methods
+    # =====================================================================
+    
+    # Normalize a level name or number to a symbol, raising if it's not valid.
+    # 
+    # Relies on Semantic Logger's "internal" {SemanticLogger.level_to_index}
+    # method.
+    # 
+    # @see https://github.com/rocketjob/semantic_logger/blob/97247126de32e6ecbf74cbccaa3b3732768d52c5/lib/semantic_logger/semantic_logger.rb#L454
+    # 
+    # @param [Symbol | String | Integer]
+    #   Representation of a level in one of the following formats:
+    #   
+    #   1.  {Symbol} - verified as member of {SemanticLogger::LEVELS} and
+    #       returned.
+    #    
+    #   2.  {String} - accepts string representations of the level symbols,
+    #       case insensitive.
+    #   
+    #   3.  {Integer} - interpreted as a Ruby StdLib Logger / Rails Logger
+    #       level, which are **different** than Semantic Logger's!
+    # 
+    # @return [:trace | :debug | :info | :warn | :error | :fatal]
+    #   Log level symbol.
+    # 
+    # @raise
+    #   When `level` is invalid.
+    # 
+    def self.level_sym_for level
+      if SemanticLogger::LEVELS.include? level
+        level
+      else
+        SemanticLogger.index_to_level SemanticLogger.level_to_index( level )
+      end
+    end
+    
+    
+    # Global / default log level, which we always normalize to a symbol.
+    # 
+    # @return [:trace | :debug | :info | :warn | :error | :fatal]
+    # 
+    def self.level
+      level_sym_for SemanticLogger.default_level
+    end
+    
+    
+    def self.level_index
+      SemanticLogger.default_level_index
+    end
+    
+    
+    # Set the global default log level.
+    # 
+    # @param level  (see .level_sym_for)
+    # @return       (see .level_sym_for)
+    # @raise        (see .level_sym_for)
+    #   
+    def self.level= level
+      SemanticLogger.default_level = level_sym_for level
+    end
+    
+    
+    # Try to set the level, logging a warning and returning `nil` if it fails.
+    # 
+    # @param level (see .level=)
+    # 
+    # @return [Symbol]
+    #   The level symbol if it was set successfully.
+    # 
+    # @return [nil]
+    #   If the set failed (also logs a warning).
+    # 
+    def self.try_set_level level
+      begin
+        self.level = level
+      rescue Exception => error
+        logger.warn "Unable to set level, probably bad value",
+          level: level,
+          error: error
+        nil
+      end
+    end # .try_set_level
+    
+    
+    def self.level_from_ENV prefix:
+      if NRSER.truthy? ENV["#{ prefix }_TRACE"]
+        return :trace
+      elsif NRSER.truthy? ENV["#{ prefix }_DEBUG"]
+        return :debug
+      end
+      
+      level = ENV["#{ prefix }_LOG_LEVEL"]
+      
+      unless level.nil? || level == ''
+        return level
+      end
+      
+      nil
+    end
+    
+    
+    # Setup logging.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [nil]
+    # 
+    def self.setup! level: nil,
+                    dest: nil,
+                    sync: false,
+                    say_hi: :debug,
+                    application: 'NRSER',
+                    env_var_prefix: nil
+      
+      unless @__mutex.try_lock
+        raise ThreadError, <<~END
+          Mutex is already held.
+          
+          You should pretty generally NOT have multiple threads trying to
+          setup logging at once or re-enter {NRSER::Logging.setup}!
+        END
+      end
+      
+      # Wrap around everything to make sure we release the mutex
+      begin
+        self.appender = dest unless dest.nil?
+        
+        # Force synchronous logging
+        sync! if sync
+        
+        # If we didn't receive a level, check the ENV
+        if level.nil?
+          if env_var_prefix.nil?
+            env_var_prefix = application.gsub( /[^a-zA-Z0-0_]+/, '_' ).upcase
+          end
+          
+          level = level_from_ENV prefix: env_var_prefix
+        end
+        
+        # If we ended up with a level, try to set it (will only log a warning
+        # if it fails, not raise, which could crash things on boot)
+        try_set_level level unless level.nil?
+        
+        self.application = application unless application.nil?
+        
+      ensure
+        # Make sure we release the mutex; don't need to hold it for the rest
+        @__mutex.unlock
+      end
+      
+      will_say_hi = case say_hi
+      when true, false
+        say_hi
+      when Symbol, String, Fixnum
+        begin
+          level_index < SemanticLogger.level_to_index( say_hi )
+        rescue Exception => error
+          logger.warn "Bad `say_hi` kwd in {NRSER::Logging.setup}",
+            say_hi: say_hi,
+            expected: "Symbol, String, or Fixnum representing log level",
+            error: error
+            
+          false
+        end
+      else
+        logger.warn "Bad `say_hi` kwd in {NRSER::Logging.setup}",
+          say_hi: say_hi,
+          expected: [true, false, Symbol, String, Fixnum]
+        
+        false
+      end
+      
+      if will_say_hi
+        logger.info "Hi! Logging is setup",
+          level: self.level,
+          dest: dest,
+          sync: sync
+      end
+      
+      nil
+    rescue Exception => error
+      # Suppress errors in favor of a warning
+      
+      logger.warn \
+        message: "Error setting up logging",
+        payload: {
+          args: {
+            level: level,
+            dest: dest,
+            env_var_prefix: env_var_prefix,
+            say_hi: say_hi,
+          },
+        },
+        exception: error
+      
+      nil
+    end # .setup!
+    
+    
+    # Call {.setup!} with some default keywords that are nice for CLI apps.
+    # 
+    # @param  (see .setup!)
+    # @return (see .setup!)
+    # 
+    def self.setup_for_cli! dest: $stderr,
+                            sync: true,
+                            **kwds
+      setup! dest: dest, sync: sync, **kwds
+    end # .setup_for_cli!
+    
+    
+    # Hack up SemanticLogger to do sync logging in the main thread
+    # 
+    # @return [nil]
+    # 
+    def self.sync!
+      # Create a {Locd::Logging::Appender::Sync}, which implements the
+      # {SemanticLogger::Appender::Async} interface but just forwards directly
+      # to it's appender in the same thread, and point it where
+      # {SemanticLogger::Processor.instance} (which is an Async) points.
+      # 
+      sync_appender = NRSER::Logging::Appender::Sync.new \
+        appender: SemanticLogger::Processor.instance.appender
+      
+      # Swap our sync in for the async
+      SemanticLogger::Processor.instance_variable_set \
+        :@processor,
+        sync_appender
+      
+      nil
+    end
+    
+    
+    # The current "main" appender (destination), if any.
+    # 
+    # This is just to simplify things in simple cases, you can always still
+    # add multiple appenders.
+    # 
+    # @return [SemanticLogger::Subscriber | nil]
+    # 
+    def self.appender
+      @appender
+    end
+    
+    
+    def self.appender= value
+      # Save ref to current appender (if any) so we can remove it after adding
+      # the new one.
+      old_appender = @appender
+      
+      @appender = case value
+      when Hash
+        SemanticLogger.add_appender value
+      when String, Pathname
+        SemanticLogger.add_appender file_name: value.to_s
+      else
+        SemanticLogger.add_appender \
+          io: value,
+          formatter: NRSER::Logging::Formatters::Color.new
+      end
+      
+      # Remove the old appender (if there was one). This is done after adding
+      # the new one so that failing won't result with no appenders.
+      SemanticLogger.remove_appender( old_appender ) if old_appender
+      
+      @appender
+    end
+    
+    
+  end # module Logging
+end # module NRSER

data/lib/nrser/refinements/module.rb

@@ -0,0 +1,5 @@
+module NRSER
+  refine Module do
+    include NRSER::Ext::Module
+  end
+end

data/lib/nrser/refinements.rb

@@ -14,3 +14,4 @@ require_relative './refinements/open_struct'
 require_relative './refinements/enumerator'
 require_relative './refinements/symbol'
 require_relative './refinements/types'
+require_relative './refinements/module'

data/lib/nrser/rspex/described.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+# 
+class NRSER::RSpex::Described
+  
+  # Constants
+  # ======================================================================
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  
+  # Attributes
+  # ======================================================================
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `NRSER::RSpex::Described`.
+  def initialize **metadata
+    
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  
+end # class NRSER::RSpex::Described
+
+
+
+
+# @todo document NRSER::RSpex::Described::Class class.
+class NRSER::RSpex::Described::Class < NRSER::RSpex::Described
+  def initialize class:
+  end
+  
+  
+  def location
+    # Get a reasonable file and line for the class
+    file, line = klass.
+      # Get an array of all instance methods, excluding inherited ones
+      # (the `false` arg)
+      instance_methods( false ).
+      # Add `#initialize` since it isn't in `#instance_methods` for some
+      # reason
+      <<( :initialize ).
+      # Map those to their {UnboundMethod} objects
+      map { |sym| klass.instance_method sym }.
+      # Toss any `nil` values
+      compact.
+      # Get the source locations
+      map( &:source_location ).
+      # Get the first line in the shortest path
+      min_by { |(path, line)| [path.length, line] }
+      
+      # Another approach I thought of... (untested)
+      # 
+      # Get the path
+      # # Get frequency of the paths
+      # count_by { |(path, line)| path }.
+      # # Get the one with the most occurrences
+      # max_by { |path, count| count }.
+      # # Get just the path (not the count)
+      # first
+  end
+  
+  
+  def to_desc
+    
+  end
+end # class NRSER::RSpex::Described::Class

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

@@ -25,8 +25,8 @@ module NRSER::RSpex::ExampleGroup
   # @return [void]
   # 
   def describe_called_with *args, &body
-    describe_x_type  "called with", List(*args),
-      type: :invocation,
+    describe_x_type List(*args),
+      type: :called_with,
       subject_block: -> { super().call *args },
       &body
   end # #describe_called_with

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

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # @todo Document describe_class method.
+  # 
+  # @return [void]
+  # 
+  def describe_class  klass,
+                      *description,
+                      bind_subject: true,
+                      **metadata,
+                      &body
+    subject_block = if bind_subject
+      -> { klass }
+    end
+    
+    describe_x \
+      NRSER::RSpex::Format.md_code_quote( klass.name ),
+      *description,
+      type: :class,
+      metadata: {
+        **metadata,
+        class: klass,
+      },
+      subject_block: subject_block,
+      &body
+  end # #describe_class
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -11,7 +11,7 @@ module NRSER::RSpex::ExampleGroup
   #   @todo Document return value.
   # 
   def describe_instance *constructor_args, &body
-    describe_x_type ".new(", Args(*constructor_args), ")",
+    describe_x ".new", Args(*constructor_args),
       type: :instance,
       metadata: {
         constructor_args: constructor_args,

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

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # @todo Document describe_method method.
+  # 
+  # @return [void]
+  # 
+  def describe_method method_name, *description, **metadata, &body
+    # Due to legacy, we only auto-bind if the name is a symbol
+    # 
+    # TODO  Get rid of this
+    # 
+    subject_block = if method_name.is_a? Symbol
+      -> { super().method method_name }
+    end
+    
+    name_prefix = if  self.respond_to?( :metadata ) &&
+                      self.metadata.key?( :constructor_args )
+      '#'
+    else
+      '.'
+    end
+    
+    name_string = NRSER::RSpex::Format.md_code_quote \
+      "#{ name_prefix }#{ method_name }"
+    
+    # Create the RSpec example group context
+    describe_x name_string, *description,
+      type: :method,
+      metadata: {
+        **metadata,
+        method_name: method_name,
+      },
+      subject_block: subject_block,
+      &body
+  end # #describe_method
+  
+end # module NRSER::RSpex::ExampleGroup

data/lib/nrser/rspex/example_group.rb

@@ -194,24 +194,6 @@ module NRSER::RSpex::ExampleGroup
   end # #describe_module
   
   
-  def describe_class klass, bind_subject: true, **metadata, &block
-    description = "#{ NRSER::RSpex::PREFIXES[:class] } #{ klass.name }"
-    
-    describe(
-      description,
-      type: :class,
-      class: klass,
-      **metadata
-    ) do
-      if bind_subject
-        subject { klass }
-      end
-      
-      module_exec &block
-    end
-  end # #describe_class
-  
-  
   def describe_group title, **metadata, &block
     describe(
       "#{ NRSER::RSpex::PREFIXES[:group] } #{ title }",
@@ -223,22 +205,6 @@ module NRSER::RSpex::ExampleGroup
   end # #describe_class
   
   
-  def describe_method name, **metadata, &block
-    describe(
-      "#{ NRSER::RSpex::PREFIXES[:method] } #{ name }",
-      type: :method,
-      method_name: name,
-      **metadata
-    ) do
-      if name.is_a? Symbol
-        subject { super().method name }
-      end
-      
-      module_exec &block
-    end
-  end # #describe_method
-  
-  
   def describe_attribute symbol, **metadata, &block
     describe(
       "#{ NRSER::RSpex::PREFIXES[:attribute] } ##{ symbol }",
@@ -296,3 +262,5 @@ require_relative './example_group/describe_setup'
 require_relative './example_group/describe_use_case'
 require_relative './example_group/describe_instance'
 require_relative './example_group/describe_called_with'
+require_relative './example_group/describe_method'
+require_relative './example_group/describe_class'

data/lib/nrser/rspex/format.rb

@@ -76,8 +76,18 @@ module NRSER::RSpex::Format
   singleton_class.send :alias_method, :b, :bold
   
   
+  def self.rspec_syntax_highlighter
+    @rspec_syntax_highlighter ||= \
+      RSpec::Core::Formatters::SyntaxHighlighter.new RSpec.configuration
+  end
+  
+  
   def self.code string
-    pastel.yellow string
+    if string =~ /\A\#[a-zA-Z][a-zA-Z0-9_]*(?:\?|\!)?/
+      pastel.bold.blue string
+    else
+      rspec_syntax_highlighter.highlight string.lines
+    end
   end
   
   
@@ -98,10 +108,13 @@ module NRSER::RSpex::Format
   def self.prepend_type type, description
     return description if type.nil?
     
-    prefixes = RSpec.configuration.x_type_prefixes
+    # prefixes = RSpec.configuration.x_type_prefixes
+    # 
+    # prefix = prefixes[type] ||
+    #           pastel.magenta( i( type.to_s.upcase.gsub('_', ' ') ) )
     
-    prefix = prefixes[type] ||
-              pastel.magenta( i( type.to_s.upcase.gsub('_', ' ') ) )
+    # prefix = "*" + type.to_s.upcase.gsub('_', ' ') + "*"
+    prefix = pastel.magenta( i( type.to_s.upcase.gsub('_', ' ') ) )
     
     "#{ prefix } #{ description }"
   end # .format_type
@@ -127,13 +140,13 @@ module NRSER::RSpex::Format
         elsif part.is_a? String
           part
         else
-          short_s part
+          NRSER::RSpex.short_s part
         end
       }.
       join( ' ' ).
       squish.
       thru { |description|
-        mean_streak.render prepend_type( type, description )
+        prepend_type type, mean_streak.render( description )
       }
   end # .description
   

data/lib/nrser/rspex.rb

@@ -270,7 +270,7 @@ RSpec.configure do |config|
   config.x_type_prefixes = \
     NRSER::RSpex::PREFIXES
   
-  config.add_setting :x_style, default: :unicode
+  config.add_setting :x_style, default: :esc_seq
 end
 
 # Make available at the top-level