From 3f15d35f83dc91e1e5af6d98e6f6fcd52abd1649 Mon Sep 17 00:00:00 2001 From: drbrain Date: Sun, 20 Oct 2013 01:33:19 +0000 Subject: * lib/rubygems: Update RubyGems to master 0886307. This commit improves documentation and should bring ruby above 75% documented on rubyci. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43369 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/rubygems/user_interaction.rb | 180 +++++++++++++++++++++++++++++++++------ 1 file changed, 154 insertions(+), 26 deletions(-) (limited to 'lib/rubygems/user_interaction.rb') diff --git a/lib/rubygems/user_interaction.rb b/lib/rubygems/user_interaction.rb index 0974476507..0e4449a2ec 100644 --- a/lib/rubygems/user_interaction.rb +++ b/lib/rubygems/user_interaction.rb @@ -66,9 +66,13 @@ module Gem::DefaultUserInteraction end ## -# Make the default UI accessible without the "ui." prefix. Classes -# including this module may use the interaction methods on the default UI -# directly. Classes may also reference the ui and ui= methods. +# UserInteraction allows RubyGems to interact with the user through standard +# methods that can be replaced with more-specific UI methods for different +# displays. +# +# Since UserInteraction dispatches to a concrete UI class you may need to +# reference other classes for specific behavior such as Gem::ConsoleUI or +# Gem::SilentUI. # # Example: # @@ -84,40 +88,69 @@ module Gem::UserInteraction include Gem::DefaultUserInteraction - def alert(*args) - ui.alert(*args) + ## + # Displays an alert +statement+. Asks a +question+ if given. + + def alert statement, question = nil + ui.alert statement, question end - def alert_error(*args) - ui.alert_error(*args) + ## + # Displays an error +statement+ to the error output location. Asks a + # +question+ if given. + + def alert_error statement, question = nil + ui.alert_error statement, question end - def alert_warning(*args) - ui.alert_warning(*args) + ## + # Displays a warning +statement+ to the warning output location. Asks a + # +question+ if given. + + def alert_warning statement, question = nil + ui.alert_warning statement, question end - def ask(*args) - ui.ask(*args) + ## + # Asks a +question+ and returns the answer. + + def ask question + ui.ask question end - def ask_for_password(*args) - ui.ask_for_password(*args) + ## + # Asks for a password with a +prompt+ + + def ask_for_password prompt + ui.ask_for_password prompt end - def ask_yes_no(*args) - ui.ask_yes_no(*args) + ## + # Asks a yes or no +question+. Returns true for yes, false for no. + + def ask_yes_no question, default = nil + ui.ask_yes_no question, default end - def choose_from_list(*args) - ui.choose_from_list(*args) + ## + # Asks the user to answer +question+ with an answer from the given +list+. + + def choose_from_list question, list + ui.choose_from_list question, list end - def say(*args) - ui.say(*args) + ## + # Displays the given +statement+ on the standard output (or equivalent). + + def say statement = '' + ui.say statement end - def terminate_interaction(*args) - ui.terminate_interaction(*args) + ## + # Terminates the RubyGems process with the given +exit_code+ + + def terminate_interaction exit_code = 0 + ui.terminate_interaction exit_code end end @@ -126,7 +159,26 @@ end class Gem::StreamUI - attr_reader :ins, :outs, :errs + ## + # The input stream + + attr_reader :ins + + ## + # The output stream + + attr_reader :outs + + ## + # The error stream + + attr_reader :errs + + ## + # Creates a new StreamUI wrapping +in_stream+ for user input, +out_stream+ + # for standard output, +err_stream+ for error output. If +usetty+ is true + # then special operations (like asking for passwords) will use the TTY + # commands to disable character echo. def initialize(in_stream, out_stream, err_stream=STDERR, usetty=true) @ins = in_stream @@ -135,6 +187,9 @@ class Gem::StreamUI @usetty = usetty end + ## + # Returns true if TTY methods should be used on this StreamUI. + def tty? if RUBY_VERSION < '1.9.3' and RUBY_PLATFORM =~ /mingw|mswin/ then @usetty @@ -310,8 +365,7 @@ class Gem::StreamUI end ## - # Display a warning in a location expected to get error messages. Will - # ask +question+ if it is not nil. + # Display a warning on stderr. Will ask +question+ if it is not nil. def alert_warning(statement, question=nil) @errs.puts "WARNING: #{statement}" @@ -364,14 +418,29 @@ class Gem::StreamUI # An absolutely silent progress reporter. class SilentProgressReporter + + ## + # The count of items is never updated for the silent progress reporter. + attr_reader :count + ## + # Creates a silent progress reporter that ignores all input arguments. + def initialize(out_stream, size, initial_message, terminal_message = nil) end + ## + # Does not print +message+ when updated as this object has taken a vow of + # silence. + def updated(message) end + ## + # Does not print anything when complete as this object has taken a vow of + # silence. + def done end end @@ -383,8 +452,16 @@ class Gem::StreamUI include Gem::DefaultUserInteraction + ## + # The number of progress items counted so far. + attr_reader :count + ## + # Creates a new progress reporter that will write to +out_stream+ for + # +size+ items. Shows the given +initial_message+ when progress starts + # and the +terminal_message+ when it is complete. + def initialize(out_stream, size, initial_message, terminal_message = "complete") @out = out_stream @@ -420,8 +497,16 @@ class Gem::StreamUI include Gem::DefaultUserInteraction + ## + # The number of progress items counted so far. + attr_reader :count + ## + # Creates a new progress reporter that will write to +out_stream+ for + # +size+ items. Shows the given +initial_message+ when progress starts + # and the +terminal_message+ when it is complete. + def initialize(out_stream, size, initial_message, terminal_message = 'complete') @out = out_stream @@ -468,15 +553,30 @@ class Gem::StreamUI # An absolutely silent download reporter. class SilentDownloadReporter + + ## + # The silent download reporter ignores all arguments + def initialize(out_stream, *args) end + ## + # The silent download reporter does not display +filename+ or care about + # +filesize+ because it is silent. + def fetch(filename, filesize) end + ## + # Nothing can update the silent download reporter. + def update(current) end + ## + # The silent download reporter won't tell you when the download is done. + # Because it is silent. + def done end end @@ -485,13 +585,35 @@ class Gem::StreamUI # A progress reporter that prints out messages about the current progress. class VerboseDownloadReporter - attr_reader :file_name, :total_bytes, :progress + + ## + # The current file name being displayed + + attr_reader :file_name + + ## + # The total bytes in the file + + attr_reader :total_bytes + + ## + # The current progress (0 to 100) + + attr_reader :progress + + ## + # Creates a new verbose download reporter that will display on + # +out_stream+. The other arguments are ignored. def initialize(out_stream, *args) @out = out_stream @progress = 0 end + ## + # Tells the download reporter that the +file_name+ is being fetched and + # contains +total_bytes+. + def fetch(file_name, total_bytes) @file_name = file_name @total_bytes = total_bytes.to_i @@ -500,6 +622,9 @@ class Gem::StreamUI update_display(false) end + ## + # Updates the verbose download reporter for the given number of +bytes+. + def update(bytes) new_progress = if @units == 'B' then bytes @@ -513,6 +638,9 @@ class Gem::StreamUI update_display end + ## + # Indicates the download is complete. + def done @progress = 100 if @units == '%' update_display(true, true) @@ -520,7 +648,7 @@ class Gem::StreamUI private - def update_display(show_progress = true, new_line = false) + def update_display(show_progress = true, new_line = false) # :nodoc: return unless @out.tty? if show_progress then -- cgit v1.2.3