class Cork::Board

provides support for UI output. Cork provides support for nested sections of information and for a verbose mode.

Attributes

ansi[R]
ansi?[R]
disable_wrap[RW]

@return [Bool] Whether the wrapping of the strings to the width of the

terminal should be disabled.
disable_wrap?[RW]

@return [Bool] Whether the wrapping of the strings to the width of the

terminal should be disabled.
err[R]

@return [error] The error specification containing the UI error.

indentation_level[RW]
input[R]

@return [input] The input specification that contains the user input

for the UI.
out[R]

@return [output] The output specification containing the UI output.

silent[R]
silent?[R]
title_level[RW]
verbose[R]
verbose?[R]
warnings[R]

@return [warnings] The warnings specification containing the UI warnings.

Public Class Methods

new(verbose: false, silent: false, ansi: true, input: $stdin, out: $stdout, err: $stderr) click to toggle source

Initialize a new instance.

@param [Boolean] verbose When verbose is true verbose output is printed.

this defaults to true

@param [Boolean] silent When silent is true all output is supressed.

This defaults to false.

@param [Boolean] ansi When ansi is true output may contain ansi

color codes. This is true by default.

@param [IO] input The file descriptor to read the user input. @param [IO] out The file descriptor to print all output to. @param [IO] err The file descriptor to print all errors to.

# File lib/cork/board.rb, line 49
def initialize(verbose: false, silent: false, ansi: true,
  input: $stdin, out: $stdout, err: $stderr)

  @input = input
  @out = out
  @err = err
  @verbose = verbose
  @silent = silent
  @ansi = ansi
  @warnings = []
  @title_colors      =  %w(    yellow green    )
  @title_level       =  0
  @indentation_level =  2
end

Public Instance Methods

gets() click to toggle source

Gets input from the configured input.

# File lib/cork/board.rb, line 86
def gets
  input.gets
end
info(message) { || ... } click to toggle source

Prints an info to the user. The info is always displayed. It respects the current indentation level only in verbose mode.

Any title printed in the optional block is treated as a message.

@param [String] message

The message to print.
# File lib/cork/board.rb, line 198
def info(message)
  indentation = verbose? ? @indentation_level : 0
  indented = wrap_string(message, indentation)
  puts(indented)

  if block_given?
    @indentation_level += 2
    @treat_titles_as_messages = true
    yield
    @treat_titles_as_messages = false
    @indentation_level -= 2
  end
end
labeled(label, value, justification = 12) click to toggle source

Prints a message with a label.

@param [String] label

The label to print.

@param [#to_s] value

The value to print.

@param [FixNum] justification

The justification of the label.
# File lib/cork/board.rb, line 137
def labeled(label, value, justification = 12)
  if value
    title = "- #{label}:"
    if value.is_a?(Enumerable)
      lines = [wrap_string(title, indentation_level)]
      lines += value.map do |v|
        wrap_string("- #{v}", indentation_level + 2)
      end
      puts lines.join("\n")
    else
      string = title.ljust(justification) + "#{value}"
      puts wrap_string(string, indentation_level)
    end
  end
end
message(message, verbose_prefix = '', relative_indentation = 2) { || ... } click to toggle source

Prints a verbose message taking an optional verbose prefix and a relative indentation valid for the UI action in the passed block.

@todo Clean interface.

# File lib/cork/board.rb, line 290
def message(message, verbose_prefix = '', relative_indentation = 2)
  message = verbose_prefix + message if verbose?
  puts_indented message if verbose?

  @indentation_level += relative_indentation
  yield if block_given?
  @indentation_level -= relative_indentation
end
notice(message) click to toggle source

Prints a verbose message taking an optional verbose prefix and a relatvie indentation valid for the UI action in the passed block.

# File lib/cork/board.rb, line 243
def notice(message)
  line = "\n[!] #{message}"
  line = line.green if ansi?
  puts(line)
end
path(pathname, relative_to = Pathname.pwd) click to toggle source

The returned path is quoted. If the argument is nil it returns an empty string.

@param [#to_str,Nil] pathname

The path to return.

@param [Pathname] relative_to

# File lib/cork/board.rb, line 117
def path(pathname, relative_to = Pathname.pwd)
  if pathname
    path = Pathname(pathname).relative_path_from(relative_to)
    "`#{path}`"
  else
    ''
  end
end
print(message) click to toggle source

Prints a message without a new line unless silent.

print_warnings() click to toggle source

Prints the stored warnings. This method is intended to be called at the end of the execution of the binary.

@return [void]

puts(message = '') click to toggle source

Prints a message followed by a new line unless silent.

# File lib/cork/board.rb, line 66
def puts(message = '')
  out.puts(message) unless silent?
end
puts_indented(message = '') click to toggle source

Prints a message respecting the current indentation level and wrapping it to the terminal width if necessary.

# File lib/cork/board.rb, line 79
def puts_indented(message = '')
  indented = wrap_string(message, @indentation_level)
  puts(indented)
end
section(title, verbose_prefix = '', relative_indentation = 0, titled = false) { || ... } click to toggle source

Prints a title taking an optional verbose prefix and a relative indentation valid for the UI action in the passed block.

In verbose mode titles are printed with a color according to their level. In normal mode titles are printed only if they have nesting level smaller than 2.

@todo Refactor to title (for always visible titles like search)

and sections (titles that represent collapsible sections).

@param [String] title

The title to print

@param [String] verbose_prefix

See #message

@param [FixNum] relative_indentation

The indentation level relative to the current,
when the message is printed.
# File lib/cork/board.rb, line 174
def section(title, verbose_prefix = '', relative_indentation = 0,
            titled = false)
  if verbose?
    title(title, verbose_prefix, relative_indentation)
  elsif title_level < 1 || titled
    puts title
  end

  @indentation_level += relative_indentation
  @title_level += 1
  yield if block_given?
  @indentation_level -= relative_indentation
  @title_level -= 1
end
title(title, verbose_prefix = '', relative_indentation = 2) { || ... } click to toggle source

A title opposed to a section is always visible

@param [String] title

The title to print

@param [String] verbose_prefix

See #message

@param [FixNum] relative_indentation

The indentation level relative to the current,
when the message is printed.
# File lib/cork/board.rb, line 224
def title(title, verbose_prefix = '', relative_indentation = 2)
  if @treat_titles_as_messages
    message(title, verbose_prefix)
  else
    puts_title(title, verbose_prefix)
  end

  if block_given?
    @indentation_level += relative_indentation
    @title_level += 1
    yield
    @indentation_level -= relative_indentation
    @title_level -= 1
  end
end
warn(message, actions = [], verbose_only = false) click to toggle source

Stores important warning to the user optionally followed by actions that the user should take. To print them use {#print_warnings}.

@param [String]  message The message to print.
@param [Array]   actions The actions that the user should take.
@param [Boolean] verbose_only When verbose_only is configured to
                 true, the warning will only be printed when
                 Board is configured to print verbose messages.
                 This is false by default.

@return [void]
# File lib/cork/board.rb, line 102
def warn(message, actions = [], verbose_only = false)
  warnings << {
    :message      => message,
    :actions      => actions,
    :verbose_only => verbose_only,
  }
end

Private Instance Methods

puts_title(title, verbose_prefix) click to toggle source
# File lib/cork/board.rb, line 340
def puts_title(title, verbose_prefix)
  title = verbose_prefix + title if verbose?
  title = "\n#{title}" if @title_level < 2
  if ansi? && (color = @title_colors[title_level])
    title = title.send(color)
  end
  puts "#{title}"
end
wrap_string(string, indent = 0) click to toggle source

Prints a title taking an optional verbose prefix and a relative indentation valid for the UI action in the passed block.

In verbose mode titles are printed with a color according to their level. In normal mode titles are printed only if they have nesting level smaller than 2.

@todo Refactor to title (for always visible titles like search)

and sections (titles that represent collapsible sections).

@param [String] title

The title to print

@param [String] verbose_prefix

See #message

@param [FixNum] relative_indentation

The indentation level relative to the current,
when the message is printed.
# File lib/cork/board.rb, line 328
def wrap_string(string, indent = 0)
  first_space = ' ' * indent
  if disable_wrap || !out.tty?
    first_space << string
  else
    require 'io/console'
    columns = out.winsize[1]
    indented = TextWrapper.wrap_with_indent(string, indent, columns)
    first_space << indented
  end
end