module Guard::UI

The UI class helps to format messages for the user. Everything that is logged through this class is considered either as an error message or a diagnostic message and is written to standard error ($stderr).

If your Guard plugin does some output that is piped into another process for further processing, please just write it to STDOUT with `puts`.

Public Class Methods

action_with_scopes(action, scope) click to toggle source

Show a scoped action message.

@param [String] action the action to show @param [Hash] scope hash with a guard or a group scope

# File lib/guard/ui.rb, line 164
def action_with_scopes(action, scope)
  titles = Guard.state.scope.titles(scope)
  info "#{action} #{titles.join(', ')}"
end
clear(opts = {}) click to toggle source

Clear the output if clearable.

# File lib/guard/ui.rb, line 134
def clear(opts = {})
  return unless Guard.state.session.clear?

  fail "UI not set up!" if @clearable.nil?
  return unless @clearable || opts[:force]

  @clearable = false
  Terminal.clear
rescue Errno::ENOENT => e
  warning("Failed to clear the screen: #{e.inspect}")
end
clearable() click to toggle source

Allow the screen to be cleared again.

# File lib/guard/ui.rb, line 155
def clearable
  @clearable = true
end
debug(message, options = {}) click to toggle source

Show a debug message that is prefixed with DEBUG and a timestamp.

@param [String] message the message to show @option options [Boolean] reset whether to clean the output before @option options [String] plugin manually define the calling plugin

# File lib/guard/ui.rb, line 122
def debug(message, options = {})
  _filtered_logger_message(message, :debug, :yellow, options)
end
deprecation(message, options = {}) click to toggle source

Show a red deprecation message that is prefixed with DEPRECATION. It has a log level of `warn`.

@param [String] message the message to show @option options [Boolean] reset whether to clean the output before @option options [String] plugin manually define the calling plugin

# File lib/guard/ui.rb, line 108
def deprecation(message, options = {})
  unless ENV["GUARD_GEM_SILENCE_DEPRECATIONS"] == "1"
    backtrace = Thread.current.backtrace[1..5].join("\n\t >")
    msg = format("%s\nDeprecation backtrace: %s", message, backtrace)
    warning(msg, options)
  end
end
error(message, options = {}) click to toggle source

Show a red error message that is prefixed with ERROR.

@param [String] message the message to show @option options [Boolean] reset whether to clean the output before @option options [String] plugin manually define the calling plugin

# File lib/guard/ui.rb, line 97
def error(message, options = {})
  _filtered_logger_message(message, :error, :red, options)
end
info(message, options = {}) click to toggle source

Show an info message.

@param [String] message the message to show @option options [Boolean] reset whether to clean the output before @option options [String] plugin manually define the calling plugin

# File lib/guard/ui.rb, line 77
def info(message, options = {})
  _filtered_logger_message(message, :info, nil, options)
end
logger() click to toggle source

Get the Guard::UI logger instance

# File lib/guard/ui.rb, line 25
def logger
  @logger ||= begin
                require "lumberjack"
                Lumberjack::Logger.new(
                  options.fetch(:device) { $stderr },
                  options
                )
              end
end
options() click to toggle source

Get the logger options

@return [Hash] the logger options

# File lib/guard/ui.rb, line 47
def options
  @options ||= Options.new(
    level: :info,
    template: ":time - :severity - :message",
    time_format: "%H:%M:%S"
  )
end
options=(options) click to toggle source

Set the logger options

@param [Hash] options the logger options @option options [Symbol] level the log level @option options [String] template the logger template @option options [String] time_format the time format

TODO: deprecate?

# File lib/guard/ui.rb, line 63
def options=(options)
  @options = Options.new(options)
end
reset_and_clear() click to toggle source

TODO: arguments: UI uses Guard::options anyway @private api

# File lib/guard/ui.rb, line 148
def reset_and_clear
  @clearable = false
  clear(force: true)
end
reset_line() click to toggle source

Reset a line.

# File lib/guard/ui.rb, line 128
def reset_line
  $stderr.print(color_enabled? ? "\r\e[0m" : "\r\n")
end
reset_logger() click to toggle source

Since logger is global, for Aruba in-process to properly separate output between calls, we need to reset

We don't use logger=() since it's expected to be a Lumberjack instance

# File lib/guard/ui.rb, line 39
def reset_logger
  @logger = nil
end
warning(message, options = {}) click to toggle source

Show a yellow warning message that is prefixed with WARNING.

@param [String] message the message to show @option options [Boolean] reset whether to clean the output before @option options [String] plugin manually define the calling plugin

# File lib/guard/ui.rb, line 87
def warning(message, options = {})
  _filtered_logger_message(message, :warn, :yellow, options)
end

Private Class Methods

_filter(plugin) { |plugin| ... } click to toggle source

Filters log messages depending on either the `:only“ or `:except` option.

@param [String] plugin the calling plugin name @yield When the message should be logged @yieldparam [String] param the calling plugin name

# File lib/guard/ui.rb, line 178
def _filter(plugin)
  only = options[:only]
  except = options[:except]
  plugin ||= calling_plugin_name

  match = !(only || except)
  match ||= (only && only.match(plugin))
  match ||= (except && !except.match(plugin))
  return unless match
  yield plugin
end
_filtered_logger_message(message, method, color_name, options = {}) click to toggle source

@private

# File lib/guard/ui.rb, line 191
def _filtered_logger_message(message, method, color_name, options = {})
  message = color(message, color_name) if color_name

  _filter(options[:plugin]) do |plugin|
    reset_line if options[:reset]
    logger.send(method, message, plugin)
  end
end
calling_plugin_name(depth = 2) click to toggle source

Tries to extract the calling Guard plugin name from the call stack.

@param [Integer] depth the stack depth @return [String] the Guard plugin name

# File lib/guard/ui.rb, line 206
def calling_plugin_name(depth = 2)
  name = %r{(guard\/[a-z_]*)(/[a-z_]*)?.rb:}i.match(caller[depth])
  return "Guard" unless name
  name[1].split("/").map do |part|
    part.split(/[^a-z0-9]/i).map(&:capitalize).join
  end.join("::")
end
color(text, *color_options) click to toggle source

Colorizes a text message. See the constant in the UI class for possible color_options parameters. You can pass optionally :bright, a foreground color and a background color.

@example

color('Hello World', :red, :bright)

@param [String] text the text to colorize @param [Array] color_options the color options

# File lib/guard/ui.rb, line 248
def color(text, *color_options)
  color_code = ""
  color_options.each do |color_option|
    color_option = color_option.to_s
    next if color_option == ""

    unless color_option =~ /\d+/
      color_option = const_get("ANSI_ESCAPE_#{ color_option.upcase }")
    end
    color_code += ";" + color_option
  end
  color_enabled? ? "\e[0#{ color_code }m#{ text }\e[0m" : text
end
color_enabled?() click to toggle source

Checks if color output can be enabled.

@return [Boolean] whether color is enabled or not

# File lib/guard/ui.rb, line 218
def color_enabled?
  @color_enabled_initialized ||= false
  @color_enabled = nil unless @color_enabled_initialized
  @color_enabled_initialized = true
  return @color_enabled unless @color_enabled.nil?
  return (@color_enabled = true) unless Gem.win_platform?
  return (@color_enabled = true) if ENV["ANSICON"]

  @color_enabled =
    begin
      require "rubygems" unless ENV["NO_RUBYGEMS"]
      require "Win32/Console/ANSI"
      true
    rescue LoadError
      info "Run 'gem install win32console' to use color on Windows"
      false
    end
end