From b695f58d52ec047e44434c16c998c4a67d3e5571 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Thu, 18 May 2023 12:28:27 +0900 Subject: [ruby/irb] Print deprecation warning for `help` command (https://github.com/ruby/irb/pull/567) * Give show_doc its own command class * Print deprecation warning for `help` command --- lib/irb/cmd/help.rb | 56 ++++++++++------------------------------------- lib/irb/cmd/show_doc.rb | 48 ++++++++++++++++++++++++++++++++++++++++ lib/irb/extend-command.rb | 6 ++++- test/irb/test_cmd.rb | 38 ++++++++++++++++++++++---------- 4 files changed, 91 insertions(+), 57 deletions(-) create mode 100644 lib/irb/cmd/show_doc.rb diff --git a/lib/irb/cmd/help.rb b/lib/irb/cmd/help.rb index 539d20a119..64b885c383 100644 --- a/lib/irb/cmd/help.rb +++ b/lib/irb/cmd/help.rb @@ -1,55 +1,23 @@ -# frozen_string_literal: false -# -# help.rb - helper using ri -# +# frozen_string_literal: true -require_relative "nop" +require_relative "show_doc" module IRB - # :stopdoc: - module ExtendCommand - class Help < Nop - class << self - def transform_args(args) - # Return a string literal as is for backward compatibility - if args.empty? || string_literal?(args) - args - else # Otherwise, consider the input as a String for convenience - args.strip.dump - end - end - end - + class Help < ShowDoc category "Context" - description "Enter the mode to look up RI documents." - - def execute(*names) - require 'rdoc/ri/driver' - - unless self.class.const_defined?(:Ri) - opts = RDoc::RI::Driver.process_args([]) - self.class.const_set(:Ri, RDoc::RI::Driver.new(opts)) - end + description "[DEPRECATED] Enter the mode to look up RI documents." - if names.empty? - Ri.interactive - else - names.each do |name| - begin - Ri.display_name(name.to_s) - rescue RDoc::RI::Error - puts $!.message - end - end - end + DEPRECATION_MESSAGE = <<~MSG + [Deprecation] The `help` command will be repurposed to display command help in the future. + For RI document lookup, please use the `show_doc` command instead. + For command help, please use `show_cmds` for now. + MSG - nil - rescue LoadError, SystemExit - warn "Can't display document because `rdoc` is not installed." + def execute(*names) + warn DEPRECATION_MESSAGE + super end end end - - # :startdoc: end diff --git a/lib/irb/cmd/show_doc.rb b/lib/irb/cmd/show_doc.rb new file mode 100644 index 0000000000..99dd9ab95a --- /dev/null +++ b/lib/irb/cmd/show_doc.rb @@ -0,0 +1,48 @@ +# frozen_string_literal: true + +require_relative "nop" + +module IRB + module ExtendCommand + class ShowDoc < Nop + class << self + def transform_args(args) + # Return a string literal as is for backward compatibility + if args.empty? || string_literal?(args) + args + else # Otherwise, consider the input as a String for convenience + args.strip.dump + end + end + end + + category "Context" + description "Enter the mode to look up RI documents." + + def execute(*names) + require 'rdoc/ri/driver' + + unless ShowDoc.const_defined?(:Ri) + opts = RDoc::RI::Driver.process_args([]) + ShowDoc.const_set(:Ri, RDoc::RI::Driver.new(opts)) + end + + if names.empty? + Ri.interactive + else + names.each do |name| + begin + Ri.display_name(name.to_s) + rescue RDoc::RI::Error + puts $!.message + end + end + end + + nil + rescue LoadError, SystemExit + warn "Can't display document because `rdoc` is not installed." + end + end + end +end diff --git a/lib/irb/extend-command.rb b/lib/irb/extend-command.rb index 1a252bb42a..e377148fb4 100644 --- a/lib/irb/extend-command.rb +++ b/lib/irb/extend-command.rb @@ -157,10 +157,14 @@ module IRB # :nodoc: [ :irb_help, :Help, "cmd/help", - [:show_doc, NO_OVERRIDE], [:help, NO_OVERRIDE], ], + [ + :irb_show_doc, :ShowDoc, "cmd/show_doc", + [:show_doc, NO_OVERRIDE], + ], + [ :irb_info, :IrbInfo, "cmd/irb_info" ], diff --git a/test/irb/test_cmd.rb b/test/irb/test_cmd.rb index c069bedb51..c5d9a0e544 100644 --- a/test/irb/test_cmd.rb +++ b/test/irb/test_cmd.rb @@ -783,19 +783,33 @@ module TestIRB end class ShowDocTest < CommandTestCase - def test_help_and_show_doc - ["help", "show_doc"].each do |cmd| - out, err = execute_lines( - "#{cmd} String#gsub\n", - "\n", - ) + def test_help + out, err = execute_lines( + "help String#gsub\n", + "\n", + ) - # the former is what we'd get without document content installed, like on CI - # the latter is what we may get locally - possible_rdoc_output = [/Nothing known about String#gsub/, /gsub\(pattern\)/] - assert_empty err - assert(possible_rdoc_output.any? { |output| output.match?(out) }, "Expect the `#{cmd}` command to match one of the possible outputs. Got:\n#{out}") - end + # the former is what we'd get without document content installed, like on CI + # the latter is what we may get locally + possible_rdoc_output = [/Nothing known about String#gsub/, /gsub\(pattern\)/] + assert_include err, "[Deprecation] The `help` command will be repurposed to display command help in the future.\n" + assert(possible_rdoc_output.any? { |output| output.match?(out) }, "Expect the `help` command to match one of the possible outputs. Got:\n#{out}") + ensure + # this is the only way to reset the redefined method without coupling the test with its implementation + EnvUtil.suppress_warning { load "irb/cmd/help.rb" } + end + + def test_show_doc + out, err = execute_lines( + "show_doc String#gsub\n", + "\n", + ) + + # the former is what we'd get without document content installed, like on CI + # the latter is what we may get locally + possible_rdoc_output = [/Nothing known about String#gsub/, /gsub\(pattern\)/] + assert_not_include err, "[Deprecation]" + assert(possible_rdoc_output.any? { |output| output.match?(out) }, "Expect the `show_doc` command to match one of the possible outputs. Got:\n#{out}") ensure # this is the only way to reset the redefined method without coupling the test with its implementation EnvUtil.suppress_warning { load "irb/cmd/help.rb" } -- cgit v1.2.1