Module: GitlabInternalEventsCli::Helpers::Formatting

Included in:
GitlabInternalEventsCli::Helpers, MetricOptions::Option, Text::EventDefiner, Text::FlowAdvisor, Text::MetricDefiner
Defined in:
lib/gitlab_internal_events_cli/helpers/formatting.rb

Constant Summary collapse

DEFAULT_WINDOW_WIDTH = 
100
DEFAULT_WINDOW_HEIGHT = 
30

Instance Method Summary collapse

Instance Method Details

#clear_format(string) ⇒ Object

Strips all existing color/text style



68
69
70
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 68

def clear_format(string)
  pastel.strip(string)
end

#counter(idx, total) ⇒ String?

Formats a counter if there’s anything to count

Returns:

  • (String, nil) —

    ex) “(3/4)”“



135
136
137
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 135

def counter(idx, total)
  "(#{idx + 1}/#{total})" if total > 1
end

#divider ⇒ Object

When to use a divider:

  • As separation between whole flows or format the layout of a screen or the layout of CLI outputs.

  • Dividers should not be used to differentiate between prompts on the same screen.



106
107
108
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 106

def divider
  '-' * window_size
end

#format_error(string) ⇒ Object

When to format as “error”:

  • When the CLI encounters unexpected problems that may require broader changes by the Analytics Instrumentation Group or out of band configuration.

  • To highlight special characters used to symbolize that there was an error or that an option is not available.



63
64
65
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 63

def format_error(string)
  pastel.red(string)
end

#format_heading(string) ⇒ Object

When to format as “heading”:

  • At the beginning or end of complete flows, to create visual separation and indicate logical breakpoints.



75
76
77
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 75

def format_heading(string)
  [divider, pastel.cyan(string), divider].join("\n")
end

#format_help(string) ⇒ Object

When to format as “help”:

  • To format supplemental information on how to interact with prompts. This should always be in parenthesis.

  • To indicate disabled or unavailable menu options.

  • To indicate meta-information in menu options or informational text.



43
44
45
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 43

def format_help(string)
  pastel.bright_black(string)
end

#format_info(string) ⇒ Object

When to format as “info”:

  • When a header is needed to organize contextual information. These headers should always be all caps.

  • As a supplemental way to highlight the most important text within a menu or informational text.

  • Optionally, for URLs



16
17
18
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 16

def format_info(string)
  pastel.cyan(string)
end

#format_prefix(prefix, string) ⇒ Object 



97
98
99
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 97

def format_prefix(prefix, string)
  string.lines.map { |line| line.prepend(prefix) }.join
end

#format_prompt(string) ⇒ Object

When to format as “prompt”:

  • When we need the user to input information. The text should describe the action the user should take to move forward, like ‘Input text` or `Select one`

  • As header text on multi-screen steps in a flow. Always include a counter when this is the case.



53
54
55
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 53

def format_prompt(string)
  pastel.magenta(string)
end

#format_selection(string) ⇒ Object

When to format as “selection”:

  • As a supplemental way of indicating something was selected or the current state of an interaction.



33
34
35
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 33

def format_selection(string)
  pastel.green(string)
end

#format_subheader(subject, item, count = 1, total = 1) ⇒ String

Used for grouping prompts that occur on the same screen or as part of the same step of a flow.

Counter is exluded if total is 1. The subject’s formatting is extended to the counter.

Parameters:

  • subject (String) —

    describes task generically ex) EATING COOKIES

  • item (String) —

    describes specific context ex) Chocolate Chip

  • count (Integer) (defaults to: 1) —

    ex) 2

  • total (Integer) (defaults to: 1) —

    ex) 3

Returns:

  • (String) —

    ex) – EATING COOKIES (2/3): Chocolate Chip –



90
91
92
93
94
95
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 90

def format_subheader(subject, item, count = 1, total = 1)
  formatting_end = "\e[0m"
  suffix = formatting_end if subject[-formatting_end.length..] == formatting_end

  "-- #{[subject.chomp(formatting_end), counter(count, total)].compact.join(' ')}:#{suffix} #{item} --"
end

#format_warning(string) ⇒ Object

When to format as “warning”:

  • To highlight the first sentence/phrase describing a problem the user needs to address. Any further text explantion should be left unformatted.

  • To highlight an explanation of why the user cannot take a particular action.



26
27
28
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 26

def format_warning(string)
  pastel.yellow(string)
end

#progress_bar(current_title, titles = []) ⇒ Object

Prints a progress bar on the screen at the current location

Parameters:

  • current_title (String) —

    title to highlight

  • titles (Array<String>) (defaults to: []) —

    progression to follow; -> first element is expected to be a title for the entire flow

Raises:

  • (ArgumentError) 


114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/gitlab_internal_events_cli/helpers/formatting.rb', line 114

def progress_bar(current_title, titles = [])
  step = titles.index(current_title)
  total = titles.length - 1

  raise ArgumentError, "Invalid selection #{current_title} in progress bar" unless step

  status = " Step #{step} / #{total} : #{titles.join(' > ')}"
  status.gsub!(current_title, format_selection(current_title))

  total_length = window_size - 4
  step_length = step / total.to_f * total_length

  incomplete = '-' * [(total_length - step_length - 1), 0].max
  complete = '=' * [(step_length - 1), 0].max

  "#{status}\n|==#{complete}>#{incomplete}|\n"
end