irb-kit 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd95b94c3b604ba8c6c5c239475a99ab603815ba86d98587193063515b676fd2
-  data.tar.gz: e2082fe9b9e281291c2e67ec6b54e2ea7359c50178d625cf96faa05ce225ece8
+  metadata.gz: 933e747eed7ae52f00c24917ffc823c6c64f46e89ee545c073acd1ab5030d658
+  data.tar.gz: 635104c16839e1e0daa5dd86fc4e9a16b6c1f2d38f71b115fd5a48a9c51b7ec1
 SHA512:
-  metadata.gz: a5bbb32382af12000c59e762774961637a00285f55355eed10d7feead6d6f015397661ec99a9ad0e29e7036a26cc938b89c3aa75ee6d96b1d2c0e6fd4c9f77bf
-  data.tar.gz: cc2472d1fd8069b751816de1f5c62574236dc999b59c380b886b5e2e0b1b5a8911935fe2c6b2fc9e9b738e9626f6c78699ae3d16d25bae5c5ff3ea63778b5837
+  metadata.gz: 33f497dfd8df38fa16951b88f8309c87d282576c87e45540d6c2ee42451731c69269a67ed76b806f53b4338eadc8165feb27bb4b064a1b5c0256936a30f471e7
+  data.tar.gz: af933ab60e72c168d1e0eef54d30edc36ddb9d69d26a925b834cbfa52d4994537fb75177b872d42c38fe766e00345e29ca4b610720761fc67b7136a059f8bab3

data/README.adoc

@@ -19,7 +19,7 @@ toc::[]
 
 == Features
 
-* Provides custom helpers.
+* Provides custom commands and helpers.
 * Provides dynamic prompt based on environment.
 
 == Requirements
@@ -84,6 +84,7 @@ If you'd like all the bells and whistles fully enabled, add the following to you
 begin
   require "irb/kit"
 
+  IRB::Kit.register_commands :all
   IRB::Kit.register_helpers :all
 
   IRB.conf[:PROMPT] ||= {}
@@ -102,14 +103,44 @@ rescue LoadError => error
 end
 ----
 
-The above enables all helpers and configures your prompt for {ruby_link}, {hanami_link}, and {rails_link} environments.
+The above enables all commands and helpers and configures your prompt for {ruby_link}, {hanami_link}, and {rails_link} environments.
 
 
 💡 Use of `:DEMO`, while functional, is meant to be replaced with the name of your organization or personal identity. So please ensure you replace both occurrences of `:DEMO` with your own unique identifier.
 
 === Commands
 
-At the moment, this gem does not provide any custom commands _but might in the future_. See {irb_extensions_link} documentation for further details.
+Custom command are provided for you by this gem. Each is listed below as found when using `help` within an {irb_link} console:
+
+....
+Kit
+  descendants        Show class descendants.
+....
+
+To enable all of these commands, use `IRB::Kit.register_commands :all`. This is the same as using:
+
+[source,ruby]
+----
+IRB::Kit.register_commands :descendants
+----
+
+Knowing this, you can disable all commands entirely, use only the ones you care about, or enable all of them at once. The following explains each helper in greater detail.
+
+==== `descendants`
+
+Use this command to show all descendants of a class. Example:
+
+[source,ruby]
+----
+descendants IO
+# File
+
+descendants Ractor::Error
+# Ractor::IsolationError
+# Ractor::MovedError
+# Ractor::RemoteError
+# Ractor::UnsafeError
+----
 
 === Helpers
 
@@ -118,8 +149,7 @@ Several custom helpers are provided for you by this gem. Each is listed below as
 ....
 Helper methods
   clip           Copy input to macOS clipboard.
-  csource        Find a constant's source location.
-  msource        Find an object method's source location.
+  esource        Edit the source code of a constant or method in your default editor.
   paste          Paste last entry from macOS clipboard.
   search         Search an object's methods by pattern.
 ....
@@ -128,7 +158,7 @@ To enable all of these helpers, use `IRB::Kit.register_helpers :all`. This is th
 
 [source,ruby]
 ----
-IRB::Kit.register_helpers(*%i[clip csource msource paste search])
+IRB::Kit.register_helpers(*%i[clip esource paste search])
 ----
 
 Knowing this, you can disable all helpers entirely, use only the ones you care about, or enable all of them at once. The following explains each helper in greater detail.
@@ -155,31 +185,26 @@ clip Object.new
 
 This helper accepts any number of arguments. Each is delimited by a new line for pasting into another application.
 
-==== `csource`
+==== `esource`
 
-Use this helper, short for _constant source_, to find the source location of a constant. Example:
+Use this helper, short for _edit source_, to print and edit the source of a constant or method in your default editor. This assumes your have the `EDITOR` environment variable set and configured to use your favorite editor. If not, you'll get an error requiring your to update your environment accordingly. Here are a few usage examples:
 
 [source,ruby]
 ----
-csource :RUBY_DESCRIPTION   # "$HOME/.cache/frum/versions/3.3.2/bin/ruby:0"
-csource "RUBY_DESCRIPTION"  # "$HOME/.cache/frum/versions/3.3.2/bin/ruby:0"
-----
-
-You can use a symbol or a string when looking up the source location of a constant. The output is formatted so you can use pass:[<kbd>CONTROL</kbd>] + `<click>` to immediately view the source at the exact line number in consoles like {iterm_link}.
+esource IRB, :start
+# Editing: irb-1.13.2/lib/irb.rb:893...
 
-==== `msource`
+esource IRB, "start"
+# Editing: irb-1.13.2/lib/irb.rb:893...
 
-Use this helper, short for _method source_, to find the source location of a method. Example:
+esource "IRB::IRBRC_EXT"
+# Editing: irb-1.13.2/lib/irb/init.rb:407...
 
-[source,ruby]
+esource :RUBY_DESCRIPTION
+# ERROR (invalid path): ruby.
 ----
-msource IRB, :start   # "$HOME/.cache/frum/versions/3.3.2/lib/ruby/3.3.0/irb.rb:893"
-msource IRB, "start"  # "$HOME/.cache/frum/versions/3.3.2/lib/ruby/3.3.0/irb.rb:893"
-----
-
-The first argument is the object you want to message while the second argument is the object's method you want to find the source code location for. You can also use a symbol or string for the method.
 
-The output is formatted so you can use pass:[<kbd>CONTROL</kbd>] + `<click>` to immediately view the source at the exact line number in consoles like {iterm_link}.
+The first argument is the constant or object you want to search for or target. The second argument is the object's method you want to find the source code location for. You can also use a symbol or string for the method.
 
 ==== `paste`
 
@@ -200,22 +225,18 @@ Use this helper to search for methods on an object. Example:
 [source,ruby]
 ----
 search Module, "protected"
-# [
-#    protected_instance_methods(*args) #<Class:Module> (Class)
-#     protected_method_defined?(*arg1) #<Class:Module> (Module)
-#             protected_methods(*args) #<Class:Module> (Object)
-# ]
+# protected_instance_methods
+# protected_method_defined?
+# protected_methods
 
 search Module, /_defined/
-# [
-#       class_variable_defined?(arg1)  #<Class:Module> (Module)
-#                const_defined?(*arg1) #<Class:Module> (Module)
-#    instance_variable_defined?(arg1)  #<Class:Module> (Kernel)
-#               method_defined?(*arg1) #<Class:Module> (Module)
-#       private_method_defined?(*arg1) #<Class:Module> (Module)
-#     protected_method_defined?(*arg1) #<Class:Module> (Module)
-#        public_method_defined?(*arg1) #<Class:Module> (Module)
-# ]
+# const_defined?
+# class_variable_defined?
+# method_defined?
+# public_method_defined?
+# private_method_defined?
+# protected_method_defined?
+# instance_variable_defined?
 ----
 
 This helper takes two arguments. The first is the object you want to search on and the second argument is the string or regular expression of the methods to search for.

data/irb-kit.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "irb-kit"
-  spec.version = "0.2.0"
+  spec.version = "0.4.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/irb-kit"
@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.cert_chain = [Gem.default_cert_path]
 
   spec.required_ruby_version = "~> 3.3"
-  spec.add_dependency "irb", "~> 1.13"
+  spec.add_dependency "irb", "~> 1.14"
   spec.add_dependency "zeitwerk", "~> 2.6"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

data/lib/irb/kit/commands/descendants.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Commands
+      # Answers descendants of a class.
+      class Descendants < IRB::Command::Base
+        MONIKER = :descendants
+
+        category "Kit"
+
+        description "Show class descendants."
+
+        help_message <<~BODY
+          Usage: descendants <class>
+
+          Examples:
+
+            descendants Object
+            descendants IO
+            descendants Ractor::Error
+        BODY
+
+        def initialize context, handler: Handlers::Descender.new
+          super context
+          @handler = handler
+        end
+
+        def execute(name) = handler.call(name)
+
+        private
+
+        attr_reader :handler
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/abstract.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Provides default functionality for all handlers.
+      class Abstract
+        def initialize io: STDOUT
+          @io = io
+        end
+
+        def call
+          fail NoMethodError,
+               "`#{self.class}##{__method__} #{method(__method__).parameters}` must be implemented."
+        end
+
+        protected
+
+        attr_reader :io
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/clipper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles copying content to the macOS clipboard.
+      class Clipper < Abstract
+        def initialize(processor: IO, **)
+          @processor = processor
+          super(**)
+        end
+
+        def call(*lines)
+          processor.popen("pbcopy", "w") { |clipboard| clipboard.write lines.join("\n") }
+          io.puts "Copied to clipboard."
+        rescue Errno::ENOENT
+          io.puts "ERROR: Unable to copy since `pbcopy` is only supported on macOS."
+        end
+
+        private
+
+        attr_reader :processor
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/constant_editor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles editing of constant source code.
+      class ConstantEditor < Abstract
+        def initialize(editor: Editor.new, **)
+          @editor = editor
+          super(**)
+        end
+
+        def call name
+          editor.call(*Object.const_source_location(name))
+        rescue NameError
+          io.puts "ERROR (invalid constant): #{name.inspect}."
+        end
+
+        private
+
+        attr_reader :editor
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/descender.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles finding the descendants of a class.
+      class Descender < Abstract
+        def initialize(collector: ObjectSpace, **)
+          @collector = collector
+          super(**)
+        end
+
+        def call name
+          collect(name).then { |all| all.empty? ? "No descendants found." : all.join("\n") }
+                       .then { |result| io.puts result }
+        rescue NameError
+          io.puts "ERROR: #{name.inspect} doesn't exist."
+        end
+
+        private
+
+        attr_reader :collector
+
+        def collect name
+          superclass = Object.const_get name
+
+          collector.each_object(Class)
+                   .select { |subclass| subclass < superclass }
+                   .tap { |descendants| descendants.delete superclass }
+                   .map(&:to_s)
+                   .sort
+        end
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/editor.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles editing of source code.
+      class Editor < Abstract
+        def initialize(environment: ENV, kernel: Kernel, **)
+          @environment = environment
+          @kernel = kernel
+          super(**)
+        end
+
+        def call path, line = nil
+          path_and_line = [path, line].join ":"
+
+          if path && Pathname(path).exist?
+            io.puts "Editing: #{path_and_line}..."
+            kernel.system %(#{environment.fetch "EDITOR"} #{path_and_line})
+          else
+            io.puts "ERROR (invalid path): #{path}."
+          end
+        rescue KeyError then io.puts "ERROR: The `EDITOR` environment variable must be defined."
+        end
+
+        private
+
+        attr_reader :environment, :kernel
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/method_editor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles editing of method source code.
+      class MethodEditor < Abstract
+        def initialize(editor: Editor.new, **)
+          @editor = editor
+          super(**)
+        end
+
+        def call object, name
+          editor.call(*object.method(name).source_location)
+        rescue NameError
+          io.puts "ERROR: Undefined method `#{name.inspect}` for `#{object.inspect}`."
+        end
+
+        private
+
+        attr_reader :editor
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/paster.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles pasting content from the macOS clipboard.
+      class Paster < Abstract
+        def initialize(processor: IO, **)
+          @processor = processor
+          super(**)
+        end
+
+        def call
+          processor.popen "pbpaste", "r", &:read
+        rescue Errno::ENOENT
+          io.puts "ERROR: Unable to paste since `pbpaste` is only supported on macOS."
+        end
+
+        private
+
+        attr_reader :processor
+      end
+    end
+  end
+end

data/lib/irb/kit/handlers/searcher.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module IRB
+  module Kit
+    module Handlers
+      # Handles searching an object's methods by pattern.
+      class Searcher < Abstract
+        def initialize(matcher: Regexp, **)
+          @matcher = matcher
+          super(**)
+        end
+
+        def call object, pattern
+          object.methods
+                .grep(matcher.new(pattern))
+                .join("\n")
+                .then { |result| result.empty? ? io.puts("No matches found.") : io.puts(result) }
+        rescue TypeError
+          io.puts "ERROR: Use only a string or regular expression for the pattern."
+        end
+
+        private
+
+        attr_reader :matcher
+      end
+    end
+  end
+end

data/lib/irb/kit/helpers/clip.rb

@@ -9,20 +9,16 @@ module IRB
 
         description "Copy input to macOS clipboard."
 
-        def initialize io = IO
+        def initialize handler: Handlers::Clipper.new
           super()
-          @io = io
+          @handler = handler
         end
 
-        def execute(*lines)
-          io.popen("pbcopy", "w") { |clipboard| clipboard.write lines.join("\n") }
-        rescue Errno::ENOENT
-          "ERROR: Unable to copy since `pbcopy` is only supported on macOS."
-        end
+        def execute(*) = handler.call(*)
 
         private
 
-        attr_reader :io
+        attr_reader :handler
       end
     end
   end

data/lib/irb/kit/helpers/edit_source.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module IRB
+  module Kit
+    module Helpers
+      # Edits the source code of a constant or method.
+      class EditSource < IRB::HelperMethod::Base
+        MONIKER = :esource
+
+        description "Edit the source code of a constant or method in your default editor."
+
+        def initialize constant_handler: Handlers::ConstantEditor.new,
+                       method_handler: Handlers::MethodEditor.new
+          super()
+          @constant_handler = constant_handler
+          @method_handler = method_handler
+        end
+
+        def execute(*arguments)
+          case arguments
+            in [name] then puts constant_handler.call(name)
+            in [object, name] then puts method_handler.call(object, name)
+            else puts "ERROR: Invalid constant or method for arguments: #{arguments.inspect}."
+          end
+        end
+
+        private
+
+        attr_reader :constant_handler, :method_handler
+      end
+    end
+  end
+end

data/lib/irb/kit/helpers/paste.rb

@@ -9,20 +9,16 @@ module IRB
 
         description "Paste last entry from macOS clipboard."
 
-        def initialize io = IO
+        def initialize handler: Handlers::Paster.new
           super()
-          @io = io
+          @handler = handler
         end
 
-        def execute
-          io.popen "pbpaste", "r", &:read
-        rescue Errno::ENOENT
-          "ERROR: Unable to paste since `pbpaste` is only supported on macOS."
-        end
+        def execute = handler.call
 
         private
 
-        attr_reader :io
+        attr_reader :handler
       end
     end
   end

data/lib/irb/kit/helpers/search.rb

@@ -9,20 +9,16 @@ module IRB
 
         description "Search an object's methods by pattern."
 
-        def initialize regex = Regexp
+        def initialize handler: Handlers::Searcher.new
           super()
-          @regex = regex
+          @handler = handler
         end
 
-        def execute object, pattern
-          object.methods.grep regex.new(pattern)
-        rescue TypeError
-          "ERROR: Use only a string or regular expression for the pattern."
-        end
+        def execute(*) = handler.call(*)
 
         private
 
-        attr_reader :regex
+        attr_reader :handler
       end
     end
   end

data/lib/irb/kit/{loader.rb → register.rb}

@@ -3,7 +3,7 @@
 module IRB
   module Kit
     # Loads extensions for namespace.
-    class Loader
+    class Register
       ALL = [:all].freeze
 
       def initialize registrar, namespace, all: ALL
@@ -12,15 +12,15 @@ module IRB
         @all = all
       end
 
-      def call(*monikers) = monikers == all ? register_all : register_selected(*monikers)
+      def call(*monikers) = monikers == all ? maximum : only(*monikers)
 
       private
 
       attr_reader :registrar, :namespace, :all
 
-      def register_all = constants.each { |helper| registrar.register helper::MONIKER, helper }
+      def maximum = constants.each { |helper| registrar.register helper::MONIKER, helper }
 
-      def register_selected(*monikers)
+      def only(*monikers)
         constants.select { |helper| monikers.include? helper::MONIKER }
                  .then { |selected| monikers.zip selected }
                  .each { |moniker, helper| registrar.register moniker, helper }

data/lib/irb/kit.rb

@@ -17,7 +17,9 @@ module IRB
       @loader ||= registry.loaders.find { |loader| loader.tag == "irb-kit" }
     end
 
-    def self.register_helpers(*) = Loader.new(IRB::HelperMethod, :Helpers).call(*)
+    def self.register_commands(*) = Register.new(IRB::Command, :Commands).call(*)
+
+    def self.register_helpers(*) = Register.new(IRB::HelperMethod, :Helpers).call(*)
 
     def self.prompt = @prompt ||= Prompter.new.call
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: irb-kit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-05-31 00:00:00.000000000 Z
+date: 2024-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: irb
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '1.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '1.14'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -78,13 +78,21 @@ files:
 - README.adoc
 - irb-kit.gemspec
 - lib/irb/kit.rb
+- lib/irb/kit/commands/descendants.rb
+- lib/irb/kit/handlers/abstract.rb
+- lib/irb/kit/handlers/clipper.rb
+- lib/irb/kit/handlers/constant_editor.rb
+- lib/irb/kit/handlers/descender.rb
+- lib/irb/kit/handlers/editor.rb
+- lib/irb/kit/handlers/method_editor.rb
+- lib/irb/kit/handlers/paster.rb
+- lib/irb/kit/handlers/searcher.rb
 - lib/irb/kit/helpers/clip.rb
-- lib/irb/kit/helpers/constant_source.rb
-- lib/irb/kit/helpers/method_source.rb
+- lib/irb/kit/helpers/edit_source.rb
 - lib/irb/kit/helpers/paste.rb
 - lib/irb/kit/helpers/search.rb
-- lib/irb/kit/loader.rb
 - lib/irb/kit/prompter.rb
+- lib/irb/kit/register.rb
 homepage: https://alchemists.io/projects/irb-kit
 licenses:
 - Hippocratic-2.1
@@ -111,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.14
 signing_key:
 specification_version: 4
 summary: Extends IRB by providing additional productivity enhancements.

data/lib/irb/kit/helpers/constant_source.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module IRB
-  module Kit
-    module Helpers
-      # Finds constant's source location.
-      class ConstantSource < IRB::HelperMethod::Base
-        MONIKER = :csource
-
-        description "Find a constant's source location."
-
-        def initialize object = Object, delimiter: ":"
-          super()
-          @object = object
-          @delimiter = delimiter
-        end
-
-        def execute name
-          object.const_source_location(name).then { |details| details.join delimiter if details }
-        rescue NameError
-          "ERROR: Invalid constant (#{name.inspect})."
-        end
-
-        private
-
-        attr_reader :object, :delimiter
-      end
-    end
-  end
-end

data/lib/irb/kit/helpers/method_source.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module IRB
-  module Kit
-    module Helpers
-      # Find an object method's source location.
-      class MethodSource < IRB::HelperMethod::Base
-        MONIKER = :msource
-
-        description "Find an object method's source location."
-
-        def initialize delimiter: ":"
-          super()
-          @delimiter = delimiter
-        end
-
-        def execute object, name
-          object.method(name).source_location.then { |details| details.join delimiter if details }
-        rescue NameError => error
-          "ERROR: #{error.message}"
-        end
-
-        private
-
-        attr_reader :delimiter
-      end
-    end
-  end
-end