Module: CLI::UI

Defined in:
lib/cli/ui.rb,
lib/cli/ui/os.rb,
lib/cli/ui/ansi.rb,
lib/cli/ui/wrap.rb,
lib/cli/ui/color.rb,
lib/cli/ui/frame.rb,
lib/cli/ui/glyph.rb,
lib/cli/ui/table.rb,
lib/cli/ui/prompt.rb,
lib/cli/ui/printer.rb,
lib/cli/ui/spinner.rb,
lib/cli/ui/version.rb,
lib/cli/ui/widgets.rb,
lib/cli/ui/progress.rb,
lib/cli/ui/terminal.rb,
lib/cli/ui/formatter.rb,
lib/cli/ui/truncater.rb,
lib/cli/ui/work_queue.rb,
lib/cli/ui/widgets/base.rb,
lib/cli/ui/spinner/async.rb,
lib/cli/ui/stdout_router.rb,
lib/cli/ui/widgets/status.rb,
lib/cli/ui/frame/frame_stack.rb,
lib/cli/ui/frame/frame_style.rb,
lib/cli/ui/progress_reporter.rb,
lib/cli/ui/spinner/spin_group.rb,
lib/cli/ui/frame/frame_style/box.rb,
lib/cli/ui/prompt/options_handler.rb,
lib/cli/ui/frame/frame_style/bracket.rb,
lib/cli/ui/prompt/interactive_options.rb

Defined Under Namespace

Modules: ANSI, Frame, ProgressReporter, Prompt, Spinner, StdoutRouter, Table, Terminal, Truncater, Widgets Classes: Color, Formatter, Glyph, OS, Printer, Progress, WorkQueue, Wrap

Constant Summary collapse

SpinGroup =

Convenience accessor to CLI::UI::Spinner::SpinGroup

Spinner::SpinGroup
VERSION = 
'2.7.0'

Class Method Summary collapse

Class Method Details

.any_key(prompt = 'Press any key to continue') ⇒ Object

Convenience Method for CLI::UI::Prompt.any_key

Attributes

  • prompt - prompt to present

: (?String prompt) -> String?



94
95
96
 
# File 'lib/cli/ui.rb', line 94

def any_key(prompt = 'Press any key to continue')
  CLI::UI::Prompt.any_key(prompt)
end

.ask(question, options: nil, default: nil, is_file: false, allow_empty: true, multiple: false, filter_ui: true, select_ui: true, &options_proc) ⇒ Object

Convenience Method for CLI::UI::Prompt.ask : (String question, ?options: Array?, ?default: (String | Array)?, ?is_file: bool, ?allow_empty: bool, ?multiple: bool, ?filter_ui: bool, ?select_ui: bool) ?{ (Prompt::OptionsHandler handler) -> void } -> (String | Array)



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/cli/ui.rb', line 100

def ask(
  question,
  options: nil,
  default: nil,
  is_file: false,
  allow_empty: true,
  multiple: false,
  filter_ui: true,
  select_ui: true,
  &options_proc
)
  CLI::UI::Prompt.ask(
    question,
    options: options,
    default: default,
    is_file: is_file,
    allow_empty: allow_empty,
    multiple: multiple,
    filter_ui: filter_ui,
    select_ui: select_ui,
    &options_proc
  )
end

.confirm(question, default: true) ⇒ Object

Convenience Method for CLI::UI::Prompt.confirm

Attributes

  • question - question to confirm

: (String question, ?default: bool) -> bool



83
84
85
 
# File 'lib/cli/ui.rb', line 83

def confirm(question, default: true)
  CLI::UI::Prompt.confirm(question, default: default)
end

.enable_color=(bool) ⇒ Object

Turn colour in Formatter, Frame, and Spinner output on or off.

Attributes

  • bool - true or false; enable or disable colour.

: (bool bool) -> void



303
304
305
 
# File 'lib/cli/ui.rb', line 303

def enable_color=(bool)
  @enable_color = !!bool
end

.enable_color? ⇒ Boolean

Check whether colour is enabled in Formatter, Frame, and Spinner output. By default, colour is enabled when STDOUT is a TTY; that is, when output has not been directed to another program or to a file.

: -> bool

Returns:

  • (Boolean) 


292
293
294
 
# File 'lib/cli/ui.rb', line 292

def enable_color?
  @enable_color
end

.enable_cursor=(bool) ⇒ Object

Turn cursor control in Formatter, Frame, and Spinner output on or off.

Attributes

  • bool - true or false; enable or disable cursor control.

: (bool bool) -> void



323
324
325
 
# File 'lib/cli/ui.rb', line 323

def enable_cursor=(bool)
  @enable_cursor = !!bool
end

.enable_cursor? ⇒ Boolean

Check whether cursor control is enabled in Formatter, Frame, and Spinner output. By default, cursor control is enabled when STDOUT is a TTY; that is, when output has not been directed to another program or to a file.

: -> bool

Returns:

  • (Boolean) 


312
313
314
 
# File 'lib/cli/ui.rb', line 312

def enable_cursor?
  @enable_cursor
end

.fmt(input, enable_color: enable_color?) ) ⇒ Object

Convenience Method to format text using CLI::UI::Formatter.format Check CLI::UI::Formatter::SGR_MAP for available formatting options

Attributes

  • input - input to format

Options

  • enable_color - should color be used? default to true unless output is redirected.

: (String input, ?enable_color: bool) -> String



156
157
158
 
# File 'lib/cli/ui.rb', line 156

def fmt(input, enable_color: enable_color?)
  CLI::UI::Formatter.new(input).format(enable_color: enable_color)
end

.frame(text, color: Frame::DEFAULT_FRAME_COLOR, failure_text: nil, success_text: nil, timing: block_given?, , frame_style: Frame.frame_style, to: $stdout, &block) ⇒ Object

Convenience Method for CLI::UI::Frame.open

Attributes

  • args - arguments for Frame.open

  • block - block for Frame.open

: [T] (String text, ?color: colorable?, ?failure_text: String?, ?success_text: String?, ?timing: (Numeric | bool), ?frame_style: frame_stylable, ?to: io_like) ?{ -> T } -> T?



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/cli/ui.rb', line 201

def frame(
  text,
  color: Frame::DEFAULT_FRAME_COLOR,
  failure_text: nil,
  success_text: nil,
  timing: block_given?,
  frame_style: Frame.frame_style,
  to: $stdout,
  &block
)
  CLI::UI::Frame.open(
    text,
    color: color,
    failure_text: failure_text,
    success_text: success_text,
    timing: timing,
    frame_style: frame_style,
    to: to,
    &block
  )
end

.frame_style=(frame_style) ⇒ Object

Set the default frame style. Convenience method for setting the default frame style with CLI::UI::Frame.frame_style=

Raises ArgumentError if frame_style is not valid

Attributes

  • symbol - the default frame style to use for frames

: (frame_stylable frame_style) -> void



337
338
339
 
# File 'lib/cli/ui.rb', line 337

def frame_style=(frame_style)
  Frame.frame_style = frame_style
end

.glyph(handle) ⇒ Object

Glyph resolution using CLI::UI::Glyph.lookup Look at the method signature for Glyph.lookup for more details

Attributes

  • handle - handle of the glyph to resolve

: (String handle) -> Glyph



39
40
41
 
# File 'lib/cli/ui.rb', line 39

def glyph(handle)
  CLI::UI::Glyph.lookup(handle)
end

.link(url, text, format: true, blue_underline: format) ⇒ Object

Create a terminal link : (String url, String text, ?format: bool, ?blue_underline: bool) -> String



343
344
345
346
347
348
349
 
# File 'lib/cli/ui.rb', line 343

def link(url, text, format: true, blue_underline: format)
  raise 'cannot use blue_underline without format' if blue_underline && !format

  text = "{{blue:{{underline:#{text}}}}}" if blue_underline
  text = CLI::UI.fmt(text) if format
  "\x1b]8;;#{url}\x1b\\#{text}\x1b]8;;\x1b\\"
end

.log_output_to(path, &block) ⇒ Object

Duplicate output to a file path

Attributes

  • path - path to duplicate output to

: [T] (String path) { -> T } -> T



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/cli/ui.rb', line 254

def log_output_to(path, &block)
  if CLI::UI::StdoutRouter.duplicate_output_to
    raise 'multiple logs not allowed'
  end

  CLI::UI::StdoutRouter.duplicate_output_to = File.open(path, 'w')
  yield
ensure
  if (file_descriptor = CLI::UI::StdoutRouter.duplicate_output_to)
    begin
      file_descriptor.close
    rescue IOError
      nil
    end
    CLI::UI::StdoutRouter.duplicate_output_to = nil
  end
end

.puts(msg, frame_color: nil, to: $stdout, encoding: Encoding::UTF_8, format: true, graceful: true, wrap: true) ⇒ Object

Convenience Method for CLI::UI::Printer.puts

Attributes

  • msg - Message to print

  • kwargs - keyword arguments for Printer.puts

: (String msg, ?frame_color: colorable?, ?to: io_like, ?encoding: Encoding, ?format: bool, ?graceful: bool, ?wrap: bool) -> void



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/cli/ui.rb', line 173

def puts(
  msg,
  frame_color: nil,
  to: $stdout,
  encoding: Encoding::UTF_8,
  format: true,
  graceful: true,
  wrap: true
)
  CLI::UI::Printer.puts(
    msg,
    frame_color: frame_color,
    to: to,
    encoding: encoding,
    format: format,
    graceful: graceful,
    wrap: wrap,
  )
end

.raw(&block) ⇒ Object

Disable all framing within a block

Attributes

  • block - block in which to disable frames

: [T] { -> T } -> T



279
280
281
282
283
284
285
 
# File 'lib/cli/ui.rb', line 279

def raw(&block)
  prev = Thread.current[:no_cliui_frame_inset]
  Thread.current[:no_cliui_frame_inset] = true
  yield
ensure
  Thread.current[:no_cliui_frame_inset] = prev
end

.resolve_color(input) ⇒ Object

Color resolution using CLI::UI::Color.lookup Will lookup using Color.lookup unless it’s already a CLI::UI::Color (or nil)

Attributes

  • input - color to resolve

: (colorable input) -> CLI::UI::Color



51
52
53
54
55
56
57
58
 
# File 'lib/cli/ui.rb', line 51

def resolve_color(input)
  case input
  when CLI::UI::Color
    input
  else
    CLI::UI::Color.lookup(input)
  end
end

.resolve_style(input) ⇒ Object

Frame style resolution using CLI::UI::Frame::FrameStyle.lookup. Will lookup using FrameStyle.lookup unless it’s already a CLI::UI::Frame::FrameStyle(or nil)

Attributes

  • input - frame style to resolve

: (frame_stylable input) -> CLI::UI::Frame::FrameStyle



67
68
69
70
71
72
73
74
 
# File 'lib/cli/ui.rb', line 67

def resolve_style(input)
  case input
  when CLI::UI::Frame::FrameStyle
    input
  else
    CLI::UI::Frame::FrameStyle.lookup(input.to_s)
  end
end

.resolve_text(input, truncate_to: nil, enable_color: enable_color?) ) ⇒ Object

Convenience Method to resolve text using CLI::UI::Formatter.format Check CLI::UI::Formatter::SGR_MAP for available formatting options

Attributes

  • input - input to format

  • truncate_to - number of characters to truncate the string to (or nil)

  • enable_color - should color be used? default to true unless output is redirected.

: (String input, ?truncate_to: Integer?, ?enable_color: bool) -> String



134
135
136
137
138
139
 
# File 'lib/cli/ui.rb', line 134

def resolve_text(input, truncate_to: nil, enable_color: enable_color?)
  formatted = CLI::UI::Formatter.new(input).format(enable_color: enable_color)
  return formatted unless truncate_to

  CLI::UI::Truncater.call(formatted, truncate_to)
end

.spinner(title, auto_debrief: true, to: $stdout, &block) ⇒ Object

Convenience Method for CLI::UI::Spinner.spin

Attributes

  • args - arguments for Spinner.open

  • block - block for Spinner.open

: (String title, ?auto_debrief: bool, ?to: io_like) { (Spinner::SpinGroup::Task task) -> void } -> bool



231
232
233
 
# File 'lib/cli/ui.rb', line 231

def (title, auto_debrief: true, to: $stdout, &block)
  CLI::UI::Spinner.spin(title, auto_debrief: auto_debrief, to: to, &block)
end

.with_frame_color(color, &block) ⇒ Object

Convenience Method to override frame color using CLI::UI::Frame.with_frame_color

Attributes

  • color - color to override to

  • block - block for Frame.with_frame_color_override

: [T] (colorable color) { -> T } -> T



243
244
245
 
# File 'lib/cli/ui.rb', line 243

def with_frame_color(color, &block)
  CLI::UI::Frame.with_frame_color_override(color, &block)
end

.wrap(input) ⇒ Object

: (String input) -> String



161
162
163
 
# File 'lib/cli/ui.rb', line 161

def wrap(input)
  CLI::UI::Wrap.new(input).wrap
end