class Gem::StreamUI

Gem::StreamUI implements a simple stream based user interface.

Attributes

errs[R]

The error stream

ins[R]

The input stream

outs[R]

The output stream

Public Class Methods

new(in_stream, out_stream, err_stream=STDERR, usetty=true) click to toggle source

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.

# File lib/rubygems/user_interaction.rb, line 197
def initialize(in_stream, out_stream, err_stream=STDERR, usetty=true)
  @ins = in_stream
  @outs = out_stream
  @errs = err_stream
  @usetty = usetty
end

Public Instance Methods

_gets_noecho() click to toggle source
# File lib/rubygems/user_interaction.rb, line 321
def _gets_noecho
  require_io_console
  @ins.noecho {@ins.gets}
end
alert(statement, question=nil) click to toggle source

Display an informational alert. Will ask question if it is not nil.

# File lib/rubygems/user_interaction.rb, line 336
def alert(statement, question=nil)
  @outs.puts "INFO:  #{statement}"
  ask(question) if question
end
alert_error(statement, question=nil) click to toggle source

Display an error message in a location expected to get error messages. Will ask question if it is not nil.

# File lib/rubygems/user_interaction.rb, line 353
def alert_error(statement, question=nil)
  @errs.puts "ERROR:  #{statement}"
  ask(question) if question
end
alert_warning(statement, question=nil) click to toggle source

Display a warning on stderr. Will ask question if it is not nil.

# File lib/rubygems/user_interaction.rb, line 344
def alert_warning(statement, question=nil)
  @errs.puts "WARNING:  #{statement}"
  ask(question) if question
end
ask(question) click to toggle source

Ask a question. Returns an answer if connected to a tty, nil otherwise.

# File lib/rubygems/user_interaction.rb, line 285
def ask(question)
  return nil if not tty?

  @outs.print(question + "  ")
  @outs.flush

  result = @ins.gets
  result.chomp! if result
  result
end
ask_for_password(question) click to toggle source

Ask for a password. Does not echo response to terminal.

# File lib/rubygems/user_interaction.rb, line 299
def ask_for_password(question)
  return nil if not tty?

  @outs.print(question, "  ")
  @outs.flush

  password = _gets_noecho
  @outs.puts
  password.chomp! if password
  password
end
ask_yes_no(question, default=nil) click to toggle source

Ask a question. Returns a true for yes, false for no. If not connected to a tty, raises an exception if default is nil, otherwise returns default.

# File lib/rubygems/user_interaction.rb, line 249
def ask_yes_no(question, default=nil)
  unless tty?
    if default.nil?
      raise Gem::OperationNotSupportedError,
            "Not connected to a tty and no default specified"
    else
      return default
    end
  end

  default_answer = case default
                   when nil
                     'yn'
                   when true
                     'Yn'
                   else
                     'yN'
                   end

  result = nil

  while result.nil? do
    result = case ask "#{question} [#{default_answer}]"
             when /^y/i then true
             when /^n/i then false
             when /^$/  then default
             else            nil
             end
  end

  return result
end
backtrace(exception) click to toggle source

Prints a formatted backtrace to the errors stream if backtraces are enabled.

# File lib/rubygems/user_interaction.rb, line 215
  def backtrace(exception)
    return unless Gem.configuration.backtrace

    @errs.puts "\t#{exception.backtrace.join "\n\t"}"
  end

  ##
  # Choose from a list of options.  +question+ is a prompt displayed above
  # the list.  +list+ is a list of option strings.  Returns the pair
  # [option_name, option_index].

  def choose_from_list(question, list)
    @outs.puts question

    list.each_with_index do |item, index|
      @outs.puts " #{index+1}. #{item}"
    end

    @outs.print "> "
    @outs.flush

    result = @ins.gets

    return nil, nil unless result

    result = result.strip.to_i - 1
    return list[result], result
  end

  ##
  # Ask a question.  Returns a true for yes, false for no.  If not connected
  # to a tty, raises an exception if default is nil, otherwise returns
  # default.

  def ask_yes_no(question, default=nil)
    unless tty?
      if default.nil?
        raise Gem::OperationNotSupportedError,
              "Not connected to a tty and no default specified"
      else
        return default
      end
    end

    default_answer = case default
                     when nil
                       'yn'
                     when true
                       'Yn'
                     else
                       'yN'
                     end

    result = nil

    while result.nil? do
      result = case ask "#{question} [#{default_answer}]"
               when /^y/i then true
               when /^n/i then false
               when /^$/  then default
               else            nil
               end
    end

    return result
  end

  ##
  # Ask a question.  Returns an answer if connected to a tty, nil otherwise.

  def ask(question)
    return nil if not tty?

    @outs.print(question + "  ")
    @outs.flush

    result = @ins.gets
    result.chomp! if result
    result
  end

  ##
  # Ask for a password. Does not echo response to terminal.

  def ask_for_password(question)
    return nil if not tty?

    @outs.print(question, "  ")
    @outs.flush

    password = _gets_noecho
    @outs.puts
    password.chomp! if password
    password
  end

  def require_io_console
    @require_io_console ||= begin
      begin
        require 'io/console'
      rescue LoadError
      end
      true
    end
  end

  def _gets_noecho
    require_io_console
    @ins.noecho {@ins.gets}
  end

  ##
  # Display a statement.

  def say(statement="")
    @outs.puts statement
  end

  ##
  # Display an informational alert.  Will ask +question+ if it is not nil.

  def alert(statement, question=nil)
    @outs.puts "INFO:  #{statement}"
    ask(question) if question
  end

  ##
  # Display a warning on stderr.  Will ask +question+ if it is not nil.

  def alert_warning(statement, question=nil)
    @errs.puts "WARNING:  #{statement}"
    ask(question) if question
  end

  ##
  # Display an error message in a location expected to get error messages.
  # Will ask +question+ if it is not nil.

  def alert_error(statement, question=nil)
    @errs.puts "ERROR:  #{statement}"
    ask(question) if question
  end

  ##
  # Display a debug message on the same location as error messages.

  def debug(statement)
    @errs.puts statement
  end
  deprecate :debug, :none, 2018, 12

  ##
  # Terminate the application with exit code +status+, running any exit
  # handlers that might have been defined.

  def terminate_interaction(status = 0)
    close
    raise Gem::SystemExitException, status
  end

  def close
  end

  ##
  # Return a progress reporter object chosen from the current verbosity.

  def progress_reporter(*args)
    case Gem.configuration.verbose
    when nil, false
      SilentProgressReporter.new(@outs, *args)
    when true
      SimpleProgressReporter.new(@outs, *args)
    else
      VerboseProgressReporter.new(@outs, *args)
    end
  end

  ##
  # 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

  ##
  # A basic dotted progress reporter.

  class SimpleProgressReporter

    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
      @total = size
      @count = 0
      @terminal_message = terminal_message

      @out.puts initial_message
    end

    ##
    # Prints out a dot and ignores +message+.

    def updated(message)
      @count += 1
      @out.print "."
      @out.flush
    end

    ##
    # Prints out the terminal message.

    def done
      @out.puts "\n#{@terminal_message}"
    end

  end

  ##
  # A progress reporter that prints out messages about the current progress.

  class VerboseProgressReporter

    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
      @total = size
      @count = 0
      @terminal_message = terminal_message

      @out.puts initial_message
    end

    ##
    # Prints out the position relative to the total and the +message+.

    def updated(message)
      @count += 1
      @out.puts "#{@count}/#{@total}: #{message}"
    end

    ##
    # Prints out the terminal message.

    def done
      @out.puts @terminal_message
    end
  end

  ##
  # Return a download reporter object chosen from the current verbosity

  def download_reporter(*args)
    if [nil, false].include?(Gem.configuration.verbose) || !@outs.tty?
      SilentDownloadReporter.new(@outs, *args)
    else
      ThreadedDownloadReporter.new(@outs, *args)
    end
  end

  ##
  # 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

  ##
  # A progress reporter that behaves nicely with threaded downloading.

  class ThreadedDownloadReporter

    MUTEX = Mutex.new

    ##
    # The current file name being displayed

    attr_reader :file_name

    ##
    # Creates a new threaded download reporter that will display on
    # +out_stream+.  The other arguments are ignored.

    def initialize(out_stream, *args)
      @file_name = nil
      @out = out_stream
    end

    ##
    # Tells the download reporter that the +file_name+ is being fetched.
    # The other arguments are ignored.

    def fetch(file_name, *args)
      if @file_name.nil?
        @file_name = file_name
        locked_puts "Fetching #{@file_name}"
      end
    end

    ##
    # Updates the threaded download reporter for the given number of +bytes+.

    def update(bytes)
      # Do nothing.
    end

    ##
    # Indicates the download is complete.

    def done
      # Do nothing.
    end

    private
    def locked_puts(message)
      MUTEX.synchronize do
        @out.puts message
      end
    end
  end
end
choose_from_list(question, list) click to toggle source

Choose from a list of options. question is a prompt displayed above the list. list is a list of option strings. Returns the pair [option_name, option_index].

# File lib/rubygems/user_interaction.rb, line 226
def choose_from_list(question, list)
  @outs.puts question

  list.each_with_index do |item, index|
    @outs.puts " #{index+1}. #{item}"
  end

  @outs.print "> "
  @outs.flush

  result = @ins.gets

  return nil, nil unless result

  result = result.strip.to_i - 1
  return list[result], result
end
close() click to toggle source
# File lib/rubygems/user_interaction.rb, line 375
def close
end
debug(statement) click to toggle source

Display a debug message on the same location as error messages.

# File lib/rubygems/user_interaction.rb, line 361
def debug(statement)
  @errs.puts statement
end
download_reporter(*args) click to toggle source

Return a download reporter object chosen from the current verbosity

# File lib/rubygems/user_interaction.rb, line 514
def download_reporter(*args)
  if [nil, false].include?(Gem.configuration.verbose) || !@outs.tty?
    SilentDownloadReporter.new(@outs, *args)
  else
    ThreadedDownloadReporter.new(@outs, *args)
  end
end
progress_reporter(*args) click to toggle source

Return a progress reporter object chosen from the current verbosity.

# File lib/rubygems/user_interaction.rb, line 381
def progress_reporter(*args)
  case Gem.configuration.verbose
  when nil, false
    SilentProgressReporter.new(@outs, *args)
  when true
    SimpleProgressReporter.new(@outs, *args)
  else
    VerboseProgressReporter.new(@outs, *args)
  end
end
require_io_console() click to toggle source
# File lib/rubygems/user_interaction.rb, line 311
def require_io_console
  @require_io_console ||= begin
    begin
      require 'io/console'
    rescue LoadError
    end
    true
  end
end
say(statement="") click to toggle source

Display a statement.

# File lib/rubygems/user_interaction.rb, line 329
def say(statement="")
  @outs.puts statement
end
terminate_interaction(status = 0) click to toggle source

Terminate the application with exit code status, running any exit handlers that might have been defined.

# File lib/rubygems/user_interaction.rb, line 370
def terminate_interaction(status = 0)
  close
  raise Gem::SystemExitException, status
end
tty?() click to toggle source

Returns true if TTY methods should be used on this StreamUI.

# File lib/rubygems/user_interaction.rb, line 207
def tty?
  @usetty && @ins.tty?
end