Class: Cork::Board

Inherits:
Object
  • Object
show all
Defined in:
lib/cork/board.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(verbose: false, silent: false, ansi: true, input: $stdin, out: $stdout, err: $stderr) ⇒ Board

Initialize a new instance.

Parameters:

  • verbose (Boolean) (defaults to: false) —

    When verbose is true verbose output is printed. this defaults to true

  • silent (Boolean) (defaults to: false) —

    When silent is true all output is supressed. This defaults to false.

  • ansi (Boolean) (defaults to: true) —

    When ansi is true output may contain ansi color codes. This is true by default.

  • input (IO) (defaults to: $stdin) —

    The file descriptor to read the user input.

  • out (IO) (defaults to: $stdout) —

    The file descriptor to print all output to.

  • err (IO) (defaults to: $stderr) —

    The file descriptor to print all errors to.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# 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

Instance Attribute Details

#ansi ⇒ Object (readonly) Also known as: ansi?

Returns the value of attribute ansi.



31
32
33
 
# File 'lib/cork/board.rb', line 31

def ansi
  @ansi
end

#disable_wrap ⇒ Bool Also known as: disable_wrap?

Returns Whether the wrapping of the strings to the width of the terminal should be disabled.

Returns:

  • (Bool) —

    Whether the wrapping of the strings to the width of the terminal should be disabled.



22
23
24
 
# File 'lib/cork/board.rb', line 22

def disable_wrap
  @disable_wrap
end

#err ⇒ error (readonly)

Returns The error specification containing the UI error.

Returns:

  • (error) —

    The error specification containing the UI error.



16
17
18
 
# File 'lib/cork/board.rb', line 16

def err
  @err
end

#indentation_level ⇒ Object

Returns the value of attribute indentation_level.



34
35
36
 
# File 'lib/cork/board.rb', line 34

def indentation_level
  @indentation_level
end

#input ⇒ input (readonly)

Returns The input specification that contains the user input for the UI.

Returns:

  • (input) —

    The input specification that contains the user input for the UI.



12
13
14
 
# File 'lib/cork/board.rb', line 12

def input
  @input
end

#out ⇒ output (readonly)

Returns The output specification containing the UI output.

Returns:

  • (output) —

    The output specification containing the UI output.



14
15
16
 
# File 'lib/cork/board.rb', line 14

def out
  @out
end

#silent ⇒ Object (readonly) Also known as: silent?

Returns the value of attribute silent.



28
29
30
 
# File 'lib/cork/board.rb', line 28

def silent
  @silent
end

#verbose ⇒ Object (readonly) Also known as: verbose?

Returns the value of attribute verbose.



25
26
27
 
# File 'lib/cork/board.rb', line 25

def verbose
  @verbose
end

#warnings ⇒ warnings (readonly)

Returns The warnings specification containing the UI warnings.

Returns:

  • (warnings) —

    The warnings specification containing the UI warnings.



18
19
20
 
# File 'lib/cork/board.rb', line 18

def warnings
  @warnings
end

Instance Method Details

#gets ⇒ Object

Gets input from the configured input.



86
87
88
 
# File 'lib/cork/board.rb', line 86

def gets
  input.gets
end

#info(message) ⇒ Object

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.

Parameters:

  • message (String) —

    The message to print.



198
199
200
201
202
203
204
205
206
207
208
209
210
 
# 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) ⇒ Object

Prints a message with a label.

Parameters:

  • label (String) —

    The label to print.

  • value (#to_s) —

    The value to print.

  • justification (FixNum) (defaults to: 12) —

    The justification of the label.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# 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) ⇒ Object

TODO:

Clean interface.

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



290
291
292
293
294
295
296
297
 
# 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) ⇒ Object

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



243
244
245
246
247
 
# 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) ⇒ Object

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

Parameters:

  • pathname (#to_str, Nil) —

    The path to return.

  • relative_to (Pathname) (defaults to: Pathname.pwd) 


117
118
119
120
121
122
123
124
 
# 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) ⇒ Object

Prints a message without a new line unless silent.



72
73
74
 
# File 'lib/cork/board.rb', line 72

def print(message)
  out.print(message) unless silent?
end

#print_warnings ⇒ void

This method returns an undefined value.

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



267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/cork/board.rb', line 267

def print_warnings
  out.flush
  warnings.each do |warning|
    next if warning[:verbose_only] && !verbose?

    message = "\n[!] #{warning[:message]}"
    message = message.yellow if ansi?
    err.puts(message)

    warning[:actions].each do |action|
      string = "- #{action}"
      string = wrap_string(string, 4)
      err.puts(string)
    end
  end
end

#puts(message = '') ⇒ Object

Prints a message followed by a new line unless silent.



66
67
68
 
# File 'lib/cork/board.rb', line 66

def puts(message = '')
  out.puts(message) unless silent?
end

#puts_indented(message = '') ⇒ Object

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



79
80
81
82
 
# 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) ⇒ Object

TODO:

Refactor to title (for always visible titles like search) and sections (titles that represent collapsible sections).

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.

Parameters:

  • title (String) —

    The title to print

  • verbose_prefix (String) (defaults to: '') —

    See #message

  • relative_indentation (FixNum) (defaults to: 0) —

    The indentation level relative to the current, when the message is printed.



174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# 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) ⇒ Object

A title opposed to a section is always visible

Parameters:

  • title (String) —

    The title to print

  • verbose_prefix (String) (defaults to: '') —

    See #message

  • relative_indentation (FixNum) (defaults to: 2) —

    The indentation level relative to the current, when the message is printed.



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# 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) ⇒ Object

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]



102
103
104
105
106
107
108
 
# File 'lib/cork/board.rb', line 102

def warn(message, actions = [], verbose_only = false)
  warnings << {
    :message      => message,
    :actions      => actions,
    :verbose_only => verbose_only,
  }
end