nrser 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c22fc11ecea67d2e92ae41a8cf469a7f33d9cf88
-  data.tar.gz: bed78e5268a47d2e8e64c1f124e6fedb8e8ca900
+  metadata.gz: e9a0b7b61d0a481af1ca35a8eb86e7ab13aff165
+  data.tar.gz: e7c16292a7f5ccfa34ce0e490a7f91313f9e34e5
 SHA512:
-  metadata.gz: 678f023739443e98fca66a347a4ce7e3077b0245ad75dfce625a2a53aa44e93cac9d65ddaf2662c93117427da054ebe53b6812d1ca9dc91182fbed41a80cda80
-  data.tar.gz: 47f21b60c61f23e5eff76c627d805ce62f60a9be852f02d0eee8fa95fb7c912f1581632d099408a2b9f8cff361829a301224537b2514fa641bcbc345b3d72117
+  metadata.gz: e085701c29d0a89e2983734e8a2d120fe1d03248cf2d8bf5644761f1e00c5fd8d20bcf676a09785b312cb85c81cd1203330d5011ffcf956916f95dae3cdec16f
+  data.tar.gz: 68bd8090335751c9ee51f2026c33d23acecdb4faad507b89879fe036fb3758f79a3ba934682a26a6613601ce36b129bd3048ee62613b8751e0089f0d32cf4b58

data/lib/nrser/core_ext/method/full_name.rb

@@ -0,0 +1,21 @@
+require_relative '../module/names'
+
+
+class Method
+  
+  # Returns the method's {#receiver} and {#name} in the common
+  # `A.cls_meth` / `A#inst_meth` format.
+  # 
+  def full_name
+    case receiver
+    when Module
+      "#{ receiver.safe_name }.#{ name }"
+    else
+      "#{ receiver.class.safe_name }##{ name }"
+    end
+  end
+  
+  # Use full name as a {Method}'s "summary"
+  alias_method :to_summary, :full_name
+  
+end # class Method

data/lib/nrser/core_ext/method.rb

@@ -0,0 +1 @@
+require_relative './method/full_name'

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

@@ -101,7 +101,8 @@ class Module
   def own_instance_method_locations sort: true,
                                     include_initialize: false,
                                     only_valid: false
-    instance_method_locations sort: sort,
+    instance_method_locations false,
+                              sort: sort,
                               include_initialize: include_initialize,
                               only_valid: only_valid
   end

data/lib/nrser/core_ext/unbound_method/full_name.rb

@@ -0,0 +1,16 @@
+require_relative '../module/names'
+
+
+class UnboundMethod
+  
+  # Instance Methods
+  # ========================================================================
+  
+  def full_name
+    # Need to string parse {#to_s}?!
+    raise NotImplementedError, "Haven't done this one yet"
+  end
+  
+  alias_method :to_summary, :full_name
+  
+end # class Method

data/lib/nrser/errors/nicer_error.rb

@@ -160,6 +160,8 @@ module NRSER::NicerError
   #   The formatted string for the segment.
   # 
   def format_message_segment segment
+    return segment.to_summary if segment.respond_to?( :to_summary )
+    
     return segment if String === segment
     
     # TODO  Do better!

data/lib/nrser/log/logger.rb

@@ -64,6 +64,41 @@ 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
+    
+    
+    # Instance Methods
+    # ========================================================================
+    
+    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
+        end
+      end
+    end
+    
+  end
+  
+  
   # Attributes
   # ========================================================================
   

data/lib/nrser/log/notify.rb

@@ -0,0 +1,94 @@
+# 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

data/lib/nrser/meta/lazy_attr.rb

@@ -0,0 +1,114 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+require 'method_decorators'
+
+
+# Namespace
+# =======================================================================
+
+module  NRSER
+
+
+# Definitions
+# =======================================================================
+
+# Store the result of an attribute method (no args) in an instance variable
+# of the same name and return that value on subsequent calls.
+# 
+class LazyAttr < MethodDecorators::Decorator
+  
+  # Get the instance variable name for a target method.
+  # 
+  # @param [Method] target_method
+  #   The method the decorator is decorating.
+  # 
+  # @return [String]
+  #   The name of the instance variable, ready to be provided to
+  #   `#instance_variable_set` (has `@` prefix).
+  # 
+  def self.instance_var_name target_method
+    name = target_method.name.to_s
+    
+    # Allow predicate methods by chopping off the `?` character.
+    # 
+    # Other stupid uses like `+` or whatever will raise when
+    # `#instance_variable_set` is called.
+    # 
+    name = name[0..-2] if name.end_with? '?'
+    
+    "@#{ name }"
+  end # .instance_var_name
+  
+  
+  # Execute the decorator.
+  # 
+  # @param [Method] target_method
+  #   The decorated method, already bound to the receiver.
+  #   
+  #   The `method_decorators` gem calls this `orig`, but I thought
+  #   `target_method` made more sense.
+  # 
+  # @param [*] receiver
+  #   The object that will receive the call to `target`.
+  #   
+  #   The `method_decorators` gem calls this `this`, but I thought `receiver`
+  #   made more sense.
+  #   
+  #   It's just `target.receiver`, but the API is how it is.
+  # 
+  # @param [Array] *args
+  #   Any arguments the decorated method was called with.
+  # 
+  # @param [Proc?] &block
+  #   The block the decorated method was called with (if any).
+  # 
+  # @return
+  #   Whatever `target_method` returns.
+  # 
+  def call target_method, receiver, *args, &block
+    unless target_method.parameters.empty?
+      raise NRSER::ArgumentError.new \
+        "{NRSER::LazyAttr} can only decorate methods with 0 params",
+        receiver: receiver,
+        target_method: target_method
+    end
+    
+    unless args.empty?
+      raise NRSER::ArgumentError.new \
+        "wrong number of arguments for", target_method,
+        "(given", args.length, "expected 0)",
+        receiver: receiver,
+        target_method: target_method
+    end
+    
+    unless block.nil?
+      raise NRSER::ArgumentError.new \
+        "wrong number of arguments (given #{ args.length }, expected 0)",
+        receiver: receiver,
+        target_method: target_method
+    end
+    
+    var_name = self.class.instance_var_name target_method
+    
+    unless receiver.instance_variable_defined? var_name
+      receiver.instance_variable_set var_name, target_method.call
+    end
+      
+    receiver.instance_variable_get var_name
+        
+  end # #call
+  
+end # class LazyAttr
+
+
+# /Namespace
+# =======================================================================
+
+end # module NRSER

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

@@ -78,7 +78,27 @@ class NRSER::Meta::Source::Location < Hamster::Vector
   # Props
   # ======================================================================
   
+  # @!attribute [r] file
+  #   The first entry in the source location array, denoting the file path.
+  #   
+  #   @return [String]
+  #     Source file absolute path.
+  #   
+  #   @return [nil]
+  #     No source file available.
+  #   
   prop  :file, type: t.abs_path?, default: nil, index: 0
+  
+  
+  # @!attribute [r] line
+  #   The second entry in the source location array, denoting the line number.
+  #   
+  #   @return [Integer]
+  #     Positive integer line number in the source {#file}.
+  #   
+  #   @return [nil]
+  #     No line number available.
+  #   
   prop  :line, type: t.pos_int?, default: nil, index: 1
   
   

data/lib/nrser/version.rb

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

data/spec/lib/nrser/core_ext/method/full_name_spec.rb

@@ -0,0 +1,41 @@
+require 'nrser/core_ext/method/full_name'
+
+describe_spec_file(
+  spec_path:        __FILE__,
+  class:            ::Method,
+  instance_method:  :full_name,
+) do
+  
+  describe_setup %{
+    get `method_name` from `receiver` and call `#full_name` on it
+  }.squish do
+    subject do
+      receiver.method( method_name ).full_name
+    end
+    
+    describe_case %{ class methods for } do
+      
+      describe_when receiver: Object, method_name: :new do
+        it { is_expected.to eq "Object.new" }
+      end
+      
+      describe_when receiver: NRSER, method_name: :rest do
+        it { is_expected.to eq "NRSER.rest" }
+      end
+      
+    end # class methods
+    
+    
+    describe_case "instance methods" do
+      describe_when receiver: Object.new, method_name: :to_s do
+        it %{ Returns the receiver's class,
+              even if method is not defined there }.squish do
+          is_expected.to eq "Object#to_s"
+        end
+      end
+      
+    end # instance methods
+    
+  end # setup
+  
+end # Spec File Description

data/spec/lib/nrser/meta/lazy_attr_spec.rb

@@ -0,0 +1,115 @@
+require 'nrser/meta/lazy_attr'
+
+describe_spec_file(
+  spec_path:        __FILE__,
+  class:            NRSER::LazyAttr,
+) do
+  
+  describe_setup %{ Decorate a class instance method } do
+    my_class = Class.new do
+      extend ::MethodDecorators
+      
+      def self.name
+        'MyClass'
+      end
+      
+      attr_reader :count
+      
+      def initialize
+        @count = 0
+      end
+      
+      +NRSER::LazyAttr
+      def f
+        @count += 1
+        'eff!'
+      end
+      
+    end
+    
+    instance = my_class.new
+    
+    it %{ starts out with call count 0 } do
+      expect( instance.count ).to be 0
+    end
+    
+    it %{ returns the correct result when called } do
+      expect( instance.f ).to eq 'eff!'
+    end
+    
+    it %{ now has the instance variable set } do
+      expect( instance.instance_variable_get :@f ).to eq 'eff!'
+    end
+    
+    it %{ now has call count 1 } do
+      expect( instance.count ).to be 1
+    end
+    
+    it %{ returns the same result when called again } do
+      expect( instance.f ).to eq "eff!"
+    end
+    
+    it %{ still has call count 1 } do
+      expect( instance.count ).to be 1
+    end
+    
+    it %{ still has the instance var set to the result } do
+      expect( instance.instance_variable_get :@f ).to eq 'eff!'
+    end
+    
+  end # instance method
+  
+  
+  describe_setup %{ Decorate a class method } do
+    my_class = Class.new do
+      extend ::MethodDecorators
+      
+      def self.name
+        'MyClass'
+      end
+      
+      @count = 0
+      
+      def self.count
+        @count
+      end
+      
+      +NRSER::LazyAttr
+      def self.f
+        @count += 1
+        'eff!'
+      end
+      
+    end
+    
+    it %{ starts out with call count 0 } do
+      expect( my_class.count ).to be 0
+    end
+    
+    it %{ returns the correct result when called } do
+      expect( my_class.f ).to eq 'eff!'
+    end
+    
+    it %{ now has the instance variable set } do
+      expect( my_class.instance_variable_get :@f ).to eq 'eff!'
+    end
+    
+    it %{ now has call count 1 } do
+      expect( my_class.count ).to be 1
+    end
+    
+    it %{ returns the same result when called again } do
+      expect( my_class.f ).to eq "eff!"
+    end
+    
+    it %{ still has call count 1 } do
+      expect( my_class.count ).to be 1
+    end
+    
+    it %{ still has the instance var set to the result } do
+      expect( my_class.instance_variable_get :@f ).to eq 'eff!'
+    end
+    
+  end # class method
+  
+end # Spec File Description

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nrser
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-24 00:00:00.000000000 Z
+date: 2018-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hamster
@@ -94,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: method_decorators
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.6
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -242,6 +256,8 @@ files:
 - lib/nrser/core_ext/hash/bury.rb
 - lib/nrser/core_ext/hash/extract_values_at.rb
 - lib/nrser/core_ext/hash/transform_values_with_keys.rb
+- lib/nrser/core_ext/method.rb
+- lib/nrser/core_ext/method/full_name.rb
 - lib/nrser/core_ext/module.rb
 - lib/nrser/core_ext/module/method_objects.rb
 - lib/nrser/core_ext/module/names.rb
@@ -253,6 +269,7 @@ files:
 - lib/nrser/core_ext/string.rb
 - lib/nrser/core_ext/symbol.rb
 - lib/nrser/core_ext/time.rb
+- lib/nrser/core_ext/unbound_method/full_name.rb
 - lib/nrser/errors.rb
 - lib/nrser/errors/abstract_method_error.rb
 - lib/nrser/errors/argument_error.rb
@@ -314,11 +331,13 @@ files:
 - lib/nrser/log/formatters/mixin.rb
 - lib/nrser/log/logger.rb
 - lib/nrser/log/mixin.rb
+- lib/nrser/log/notify.rb
 - lib/nrser/mean_streak.rb
 - lib/nrser/mean_streak/document.rb
 - lib/nrser/message.rb
 - lib/nrser/meta.rb
 - lib/nrser/meta/class_attrs.rb
+- lib/nrser/meta/lazy_attr.rb
 - lib/nrser/meta/source/location.rb
 - lib/nrser/no_arg.rb
 - lib/nrser/props.rb
@@ -403,6 +422,7 @@ files:
 - spec/lib/nrser/core_ext/enumerable/find_map_spec.rb
 - spec/lib/nrser/core_ext/hash/short_transform_keys_spec.rb
 - spec/lib/nrser/core_ext/hash_spec.rb
+- spec/lib/nrser/core_ext/method/full_name_spec.rb
 - spec/lib/nrser/errors/abstract_method_error_spec.rb
 - spec/lib/nrser/functions/enumerable/associate_spec.rb
 - spec/lib/nrser/functions/enumerable/find_all_map_spec.rb
@@ -433,6 +453,7 @@ files:
 - spec/lib/nrser/mean_streak/design_spec.rb
 - spec/lib/nrser/mean_streak/identity_instance_spec.rb
 - spec/lib/nrser/meta/class_attrs_spec.rb
+- spec/lib/nrser/meta/lazy_attr_spec.rb
 - spec/lib/nrser/meta/source/location_spec.rb
 - spec/lib/nrser/op/message_spec.rb
 - spec/lib/nrser/props/immutable/hash_spec.rb
@@ -493,6 +514,7 @@ test_files:
 - spec/lib/nrser/core_ext/enumerable/find_map_spec.rb
 - spec/lib/nrser/core_ext/hash/short_transform_keys_spec.rb
 - spec/lib/nrser/core_ext/hash_spec.rb
+- spec/lib/nrser/core_ext/method/full_name_spec.rb
 - spec/lib/nrser/errors/abstract_method_error_spec.rb
 - spec/lib/nrser/functions/enumerable/associate_spec.rb
 - spec/lib/nrser/functions/enumerable/find_all_map_spec.rb
@@ -523,6 +545,7 @@ test_files:
 - spec/lib/nrser/mean_streak/design_spec.rb
 - spec/lib/nrser/mean_streak/identity_instance_spec.rb
 - spec/lib/nrser/meta/class_attrs_spec.rb
+- spec/lib/nrser/meta/lazy_attr_spec.rb
 - spec/lib/nrser/meta/source/location_spec.rb
 - spec/lib/nrser/op/message_spec.rb
 - spec/lib/nrser/props/immutable/hash_spec.rb