nrser 0.2.0.pre.3 → 0.2.0

data/lib/nrser/functions/module/source_locations.rb

@@ -0,0 +1,213 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+using NRSER
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # @!group Module Functions
+  # ==========================================================================
+  
+  
+  # @todo Document map_to_source_locations method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [Hash<#source_location, Array<(String?, Fixnum?)>?>]
+  #   Map of objects
+  # 
+  def self.map_to_source_locations methods
+    methods.assoc_to &:source_location
+  end # .map_to_source_locations
+  
+  
+  # Map class method {Methods} objects to the `#source_location` for `mod`
+  # class methods.
+  # 
+  # @see https://ruby-doc.org/core/Method.html#method-i-source_location
+  # 
+  # @param (see NRSER.class_method_objects_for)
+  # 
+  # @return [Hash<Symbol, Array<(String?, Fixnum?)>?>]
+  #   Hash mapping method name {Symbol}s to results of calling their
+  #   {Method#source_location}, which seems to be able to be:
+  #   
+  #   1.  `Array<(String, Fixnum)>` - two-entry array of file path,
+  #       line number.
+  #   
+  #   2.  `nil` - if this method was not defined in Ruby (C extension, etc.)
+  #       
+  #   3.  `Array<(nil, nil)>` - Not listed as a possibility in the docs, but
+  #       I swear I've seen it, so watch out.
+  # 
+  def self.class_method_source_locations_for *args
+    map_to_source_locations class_method_objects_for( *args )
+  end # .class_method_source_locations
+  
+  
+  # Map *own* (not inherited) class method {Methods} objects to the
+  # `#source_location` for `mod` class methods.
+  # 
+  # @see https://ruby-doc.org/core/Method.html#method-i-source_location
+  # 
+  # @param  (see .own_class_method_objects_for)
+  # @return (see .class_method_objects_for)
+  # 
+  def self.own_class_method_source_locations_for *args
+    map_to_source_locations own_class_method_objects_for( *args )
+  end # .own_class_method_source_locations_for
+  
+  
+  # Map instance method {Methods} objects to the `#source_location` for `mod`
+  # class methods.
+  # 
+  # @see https://ruby-doc.org/core/Method.html#method-i-source_location
+  # 
+  # @param (see .instance_method_objects_for)
+  # @return (see .class_method_source_locations_for)
+  # 
+  def self.instance_method_source_locations_for *args
+    map_to_source_locations instance_method_objects_for( *args )
+  end # .class_method_source_locations
+
+
+  # Map *own* (not inherited) class method {Methods} objects to the
+  # `#source_location` for `mod` class methods.
+  # 
+  # @see https://ruby-doc.org/core/Method.html#method-i-source_location
+  # 
+  # @param  (see NRSER.own_class_method_objects_for)
+  # @return (see NRSER.class_method_objects_for)
+  # 
+  def self.own_instance_method_source_locations_for *args
+    map_to_source_locations own_instance_methods_objects_for( *args )
+  end # .own_class_method_source_locations_for
+  
+  
+  # @todo Document method_source_locations_for method.
+  # 
+  # @param [type] mod
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.method_source_locations_for  mod,
+                                        include_super = false,
+                                        sort: true
+    class_method_source_locations_for(
+      mod,
+      include_super,
+      sort: sort,
+    ).
+      # map_keys { |name| ".#{ name }" }.
+      merge instance_method_source_locations_for(
+        mod,
+        include_super,
+        sort: sort,
+        # Think it makes sense to *always* include `#initialize` since at this
+        # point we're interested in where *all* the methods are, and that
+        # should def be included.
+        include_initialize: true,
+      ) # .map_keys { |name| "##{ name }" }
+  end # .method_source_locations_for
+  
+  
+  def self.own_method_source_locations_for  mod,
+                                            sort: true
+    method_source_locations_for \
+      mod,
+      false,
+      sort: sort
+  end # .method_source_locations_for
+  
+  
+  
+  # @todo Document module_source_locations method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.module_source_locations mod
+    # Get all the src locs for `mod`'s methods
+    own_method_source_locations_for( mod ).values.
+      # Filter out any that don't have full src loc info
+      reject { |src_loc| src_loc.nil? || src_loc.any?( &:nil? ) }
+  end # .module_source_locations
+  
+
+  
+  # Get a reasonable file and line for the class.
+  # 
+  # @param [Class] cls
+  #   Class to try and locate.
+  # 
+  # @return [Array<(String, Fixnum)>]
+  #   Two entry array; first entry is the string file path, second is the
+  #   line number.
+  # 
+  def self.module_source_location mod
+    # If any files end with the "canonical path" then use that. It's a path
+    # suffix
+    # 
+    #     "my_mod/sub_mod/some_class.rb"
+    # 
+    # the for a class
+    # 
+    #     MyMod::SubMod::SomeClass
+    # 
+    canonical_path_end = \
+      ActiveSupport::Inflector.underscore( mod.name ) + '.rb'
+    
+    # Get all the src locs for `mod`'s methods
+    src_locs = module_source_locations mod
+    
+    # Find first line in canonical path (if any)
+    canonical_path_src_loc = src_locs.
+      find_all { |(path, line)| path.end_with? canonical_path_end }.
+      min_by { |(path, line)| line }
+    
+    # If we found one, we're done!
+    return canonical_path_src_loc if canonical_path_src_loc
+    
+    raise "HERE"
+    
+    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 (TODO how/why?)
+      compact.
+      # Get the source locations
+      map( &:source_location ).
+      # Get rid of `[nil, nil]` results, which seems to come from C exts?
+      reject { |(path, line)| path.nil? || line.nil? }.
+      # 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 # .module_source_location
+  
+  # @!endgroup Module Functions
+  
+end # module NRSER

data/lib/nrser/functions/module.rb

@@ -0,0 +1,2 @@
+require_relative './module/methods'
+require_relative './module/source_locations'

data/lib/nrser/functions.rb

@@ -17,3 +17,4 @@ require_relative './functions/merge_by'
 require_relative './functions/tree'
 require_relative './functions/path'
 require_relative './functions/git'
+require_relative './functions/module'

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

@@ -0,0 +1,148 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Definitions
+# =======================================================================
+
+# Replacement for {SemanticLogger::Appender::Async} that implements the
+# same interface but just logs synchronously in the current thread.
+# 
+# Basically just implements the {SemanticLogger::Appender::Async} API,
+# returning mostly with fake / nonsense values, but it seems to work, and
+# just let's writes go strait through to the {#appender} (which is actually
+# a {SemanticLogger::Processor}).
+# 
+# Useful for CLI applications where you want to see output in sync with
+# operations.
+# 
+class NRSER::Logging::Appender::Sync
+  
+  # Mixins
+  # ============================================================================
+  
+  # Macros for forwarding to {#appender}
+  extend Forwardable
+  
+  
+  # 
+  # ============================================================================
+  
+  # The appender we forward to, which is a {SemanticLogger::Processor}
+  # in practice, since it wouldn't make any sense to wrap a regular
+  # appender in a Sync.
+  # 
+  # @return [SemanticLogger::Processor]
+  #     
+  attr_accessor :appender
+
+  # Forward methods that can be called directly
+  def_delegator :@appender, :name
+  def_delegator :@appender, :should_log?
+  def_delegator :@appender, :filter
+  def_delegator :@appender, :host
+  def_delegator :@appender, :application
+  def_delegator :@appender, :level
+  def_delegator :@appender, :level=
+  def_delegator :@appender, :logger
+  
+  # Added for sync
+  def_delegator :@appender, :log
+  def_delegator :@appender, :on_log
+  def_delegator :@appender, :flush
+  def_delegator :@appender, :close
+  
+  
+  # A fake {Queue} that just implements a {.size} method that returns `0`.
+  # 
+  # Sync appender doesn't need a queue, but Semantic Logger expects one, so
+  # telling it the length is always zero seems to make sense.
+  # 
+  class FakeQueue
+    # @return [0]
+    #   Fake queue is always empty.
+    def self.size
+      0
+    end
+  end # class FakeQueue
+  
+
+  # 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
+  def initialize  appender:, name: appender.class.name
+    @appender = appender
+  end
+  
+  # Needs to be there to support {SemanticLogger::Processor.queue_size},
+  # which gets the queue and returns it's size (which will always be zero
+  # for us).
+  # 
+  # We return {FakeQueue}, which only implements a `size` method that
+  # returns zero.
+  # 
+  # @return [#size]
+  # 
+  def queue; FakeQueue; end
+  
+  
+  # @return [-1]
+  #   Nonsense value meant to indicate there is no lag check interval.
+  def lag_check_interval; -1; end
+  
+  
+  # @raise [NotImplementedError]
+  #   Sync appender doesn't support setting lag check interval.
+  def lag_check_interval= value
+    raise NotImplementedError,
+      "Can't set `lag_check_interval` on Sync appender"
+  end
+  
+  
+  # @return [-1]
+  #   Nonsense value meant to indicate there is no lag threshold.
+  def lag_threshold_s; -1; end
+  
+  
+  # @raise [NotImplementedError]
+  #   Sync appender doesn't support setting log threshold.
+  def lag_threshold_s= value
+    raise NotImplementedError,
+      "Can't set `lag_threshold_s` on Sync appender"
+  end
+  
+  
+  # @return [false]
+  #   Sync appender is of course not size-capped.
+  def capped?; false; end
+
+  
+  # The {SemanticLogger::Appender::Async} worker thread is exposed via
+  # this method, which creates it if it doesn't exist and returns it, but
+  # it doesn't seem like the returned value is ever used; the method
+  # call is just invoked to start the thread.
+  # 
+  # Hence it seems to make most sense to just return `nil` since we don't
+  # have a thread, and figure out what to do if that causes errors (so far
+  # it seems fine).
+  #
+  # @return [nil]
+  # 
+  def thread; end
+  
+  
+  # @return [true]
+  #   Sync appender is always active
+  def active?; true; end
+
+end # class NRSER::Logging::Appender::Sync

data/lib/nrser/logging/appender.rb

@@ -0,0 +1,3 @@
+module NRSER::Logging::Appender; end
+
+require_relative './appender/sync'

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

@@ -0,0 +1,165 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+require 'awesome_print'
+require 'semantic_logger'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Logging; end
+module NRSER::Logging::Formatters; end
+
+
+# Definitions
+# =======================================================================
+
+class NRSER::Logging::Formatters::Color < ::SemanticLogger::Formatters::Color
+  
+  # Constants
+  # ======================================================================
+  
+  # ANSI escape sequence to start "Dark Gray" color.
+  # 
+  # @return [String]
+  # 
+  ANSI_ESC_DARK_GRAY = "\e[1;30m"
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  # @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
+    SemanticLogger::Formatters::Color::ColorMap.new(
+      debug: SemanticLogger::AnsiColors::MAGENTA,
+      trace: ANSI_ESC_DARK_GRAY,
+    )
+  end # .default_color_map
+  
+  
+  # Attributes
+  # ======================================================================
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `ColorFormatter`.
+  def initialize  ap: {multiline: true},
+                  color_map: self.class.default_color_map,
+                  time_format: ::SemanticLogger::Formatters::Base::TIME_FORMAT,
+                  log_host: false,
+                  log_application: false
+    super ap: ap,
+          color_map: color_map,
+          time_format: time_format,
+          log_host: log_host,
+          log_application: log_application
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  
+  # Upcase the log level.
+  # 
+  # @return [String]
+  # 
+  def level
+    "#{ color }#{ log.level.upcase }#{ color_map.clear }"
+  end
+  
+  
+  # Create the log entry text. Overridden to customize appearance -
+  # generally reduce amount of info and put payload on it's own line.
+  # 
+  # We need to replace *two* super functions, the first being
+  # [SemanticLogger::Formatters::Color#call][]:
+  # 
+  #     def call(log, logger)
+  #       self.color = color_map[log.level]
+  #       super(log, logger)
+  #     end
+  # 
+  # [SemanticLogger::Formatters::Color#call]: https://github.com/rocketjob/semantic_logger/blob/v4.2.0/lib/semantic_logger/formatters/color.rb#L98
+  # 
+  # which doesn't do all too much, and the next being it's super-method,
+  # [SemanticLogger::Formatters::Default#call][]:
+  #     
+  #     # Default text log format
+  #     #  Generates logs of the form:
+  #     #    2011-07-19 14:36:15.660235 D [1149:ScriptThreadProcess] Rails -- Hello World
+  #     def call(log, logger)
+  #       self.log    = log
+  #       self.logger = logger
+  #     
+  #       [time, level, process_info, tags, named_tags, duration, name, message, payload, exception].compact.join(' ')
+  #     end
+  # 
+  # [SemanticLogger::Formatters::Default#call]: https://github.com/rocketjob/semantic_logger/blob/v4.2.0/lib/semantic_logger/formatters/default.rb#L64
+  # 
+  # which does most the real assembly.
+  # 
+  # @param [SemanticLogger::Log] log
+  #   The log entry to format.
+  #   
+  #   See [SemanticLogger::Log](https://github.com/rocketjob/semantic_logger/blob/v4.2.0/lib/semantic_logger/log.rb)
+  # 
+  # @param [SemanticLogger::Logger] logger
+  #   The logger doing the logging (pretty sure, haven't checked).
+  #   
+  #   See [SemanticLogger::Logger](https://github.com/rocketjob/semantic_logger/blob/v4.2.0/lib/semantic_logger/logger.rb)
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def call log, logger
+    # SemanticLogger::Formatters::Color code
+    self.color = color_map[log.level]
+    
+    # SemanticLogger::Formatters::Default code
+    self.log    = log
+    self.logger = logger
+    
+    [
+      time, # annoyingly noisy and don't really need for local CLI app
+      level,
+      process_info,
+      tags,
+      named_tags,
+      duration,
+      name,
+    ].compact.join( ' ' ) +
+    "\n" +
+    [
+      message,
+      payload,
+      exception,
+    ].compact.join(' ') +
+    "\n" # I like extra newline to space shit out
+    
+  end # #call
+  
+  
+end # class Color

data/lib/nrser/logging/formatters.rb

@@ -0,0 +1 @@
+require_relative './formatters/color'