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:
-
stderr Serialized data objects ONLY
-
stdout ALL text messages (debug, info, warnings, and errors)
If you are using this class, you don’t have to think about this but it still helps to remember.
Primary functions:
-
Render and transmit messages to various output channels
-
Dump data to isolated output channels
-
Collect public and private (hidden) information from input channels
-
Provide a color format library for composing potentially nested colored strings
See also:
-
Nucleon::Core
(base UI capable object)
Attributes
- ANY
-
Any class that implements this console interface
- IO
-
Error IO object (data)
Don’t touch unless you know what you are doing.
- IO
-
Input IO object
Don’t touch unless you know what you are doing.
- IO
-
Output IO object (messages)
Don’t touch unless you know what you are doing.
- String
-
Console
resource name
This is the string identifier and default console prefix used when rendering.
Public Class Methods
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
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 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
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
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
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
Initialize a new console object
TODO: Figure out some way to make the console system pluggable?
-
Parameters
-
- 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
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
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
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
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
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
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
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 terminal user for an input value
Input text can be freely displayed or hidden as typed.
-
Parameters
-
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 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 an object to an output channel even if quiet specified
Data
dumps can not be silenced.
-
Parameters
-
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 a message for display.
Primary functions:
-
Add prefix to each line if requested (:prefix)
-
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
Output information to an output channel unless quiet specified
-
Parameters
-
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
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
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
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
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
Output success message to an output channel unless quiet specified
-
Parameters
-
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
Output warning to an output channel unless quiet specified
-
Parameters
-
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