class Nucleon::Util::Console

Console

The Nucleon::Util::Console class defines a console interface that the Nucleon framework uses to collect and display information to stdin, stdout, and stderr.

This console interface is inspired by Vagrant’s UI system but has some important differences.

Important rule

We split all outbound message traffic between stdout and stderr by routing all data dumps to stderr and all other text based messages to stdout (even errors).

TODO: This system will break if other libraries write to stderr. Eventually build multiple messaging systems on top of basic connection.

TODO: Figure out some way to switch to a color profile method instead of current color methods.

Remember:

If you are using this class, you don’t have to think about this but it still helps to remember.

Primary functions:

  1. Render and transmit messages to various output channels

  2. Dump data to isolated output channels

  3. Collect public and private (hidden) information from input channels

  4. Provide a color format library for composing potentially nested colored strings

See also:

Attributes

color[RW]
Boolean

Whether or not to use color markers when rendering text

This can be overridden by the global quiet setting ::quiet, ::quiet=

delegate[RW]
ANY

Any class that implements this console interface

error[RW]
IO

Error IO object (data)

Don’t touch unless you know what you are doing.

input[RW]
IO

Input IO object

Don’t touch unless you know what you are doing.

output[RW]
IO

Output IO object (messages)

Don’t touch unless you know what you are doing.

resource[RW]
String

Console resource name

This is the string identifier and default console prefix used when rendering.

Public Class Methods

black(string) click to toggle source

Color a given string black if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Black or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
660 def self.black(string)
661   colorize(string, :black)
662 end
blue(string) click to toggle source

Color a given string blue if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Blue or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
728 def self.blue(string)
729   colorize(string, :blue)
730 end
colorize(string, color) click to toggle source

Colorize a given string if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

    • String, Symbol

      color Color to use; :black, :red, :green, :yellow, :blue, :purple, :cyan, :grey

  • Returns

    • String

      Colorized or input string depending on global color flag

  • Errors

See also:

    # File lib/core/util/console.rb
627 def self.colorize(string, color)
628   return '' unless string
629   return string.to_s unless use_colors
630 
631   color        = color.to_sym
632   string       = string.to_s
633   color_string = string
634 
635   if @@colors[color]
636     color         = @@colors[color]
637     clear_color   = @@colors[:clear]
638     escaped_clear = Regexp.escape(clear_color)
639 
640     color_string  = "#{color}"
641     color_string << string.gsub(/#{escaped_clear}(?!\e\[)/, "#{clear_color}#{color}")
642     color_string << "#{clear_color}"
643   end
644   color_string
645 end
cyan(string) click to toggle source

Color a given string cyan if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Cyan or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
762 def self.cyan(string)
763   colorize(string, :cyan)
764 end
green(string) click to toggle source

Color a given string green if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Green or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
694 def self.green(string)
695   colorize(string, :green)
696 end
grey(string) click to toggle source

Color a given string grey if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Grey or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
779 def self.grey(string)
780   colorize(string, :grey)
781 end
new(options = {}) click to toggle source

Initialize a new console object

TODO: Figure out some way to make the console system pluggable?

  • Parameters

    • Hash

      options Console options

      • String

        :resource Logger resource identifier (also serves as prefix)

      • Boolean

        :color Whether or not to render messages in color (overridden by global quiet)

      • Symbol

        :printer Printer method (default :puts)

      • IO

        :input Don’t touch

      • IO

        :output Don’t touch

      • IO

        :error Don’t touch

      • ANY

        :console_delegate Delegate object that handles console operations (must implement logging interface)

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
 97 def initialize(options = {})
 98   if options.is_a?(String)
 99     options = { :resource => options }
100   end
101   config = Config.ensure(options)
102 
103   @resource = config.get(:resource, '')
104 
105   @color   = config.get(:color, true)
106   @printer = config.get(:printer, :puts)
107 
108   @input  = config.get(:input, $stdin)
109   @output = config.get(:output, $stdout)
110   @error  = config.get(:error, $stderr)
111 
112   @delegate = config.get(:console_delegate, nil)
113 end
purple(string) click to toggle source

Color a given string purple if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Purple or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
745 def self.purple(string)
746   colorize(string, :purple)
747 end
quiet() click to toggle source

Check current global quiet flag

  • Parameters

  • Returns

    • Boolean

      Whether or not console output is disabled at the global level

  • Errors

See also:

    # File lib/core/util/console.rb
183 def self.quiet
184   @@quiet
185 end
quiet=(quiet) click to toggle source

Set current global quiet flag

  • Parameters

    • Boolean

      quiet Whether or not console output is disabled at the global level

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
200 def self.quiet=quiet
201   @@quiet = quiet
202 end
red(string) click to toggle source

Color a given string red if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Red or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
677 def self.red(string)
678   colorize(string, :red)
679 end
use_colors() click to toggle source

Check current global use colors flag

  • Parameters

  • Returns

    • Boolean

      Whether or not console output coloring is allowed at the global level

  • Errors

See also:

    # File lib/core/util/console.rb
220 def self.use_colors
221   @@use_colors && ! ENV['NUCLEON_NO_COLOR']
222 end
use_colors=(use_colors) click to toggle source

Set current global use colors flag

  • Parameters

    • Boolean

      use_colors Whether or not console output coloring is allowed at the global level

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
237 def self.use_colors=use_colors
238   @@use_colors = use_colors
239 end
yellow(string) click to toggle source

Color a given string yellow if global colors enabled, else return input string.

  • Parameters

    • String, Symbol

      string String to colorize (if colors allowed globally)

  • Returns

    • String

      Yellow or uncolored input string depending on global color flag

  • Errors

See:

    # File lib/core/util/console.rb
711 def self.yellow(string)
712   colorize(string, :yellow)
713 end

Public Instance Methods

ask(message, options = {}) click to toggle source

Ask terminal user for an input value

Input text can be freely displayed or hidden as typed.

  • Parameters

    • String

      message Message to display to the user

    • Hash

      options Input options

      • Boolean

        :new_line Append new line to end of message

      • Boolean

        :prefix Render prefix before message (console resource)

      • Boolean

        :echo Whether or not to echo the input back to the screen

      • say options (minus :quiet_override)

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
331 def ask(message, options = {})
332   return @delegate.ask(message, options) if check_delegate('ask')
333 
334   options[:new_line] = false if ! options.has_key?(:new_line)
335   options[:prefix] = false if ! options.has_key?(:prefix)
336   options[:echo] = true if ! options.has_key?(:echo)
337 
338   user_input = nil
339 
340   say(:info, message, Config.ensure(options).import({
341     :quiet_override => true,
342     :new_line => false
343   }).export)
344 
345   if options[:echo]
346     user_input = @input.gets.chomp
347   else
348     require 'io/console'
349     user_input = @input.noecho(&:gets).chomp
350   end
351   safe_puts("\n")
352   user_input
353 end
check_delegate(method) click to toggle source

Check if a registered delegate exists and responds to a specified method.

  • Parameters

    • String, Symbol

      method Method to check in delegate if registered

  • Returns

    • Boolean

      Whether a delegate that responds to method exists

  • Errors

    # File lib/core/util/console.rb
606 def check_delegate(method)
607   return Util::Data.test(@delegate && @delegate.respond_to?(method.to_s))
608 end
dump(data, options = {}) click to toggle source

Dump an object to an output channel even if quiet specified

Data dumps can not be silenced.

  • Parameters

    • String

      data Serialized data object or text string

    • Hash

      options Dump options

      • Symbol

        :channel IO channel to send output to (don’t touch)

      • safe_puts options

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
300 def dump(data, options = {})
301   return @delegate.dump(data, options) if check_delegate('dump')
302 
303   options[:channel] = options.has_key?(:channel) ? options[:channel] : @error
304   safe_puts(data.to_s, options)
305 end
format_message(type, message, options = {}) click to toggle source

Format a message for display.

Primary functions:

  1. Add prefix to each line if requested (:prefix)

  2. Add colors to each line if requested (global and instance color enabled)

  • Parameters

    • Symbol

      type Message type; :warn, :error, :success

    • String

      message Message to render

    • Hash

      options Format options

      • Boolean

        :color Color to use; :black, :red, :green, :yellow, :blue, :purple, :cyan, :grey

      • Boolean

        :prefix Render prefix before message

      • String

        :prefix_text Text to render within brackets [{prefix_text}] (default console resource)

  • Returns

    • String

      Formatted string ready for output

  • Errors

See also:

    # File lib/core/util/console.rb
512 def format_message(type, message, options = {})
513   return @delegate.format_message(type, message, options) if check_delegate('format_message')
514   return '' if message.to_s.strip.empty?
515 
516   if options[:prefix]
517     if prefix_text = options[:prefix_text]
518       prefix = "[#{prefix_text}]"
519 
520     elsif @resource && ! @resource.empty?
521       prefix = "[#{@resource}]"
522     end
523   end
524 
525   lines         = []
526   prev_color    = nil
527   escaped_clear = Regexp.escape(@@colors[:clear])
528 
529   message.split("\n").each do |line|
530     line = prev_color + line if self.class.use_colors && @color && prev_color
531 
532     lines << "#{prefix} #{line}".sub(/^ /, '')
533 
534     if self.class.use_colors && @color
535       # Set next previous color
536       if line =~ /#{escaped_clear}$/
537         prev_color = nil
538       else
539         line_section = line.split(/#{escaped_clear}/).pop
540 
541         if line_section
542           prev_colors = line_section.scan(/\e\[[0-9][0-9]?m/)
543           prev_color  = prev_colors.pop unless prev_colors.empty?
544         end
545       end
546     end
547   end
548 
549   message = lines.join("\n")
550 
551   if self.class.use_colors && @color
552     if options.has_key?(:color)
553       message = self.class.colorize(message, options[:color])
554     else
555       message = self.class.colorize(message, @@color_map[type]) if @@color_map[type]
556     end
557   end
558   return message
559 end
info(message, *args) click to toggle source

Output information to an output channel unless quiet specified

  • Parameters

    • String

      message Message to render to output channel

    • Hash

      options Output options

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
415 def info(message, *args)
416   return @delegate.info(message, *args) if check_delegate('info')
417   say(:info, message, *args)
418 end
inspect() click to toggle source

Return a string reference that identifies this console object

  • Parameters

  • Returns

    • String

      Identification string

  • Errors

    # File lib/core/util/console.rb
124 def inspect
125   "#<#{self.class}: #{@resource}>"
126 end
password(type, options = {}) click to toggle source

Ask terminal user for a password

Keeps requesting until two password inputs match or user cancels the input.

TODO: Needs I18n treatment.

  • Parameters

    • String, Symbol

      type Type of password being requested (in prompt)

    • Hash

      options Input options

  • Returns

    • String

      Returns password with whitespace stripped

  • Errors

See also:

    # File lib/core/util/console.rb
374 def password(type, options = {})
375   return @delegate.password(type, options) if check_delegate('password')
376 
377   try_again = true
378   password  = nil
379 
380   while try_again
381     # Get and check a password from the keyboard
382     password              = ask("Enter #{type} password: ", { :echo => false })
383     confirmation_password = ask("Confirm #{type} password: ", { :echo => false })
384 
385     if password != confirmation_password
386       choice    = ask('Passwords do not match!  Try again? (Y|N): ')
387       try_again = choice.upcase == "Y"
388       password  = nil unless try_again
389     else
390       try_again = false
391     end
392   end
393   password = password.strip if password
394   password
395 end
safe_puts(message = nil, options = {}) click to toggle source

Safely output via a printer method to an output channel unless quiet specified

  • Parameters

    • String

      message Message to render to output channel

    • Hash

      options Output options

      • Symbol

        :channel IO channel to send output to (don’t touch)

      • Symbol

        :printer Printer method to use; :puts, :print

  • Returns

    • Void

      This method does not return a value

  • Errors

    • Errno::EPIPE

      Error if sending of output to communication channel fails

See also:

    # File lib/core/util/console.rb
578 def safe_puts(message = nil, options = {})
579   return @delegate.safe_puts(message, options) if check_delegate('safe_puts')
580 
581   message ||= ""
582   options = {
583     :channel => @output,
584     :printer => @printer,
585   }.merge(options)
586 
587   begin
588     options[:channel].send(options[:printer], message)
589   rescue Errno::EPIPE
590     return
591   end
592 end
say(type, message, options = {}) click to toggle source

Output via a printer method to an output channel unless quiet specified

  • Parameters

    • Symbol

      type Message type; :warn, :error, :success

    • String

      message Message to render to output channel

    • Hash

      options Output options

      • Boolean

        :quiet_override Whether or not to override global quiet flag

      • Boolean

        :new_line Append new line to end of message

      • Boolean

        :prefix Render prefix before message (console resource)

      • Symbol

        :channel IO channel to send output to (don’t touch)

      • format_message options

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
266 def say(type, message, options = {})
267   return if @@quiet && ! options[:quiet_override]
268   return @delegate.say(type, message, options) if check_delegate('say')
269 
270   defaults = { :new_line => true, :prefix => true }
271   options  = defaults.merge(options)
272   printer  = options[:new_line] ? :puts : :print
273   suffix   = options[:new_line] ? "\n" : ''
274 
275   puts_options           = { :printer => printer }
276   puts_options[:channel] = options[:channel] if options.has_key?(:channel)
277 
278   safe_puts(format_message(type, message, options) + suffix, puts_options)
279 end
success(message, *args) click to toggle source

Output success message to an output channel unless quiet specified

  • Parameters

    • String

      message Message to render to output channel

    • Hash

      options Output options

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
478 def success(message, *args)
479   return @delegate.success(message, *args) if check_delegate('success')
480   say(:success, message, *args)
481 end
warn(message, *args) click to toggle source

Output warning to an output channel unless quiet specified

  • Parameters

    • String

      message Message to render to output channel

    • Hash

      options Output options

  • Returns

    • Void

      This method does not return a value

  • Errors

See also:

    # File lib/core/util/console.rb
436 def warn(message, *args)
437   return @delegate.warn(message, *args) if check_delegate('warn')
438   say(:warn, message, *args)
439 end