peeky 0.0.25 → 0.0.39

data/USAGE2.md

@@ -0,0 +1,5 @@
+# Peeky
+
+This document will show you how to use Peeky.
+
+Peeky is a Ruby GEM for peaking into ruby classes and extracting meta

data/lib/peeky.rb

@@ -12,6 +12,7 @@ require 'peeky/parameter_info'
 require 'peeky/predicates/attr_reader_predicate'
 require 'peeky/predicates/attr_writer_predicate'
 
+require 'peeky/renderer/class_debug_render'
 require 'peeky/renderer/class_interface_render'
 require 'peeky/renderer/class_interface_yard_render'
 require 'peeky/renderer/method_call_minimum_params_render'

data/lib/peeky/api.rb

@@ -16,11 +16,24 @@ module Peeky
     # ClassInfo stores information about the instance of a
     # class that is passed in including methods, attr_accessors
     # attr_readers and attr_writers.
-    def build_class_info(instance)
-      Peeky::ClassInfo.new(instance)
+    #
+    # @param instance [Object] instance of class to gather information about (required)
+    # @param lazy [TrueClass] lazy load method and parameter information, laze: is optional, defaults to true
+    def build_class_info(instance, lazy: true)
+      ci = Peeky::ClassInfo.new(instance)
+      ci.load unless lazy
+      ci
     end
 
     # Render a class using a predefined class renderer
+    #
+    # ^1: One of class_info and instance must supplied, they are mutually
+    # exclusive to each other.
+    #
+    # @param render_key [Symbol] class render key (required)
+    # @param class_info [Object] class_info: is optional^1, defaults to nil
+    # @param instance [Object] instance: is optional^1, defaults to nil
+    # @param _opts [<key: value>...] **_opts - list of key/values that can help configure render
     def render_class(render_key, class_info: nil, instance: nil, **_opts)
       raise 'Call render_class with class_info OR instance.' if class_info.nil? && instance.nil?
       raise 'Call render_class with class_info OR instance, these parameters are mutually exclusive' if !class_info.nil? && !instance.nil?
@@ -35,6 +48,7 @@ module Peeky
     # Get a method renderer by :key
     #
     # TODO: Refactor to a configurable system
+    # @param key [String] key is a shortcut to a specific Peeky::Render that handles method_info (required)
     def method_renderer(key)
       case key
       when :signature
@@ -51,8 +65,11 @@ module Peeky
     # Get a class renderer by :key
     #
     # TODO: Refactor to a configurable system
+    # @param key [String] key is a shortcut to a specific Peeky::Renderer that handles class_info (required)
     def class_renderer(key)
       case key
+      when :class_debug
+        Peeky::Renderer::ClassDebugRender
       when :class_interface
         Peeky::Renderer::ClassInterfaceRender
       when :class_interface_yard

data/lib/peeky/attr_info.rb

@@ -6,7 +6,9 @@ module Peeky
   # Attr Info is a container that holds read, write or read/write
   # attributes in the form of MethodInfo objects
   class AttrInfo
+    # reader stores a MethodInfo for a matching reader, nil if readable style method_info not found
     attr_reader :reader
+    # writer stores a MethodInfo for a matching writer, nil if writable style method_info not found
     attr_reader :writer
 
     def initialize(reader: nil, writer: nil)
@@ -16,6 +18,7 @@ module Peeky
       @writer = writer
     end
 
+    # Type of the attribute [:attr_writer, :attr_reader or :attr_accessor]
     def type
       @type ||= if @reader.nil?
                   :attr_writer
@@ -24,6 +27,7 @@ module Peeky
                 end
     end
 
+    # Name of the attribute
     def name
       @name ||= @reader.nil? ? @writer.clean_name : @reader.clean_name
     end

data/lib/peeky/class_info.rb

@@ -17,6 +17,43 @@ module Peeky
       @instance = instance
     end
 
+    # rubocop:disable Metrics/AbcSize
+    def to_s
+      result = []
+      result.push kv('class', class_full_name)
+      if defined?(@_ruby_instance_method_names)
+        result.push kv('# of instance methods', @_ruby_instance_method_names.join(', '))
+      else
+        result.push kv('# of instance methods', '')
+      end
+      if defined?(@_signatures)
+        result.push kv('# of accessors', accessors.length)
+        result.push kv('# of readers', readers.length)
+        result.push kv('# of writers', writers.length)
+        result.push kv('# of methods', methods.length)
+      else
+        result.push kv('# of accessors', '')
+        result.push kv('# of readers', '')
+        result.push kv('# of writers', '')
+        result.push kv('# of methods', '')
+      end
+      result.join("\n")
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Load class_info
+    #
+    # Accessing information about methods and parameters is currently
+    # lazy-loaded via memoization.
+    #
+    # At times during debug or other edge cases, it may be useful to
+    # pre-load this information early.
+    def load
+      ruby_instance_methods
+      ruby_instance_method_names
+      signatures
+    end
+
     # Class full name includes the module namespace
     def class_full_name
       instance.class.name
@@ -144,53 +181,20 @@ module Peeky
       signatures.select { |im| im.name == name && im.implementation_type == filter_type }
     end
 
-    # Build (not sure where I am going with this yet)
-    # TODO: Refact: Currently the idea is to pre-load data
-    # this is slower when you are not accessing things, but
-    # it is easier to debug, so think about what I really want
-    # here
-    def build()
-      ruby_instance_methods
-      ruby_instance_method_names
-      signatures
-    end
-
-    # Debug
-    #
-    # Refact: PATTERN: Come up it an debug inclusion system so that
-    # so that debug helpers can be included for development and excluded
-    # for production 
-    # @param format [String] format: <value for format> (optional)
-    def debug(format: [:signatures])
-      if format.include?(:method_names)
-        puts '-' * 70
-        puts 'Method Names'
-        puts '-' * 70
-        ruby_instance_method_names.each do |method_name|
-          puts method_name
-        end
-      end
-
-      return unless format.include?(:signatures)
+    private
 
-      puts '-' * 70
-      puts 'Methods'
-      puts '-' * 70
-      signatures.each(&:debug)
+    def kv(key, value)
+      "#{key.to_s.ljust(25)}: #{value}"
     end
 
-    private
-
     def ruby_instance_method_names
       @_ruby_instance_method_names ||= instance.class.instance_methods(false).sort
     end
 
     def ruby_instance_methods
-      begin
-        @_ruby_instance_methods ||= ruby_instance_method_names.map { |method_name| instance.method(method_name) }
-      rescue => exception
-        puts exception
-      end
+      @_ruby_instance_methods ||= ruby_instance_method_names.map { |method_name| instance.method(method_name) }
+    rescue StandardError => e
+      puts e
     end
   end
 end

data/lib/peeky/example/yard_sample.rb

@@ -47,16 +47,16 @@ module Peeky
       # F method with required param and optional param
       #
       # @param first_name [String] first name (required)
-      # @param last_name [String] last name (optional)
-      def f_method_with_required_param_and_optional_param(first_name, last_name = nil)
+      # @param last_name [String] last_name is optional, defaults to ''
+      def f_method_with_required_param_and_optional_param(first_name, last_name = '')
       end
 
       # G method with required param and two optional params
       #
       # @param first_name [String] first name (required)
-      # @param last_name [String] last name (optional)
-      # @param age [String] age (optional)
-      def g_method_with_required_param_and_two_optional_params(first_name, last_name = nil, age = nil)
+      # @param last_name [String] last_name is optional, defaults to ''
+      # @param age [Integer] age is optional, defaults to 21
+      def g_method_with_required_param_and_two_optional_params(first_name, last_name = '', age = 21)
       end
 
       # H list of optional parameters
@@ -94,11 +94,12 @@ module Peeky
       # N method with key value param required and optional key value
       #
       # @param last_name [String] last_name: <value for last name> (required)
-      # @param salutation [String] salutation: <value for salutation> (optional)
-      def n_method_with_key_value_param_required_and_optional_key_value(last_name:, salutation: nil)
+      # @param salutation [String] salutation: is optional, defaults to 'Mr'
+      def n_method_with_key_value_param_required_and_optional_key_value(last_name:, salutation: 'Mr')
       end
 
       # P available?
+
       # @return [Boolean] true when p available?
       def p_available?
       end
@@ -110,13 +111,29 @@ module Peeky
       # Z complex
       #
       # @param aaa [String] aaa (required)
-      # @param bbb [String] bbb (optional)
+      # @param bbb [Integer] bbb is optional, defaults to 1
       # @param ccc [Array<Object>] *ccc - list of ccc
       # @param ddd [String] ddd: <value for ddd> (required)
-      # @param eee [String] eee: <value for eee> (optional)
+      # @param eee [Integer] eee: is optional, defaults to 1
       # @param fff [<key: value>...] **fff - list of key/values
       # @param ggg [Block] &ggg
-      def z_complex(aaa, bbb = nil, *ccc, ddd:, eee: nil, **fff, &ggg)
+      def z_complex(aaa, bbb = 1, *ccc, ddd:, eee: 1, **fff, &ggg)
+      end
+
+      # Z optional styles
+      #
+      # @param aaa [String] aaa (required)
+      # @param bbb [Integer] bbb is optional, defaults to 123
+      # @param ccc [String] ccc is optional, defaults to 'abc'
+      # @param ddd [TrueClass] ddd is optional, defaults to true
+      # @param eee [FalseClass] eee is optional, defaults to false
+      # @param fff [Object] fff is optional, defaults to nil
+      # @param ggg [Integer] ggg: is optional, defaults to 123
+      # @param hhh [String] hhh: is optional, defaults to 'xyz'
+      # @param iii [TrueClass] iii: is optional, defaults to true
+      # @param jjj [FalseClass] jjj: is optional, defaults to false
+      # @param kkk [Object] kkk: is optional, defaults to nil
+      def z_optional_styles(aaa, bbb = 123, ccc = 'abc', ddd = true, eee = false, fff = nil, ggg: 123, hhh: 'xyz', iii: true, jjj: false, kkk: )
       end
     end
   end

data/lib/peeky/method_info.rb

@@ -16,26 +16,35 @@ module Peeky
 
     def_delegators :focal_method, :name, :receiver, :arity, :super_method
 
-    # Stage 2 is the method likely to be an attribute reader or writer
+    ## Stage 2 is the method likely to be an attribute reader or writer
+    #
 
     # Implementation type indicates the probable representation of this
     # method in ruby, was it `def method` or `attr_reader` / `attr_writer`
     attr_reader :implementation_type
 
-    # TODO: target_instance is required...
-    def initialize(method, target_instance = nil)
+    def initialize(method, target_instance)
       @focal_method = method
+      @target_instance = target_instance
       @parameters = ParameterInfo.from_method(method)
       # stage 1
       # @implementation_type = :method
 
       # stage 2
-      @implementation_type = infer_implementation_type(target_instance)
+      infer_implementation_type
+
+      # stage 3
+      infer_default_paramaters
     end
 
     # Stage 2 (working out) attr_accessor
+    #
+
     # Name of method minus writer annotations
-    # Example :writable_attribute= becomes :writable_attribute
+    # Example
+    #   :writable_attribute=
+    #   # becomes
+    #   :writable_attribute
     def clean_name
       @clean_name ||= begin
         n = name.to_s
@@ -43,43 +52,113 @@ module Peeky
       end
     end
 
-    def infer_implementation_type(target_instance)
-      if target_instance.nil?
-        :method
-      elsif match(target_instance, Peeky::Predicates::AttrReaderPredicate)
-        :attr_reader
-      elsif match(target_instance, Peeky::Predicates::AttrWriterPredicate)
-        :attr_writer
-      else
-        :method
+    # Infer implementation type [:method, :attr_reader or :attr_writer]
+    # rubocop:disable Lint/DuplicateBranch
+    def infer_implementation_type
+      @implementation_type = if @target_instance.nil?
+                               :method
+                             elsif match(Peeky::Predicates::AttrReaderPredicate)
+                               :attr_reader
+                             elsif match(Peeky::Predicates::AttrWriterPredicate)
+                               :attr_writer
+                             else
+                               :method
+                             end
+    end
+    # rubocop:enable Lint/DuplicateBranch
+
+    # Get parameter by name
+    #
+    # @param name [String] name (required)
+    def get_parameter(name)
+      name = name.to_s
+      parameters.find { |p| p.name == name }
+    end
+
+    # Has any optional paramaters?
+
+    # @return [Boolean] true when any parameter is optional?
+    def optional?
+      parameters.any?(&:optional?)
+    end
+
+    # Infer default paramater values
+    #
+    # WARNING: Unit test coverage went from .1 seconds to 30-40 seconds
+    # when I first introduced this method.
+    #
+    # I now only call TracePoint if I have optional parameters to be inferred.
+    #
+    # The tests are now down to 5 seconds, but it highlights the cost of use
+    # TracePoint.
+    def infer_default_paramaters
+      minimalist_method = Peeky::Renderer::MethodCallMinimumParamsRender.new(self).render
+
+      return if minimalist_method.end_with?('=')
+      return unless optional?
+
+      tracer.enable do
+        @target_instance.instance_eval(minimalist_method)
+      rescue StandardError => e
+        # just print the error for now, we are only attempting to capture the
+        # first call, any errors inside the call cannot be dealt with and should
+        # not be re-raised
+        puts e.message
+      end
+    end
+
+    def tracer
+      TracePoint.trace(:call, :c_call) do |tp|
+        next unless tp.self.is_a?(@target_instance.class)
+        next unless tp.method_id == name
+
+        tp.parameters.each do |_type, param_name|
+          method_paramater = get_parameter(param_name)
+
+          if method_paramater.optional?
+            value = tp.binding.local_variable_get(param_name)
+            method_paramater.default_value = value
+          end
+        end
       end
     end
 
-    def match(target_instance, predicate)
-      predicate.new.match(target_instance, self)
+    # Match
+    #
+    # @param predicate [String] use a predicate object with the signature match(instance, method_info)
+    def match(predicate)
+      predicate.new.match(@target_instance, self)
     end
 
+    # Method?
+
+    # @return [Boolean] true when implementation type is method?
     def method?
       @implementation_type == :method
     end
 
-    # https://github.com/rubyide/vscode-ruby/issues/454
-    # if I prefix these methods with attr_ then will get an issue
-    # in the language server.
-    # Cannot read property 'namedChildren' of undefined
+    # Readable?
+    #
+    # @return [Boolean] true when readable?
     def readable?
+      # Method naming issue: VSCode Ruby Language Server
+      #
+      # If this method is renamed to attr_readable, same for attr_writable.
+      #
+      # https://github.com/rubyide/vscode-ruby/issues/454
+      # if I prefix these methods with attr_ then will get an issue
+      # in the language server.
+      #
+      # Cannot read property 'namedChildren' of undefined
+
       @implementation_type == :attr_reader
     end
 
+    # Writable?
+
+    # @return [Boolean] true when implementation_type writable?
     def writable?
       @implementation_type == :attr_writer
     end
-
-    def debug
-      puts '-' * 70
-      puts name
-      puts '-' * 70
-      parameters.each(&:debug)
-    end
   end
 end

data/lib/peeky/parameter_info.rb

@@ -20,11 +20,8 @@ module Peeky
     # type of the parameter
     attr_accessor :type
 
-    # ruby code format when used in a signature
-    attr_accessor :signature_format
-
-    # minimal required usage in a call to the method with this paramater
-    attr_accessor :minimal_call_format
+    # default value for positional or keyed parameters
+    attr_accessor :default_value
 
     def initialize(param)
       map(param)
@@ -51,54 +48,133 @@ module Peeky
       ruby_method.parameters.map { |ruby_paramater| from_parameter(ruby_paramater) }
     end
 
-    def debug
-      puts "name                          : #{name}"
-      puts "type                          : #{type}"
-      puts "signature_format              : #{signature_format}"
-      puts "minimal_call_format           : #{minimal_call_format}"
+    # ruby code formatted for use in a method signature
+    def signature_format
+      @_signature_format ||= begin
+        method_name = "signature_format_#{@type}".to_sym
+
+        m = method(method_name)
+        m.call
+      end
+    end
+
+    # minimal required usage in a call to the method with this paramater
+    def minimal_call_format
+      @_minimal_call_format ||= begin
+        method_name = "minimal_call_format_#{@type}".to_sym
+
+        if respond_to?(method_name, true)
+          m = method(method_name)
+          m.call
+        else
+          minimal_call_format_ignore
+        end
+      end
+    end
+
+    # Optional?
+
+    # @return [Boolean] true when parameter is one of the optional types?
+    def optional?
+      @_optional |= (@type == :param_optional || @type == :key_optional)
+    end
+
+    # Default value type will look at the default value and try to
+    # infer the class behind it. Will default to 'Object' fi nil
+    def default_value_type
+      if @default_value.nil?
+        'Object'
+      else
+        @default_value.class
+      end
+    end
+
+    # Wrap default value in quotes if string, or no wrapping otherwise
+    #
+    # @param value_for_nil [String] value for nil, generally '' or 'nil' (required)
+    def wrap_default_value(value_for_nil)
+      if @default_value.is_a?(String)
+        "'#{@default_value}'"
+      else
+        @default_value.nil? ? value_for_nil : @default_value
+      end
     end
 
     private
 
     # Convert the limited information provided by ruby method.parameters
     # to a richer structure.
-    # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
     def map(param)
       @name = param.length > 1 ? param[1].to_s : ''
 
+      @default_value = nil
+
       case param[0]
       when :req
         @type = :param_required
-        @signature_format = name.to_s
-        @minimal_call_format = "'#{name}'"
       when :opt
         @type = :param_optional
-        @signature_format = "#{name} = nil"
-        @minimal_call_format = ''
       when :rest
         @type = :splat
-        @signature_format = "*#{name}"
-        @minimal_call_format = ''
       when :keyreq
         @type = :key_required
-        @signature_format = "#{name}:"
-        @minimal_call_format = "#{name}: '#{name}'"
       when :key
         @type = :key_optional
-        @signature_format = "#{name}: nil"
-        @minimal_call_format = ''
       when :keyrest
         @type = :double_splat
-        @signature_format = "**#{name}"
-        @minimal_call_format = ''
       when :block
         @type = :block
-        @signature_format = "&#{name}"
-        @minimal_call_format = ''
       else
         raise 'unknown type'
       end
     end
-    # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    # Signature format *: Is used to format a parameter when it is used
+    # inside of a method signature, eg. def my_method(p1, p2 = 'xyz', p3: :name_value)
+
+    def signature_format_param_required
+      name.to_s
+    end
+
+    def signature_format_param_optional
+      "#{name} = #{wrap_default_value('nil')}" # signature format needs to be moved to a method
+    end
+
+    def signature_format_splat
+      "*#{name}"
+    end
+
+    def signature_format_key_required
+      "#{name}:"
+    end
+
+    def signature_format_key_optional
+      "#{name}: #{wrap_default_value('')}"
+    end
+
+    def signature_format_double_splat
+      "**#{name}"
+    end
+
+    def signature_format_block
+      "&#{name}"
+    end
+
+    # Minimal call format *: Is used to format a call to a method with the least
+    # number of parameters needed to make it work.
+
+    def minimal_call_format_ignore
+      ''
+    end
+
+    def minimal_call_format_param_required
+      "'#{@name}'"
+    end
+
+    def minimal_call_format_key_required
+      "#{@name}: '#{@name}'"
+    end
   end
 end