trace_wrapper 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0064e5f0a037df2776197d1bc4f037b2143bffed37c585dd2b32c3e00206eb9
-  data.tar.gz: 1fe3daabe757fae12b60deb33e28df9fc647c74c433b356bbbcce8085fef3e12
+  metadata.gz: a24b778f09263356a804557de301cd497ee947853e019021e1489119c9dbaebc
+  data.tar.gz: 3f30db2855adc23225ded0f7780f10b2ede9ff04909bc8ff1b26ff5a06340914
 SHA512:
-  metadata.gz: 311db8eafe42199cb782128a12bf0271d40664a4a54de3f1aea57e0a60f144ed20225338b22e0517e9a99dab8f95dab8f8b7341a31f8b40c751ce0642a6c1954
-  data.tar.gz: ed522468367180ee1c63029a6fbb5d670547e54d839bb6e149670baed46d9e8e27d6517e76ce9f6f89e42cd785ce54f5aeb2c2f302be36d1a24ab8aa8b8ef970
+  metadata.gz: dc092be9bb2b3e468ff1084447bf4c76a174b506e8e958992512a3d82662830610dae3d977bf2ff2afc3e14029b209df086341fa67c01c1afedf6d7bf6b893f2
+  data.tar.gz: d92524251b1fc0a1d9dba6807e67fcd9854be77245e7a28eb8b8295d138da35a3722aaf4dcd20cd09448a4a6d5f22470c84fce71a902d21e4a53f86f9a320823

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2020-04-17
+
+### Changed
+- [BREAKING CHANGE] `:visibility` option to `wrap()` changed to just indicate the lowest visibility level wanted [commit](https://github.com/biinari/trace_wrapper/commit/84024964d846ed522192d4c1f0a8ecbb8f516323)
+- Moved shell colour internals to separate, undocumented module. [commit](https://github.com/biinari/trace_wrapper/7d4a9cb04314e252c4bfd184ce815b300d1f7852)
+
+### Documentation
+- Fixed documentation to include `README.md`.
+- Added description of `#wrap` behaviour with / without a block.
+
+## [0.1.0] - 2020-04-17
+
+Initial public release
+
+### Changed
+
+- Changed `:method_type` choices to `:instance` (instance methods), `:self`
+  (class / module methods, i.e. methods called directly on receiver), `:all`
+  (both instance and direct methods)
+
+### Added
+
+- Allow passing `receivers` as an array in first argument to `wrap()`. [commit](https://github.com/biinari/trace_wrapper/3d16a0fa823219705a1214114016d8f66e820609)
+- Add `:visibility` option to `wrap()` [PR #1](https://github.com/biinari/trace_wrapper/pulls/1)
+- Add `[process:thread]` identifier to trace output when calls are made on a
+  different process / thread to the instantiation of `TraceWrapper`.
+
+## 0.0.1 (never released)
+
+[Initial commit](https://github.com/biinari/tree/f71416e97ce3b7c1e76d0d6722ea64eb4d2a01ff)
+
+[Unreleased]: https://github.com/biinari/trace_wrapper/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/biinari/trace_wrapper/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/biinari/trace_wrapper/releases/tag/v0.1.0

data/README.md

@@ -64,7 +64,7 @@ What is the answer to the ultimate question?
 42
 ```
 
-See [custom example](examples/custom.rb) for a more custom usage
+See [custom example](https://github.com/biinari/trace_wrapper/blob/master/examples/custom.rb) for a more custom usage
 
 ### Options
 

data/Rakefile

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rake/testtask'
+require 'rdoc/task'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
@@ -12,4 +13,10 @@ task :rubocop do
   sh 'rubocop'
 end
 
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+  rdoc.rdoc_dir = 'doc'
+end
+
 task default: %i[rubocop test]

data/lib/trace_wrapper.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
 require 'trace_wrapper/version'
+require 'trace_wrapper/shell'
 
 ##
 # Wraps methods on given classes or modules to output a call/return tree.
 class TraceWrapper
-  COLOURS = {
-    red: '31m',
-    b_red: '1;31m',
-    green: '32m',
-    b_green: '1;32m',
-    orange: '33m',
-    yellow: '1;33m',
-    blue: '34m',
-    b_blue: '1;34m',
-    purple: '35m',
-    b_purple: '1;35m',
-    teal: '36m',
-    cyan: '1;36m'
-  }.freeze
-
-  ELLIPSIS = "\u2026"
+  include TraceWrapper::Shell
 
   class << self
-    def wrap(*receivers, **kwargs, &block)
+    ##
+    # Wraps methods on given +receivers+ with tracing
+    #
+    # options will be passed to .new and #wrap respectively
+    #
+    # If a block is given, it will be passed to #wrap
+    def wrap(*receivers, **options, &block) # :yields: a_trace_wrapper
       init_keys = %i[output colour]
-      init_args = kwargs.select { |k, _| init_keys.include?(k) }
-      wrap_args = kwargs.reject { |k, _| init_keys.include?(k) }
+      init_args = options.select { |k, _| init_keys.include?(k) }
+      wrap_args = options.reject { |k, _| init_keys.include?(k) }
 
       new(**init_args).wrap(*receivers, **wrap_args, &block)
     end
@@ -39,7 +31,7 @@ class TraceWrapper
   #
   # :output - +IO+ object to write trace output to (default +STDOUT+)
   # :colour - True to use shell colours in output (default +nil+ will colour if
-  #           output is a TTY)
+  # output is a TTY)
   def initialize(output: $stdout, colour: nil)
     @output = output
     @colour = colour
@@ -54,18 +46,23 @@ class TraceWrapper
   #
   # Options
   #
-  # :method_type - Types of methods to wrap (default: :all). Choices are:
-  #                :instance for methods on instances of receiver(s)
-  #                :self for methods called directly on the receiver(s)
-  #                :all for both
-  # :visibility - Array of method visibility levels to wrap. Can include
-  #               :public, :protected, :private
-  #               (default [:public, :protected])
+  # +:method_type+ - Types of methods to wrap (default: +:all+). Choices are:
+  # +:instance+ (for instance methods),
+  # +:self+ (for receiver methods, i.e. class/module functions),
+  # +:all+ for both
+  #
+  # +:visibility+ - Lowest method visibility level to wrap
+  # (default: +:protected+). Choices are: :public, :protected, :private.
   #
-  # If a block is given, the wrappers will be created just around the block
+  # If a block is given, the wrappers will be created just around the block and
+  # the block's result will be returned.
+  # The TraceWrapper instance will be yielded to the block to allow further
+  # wraps to be added.
+  #
+  # If no block is given, you should call unwrap after use.
   def wrap(*receivers,
            method_type: :all,
-           visibility: %i[public protected])
+           visibility: :protected) # :yields: a_trace_wrapper
     unwrappers = []
     Array(*receivers).each do |receiver|
       if %i[all self].include?(method_type)
@@ -96,7 +93,7 @@ class TraceWrapper
   private
 
   # Wrap standard methods (methods on the object given) with tracing
-  def wrap_methods(*receivers, visibility: %i[public protected])
+  def wrap_methods(*receivers, visibility: :protected)
     unwrappers = []
     Array(*receivers).each do |receiver|
       mod, unwrapper = wrapping_module(receiver, :self, visibility)
@@ -108,7 +105,7 @@ class TraceWrapper
 
   # Wrap instance methods (called on an instance of the class given) with
   # tracing
-  def wrap_instance_methods(*receivers, visibility: %i[public protected])
+  def wrap_instance_methods(*receivers, visibility: :protected)
     unwrappers = []
     Array(*receivers).each do |receiver|
       mod, unwrapper = wrapping_module(receiver, :instance, visibility)
@@ -166,12 +163,16 @@ class TraceWrapper
       protected: :protected_methods,
       private: :private_methods
     }
-  }.freeze
+  }.freeze # :nodoc:
 
   def get_methods(receiver, method_type, visibility)
-    %i[public protected private].map do |vis|
-      next unless visibility.include?(vis)
+    visibilities = %i[public protected private]
+    unless visibilities.include?(visibility)
+      raise "visibility option not recognised: #{visibility.inspect}"
+    end
+    visibilities = visibilities[0..visibilities.find_index(visibility)]
 
+    visibilities.map do |vis|
       lister = LIST_METHODS[method_type][vis]
       receiver.public_send(lister, false) - Object.public_send(lister)
     end.compact.flatten
@@ -208,16 +209,6 @@ class TraceWrapper
     @output.write("#{indent}#{text}\n")
   end
 
-  def colour(text, colour)
-    return text unless colour?
-    "\e[#{COLOURS[colour]}#{text}\e[0m"
-  end
-
-  def colour?
-    return @colour unless @colour.nil?
-    @output.respond_to?(:isatty) && @output.isatty
-  end
-
   def incr_indent
     process[:indent] += 1
   end

data/lib/trace_wrapper/shell.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class TraceWrapper
+  module Shell # :nodoc: all
+    COLOURS = {
+      red: '31m',
+      b_red: '1;31m',
+      green: '32m',
+      b_green: '1;32m',
+      orange: '33m',
+      yellow: '1;33m',
+      blue: '34m',
+      b_blue: '1;34m',
+      purple: '35m',
+      b_purple: '1;35m',
+      teal: '36m',
+      cyan: '1;36m'
+    }.freeze
+
+    ELLIPSIS = "\u2026"
+
+    def colour?
+      return @colour unless @colour.nil?
+      @output.respond_to?(:isatty) && @output.isatty
+    end
+
+    def colour(text, colour)
+      return text unless colour?
+      "\e[#{COLOURS[colour]}#{text}\e[0m"
+    end
+  end
+end

data/lib/trace_wrapper/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 class TraceWrapper
-  VERSION = '0.1.0'
+  # Current version of TraceWrapper
+  VERSION = '0.2.0'
 end

data/test/test_trace_wrapper.rb

@@ -156,7 +156,7 @@ class TestTraceWrapper < Minitest::Test
                    .gsub!(/@([^@]*)@/, "#{PURPLE}\\1#{CLEAR}")
 
     subject = lambda do |tracer|
-      tracer.wrap(PlayClass, visibility: %i[public protected private])
+      tracer.wrap(PlayClass, visibility: :private)
       result = PlayClass.new.play_solitaire(2, 3)
 
       assert_equal('solo: 2, 3', result)

data/trace_wrapper.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
     'source_code_uri' => 'https://github.com/biinari/trace_wrapper'
   }
   s.rdoc_options << '--main' << 'README.md'
+  s.extra_rdoc_files = ['README.md']
 
   s.add_development_dependency 'minitest', '~> 5.14'
   s.add_development_dependency 'rake', '~> 13.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trace_wrapper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Bill Ruddock
@@ -60,11 +60,13 @@ description: |-
 email: 
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.md
 - README.md
@@ -72,6 +74,7 @@ files:
 - examples/basic.rb
 - examples/custom.rb
 - lib/trace_wrapper.rb
+- lib/trace_wrapper/shell.rb
 - lib/trace_wrapper/version.rb
 - test/playground.rb
 - test/test_trace_wrapper.rb