Module: Formatter
- Defined in:
- utils/formatter.rb
Overview
This module is part of an internal API. This module may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this module if possible, as it may be removed or changed without warning.
Helper module for formatting output.
Constant Summary collapse
- COMMAND_DESC_WIDTH =
This constant is part of an internal API. This constant may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
80
- OPTION_DESC_WIDTH =
This constant is part of an internal API. This constant may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.
45
Class Method Summary collapse
- .arrow(string, color: nil) ⇒ Object internal
- .bold(string) ⇒ Object internal
-
.columns(*objects, gap_size: 2) ⇒ Object
internal
Layout objects in columns that fit the current terminal width.
-
.error(string, label: nil) ⇒ Object
internal
Format a string as error, with an optional label.
-
.format_help_text(string, width: 172) ⇒ Object
private
Wraps text to fit within a given number of columns using regular expressions that:.
-
.headline(string, color: nil) ⇒ Object
internal
Format a string as headline.
- .identifier(string) ⇒ Object internal
- .option(string) ⇒ Object internal
-
.success(string, label: nil) ⇒ Object
internal
Format a string as success, with an optional label.
-
.truncate(string, max: 30, omission: "...") ⇒ String
internal
Truncate a string to a specific length.
- .url(string) ⇒ Object internal
-
.warning(string, label: nil) ⇒ Object
internal
Format a string as warning, with an optional label.
Class Method Details
.arrow(string, color: nil) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
13 14 15 |
# File 'utils/formatter.rb', line 13 def self.arrow(string, color: nil) prefix("==>", string, color) end |
.bold(string) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
28 29 30 |
# File 'utils/formatter.rb', line 28 def self.bold(string) "#{Tty.bold}#{string}#{Tty.reset}" end |
.columns(*objects, gap_size: 2) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Layout objects in columns that fit the current terminal width.
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 |
# File 'utils/formatter.rb', line 119 def self.columns(*objects, gap_size: 2) objects = objects.flatten.map(&:to_s) fallback = proc do return objects.join("\n").concat("\n") end fallback.call if objects.empty? fallback.call if respond_to?(:tty?) ? !T.unsafe(self).tty? : !$stdout.tty? console_width = Tty.width object_lengths = objects.map { |obj| Tty.strip_ansi(obj).length } cols = (console_width + gap_size) / (T.must(object_lengths.max) + gap_size) fallback.call if cols < 2 rows = (objects.count + cols - 1) / cols cols = (objects.count + rows - 1) / rows # avoid empty trailing columns col_width = ((console_width + gap_size) / cols) - gap_size gap_string = "".rjust(gap_size) output = +"" rows.times do |row_index| item_indices_for_row = T.cast(row_index.step(objects.size - 1, rows).to_a, T::Array[Integer]) first_n = T.must(item_indices_for_row[0...-1]).map do |index| objects[index] + "".rjust(col_width - object_lengths.fetch(index)) end # don't add trailing whitespace to last column last = objects.values_at(item_indices_for_row.fetch(-1)) output.concat((first_n + last) .join(gap_string)) .concat("\n") end output.freeze end |
.error(string, label: nil) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Format a string as error, with an optional label.
53 54 55 |
# File 'utils/formatter.rb', line 53 def self.error(string, label: nil) label(label, string, :red) end |
.format_help_text(string, width: 172) ⇒ Object
This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Wraps text to fit within a given number of columns using regular expressions that:
- convert hard-wrapped paragraphs to a single line
- add line break and indent to subcommand descriptions
- find any option descriptions longer than a pre-set length and wrap between words with a hanging indent, without breaking any words that overflow
- wrap any remaining description lines that need wrapping with the same indent
- wrap all lines to the given width.
Note that an option (e.g. --foo
) may not be at the beginning of a line,
so we always wrap one word before an option.
83 84 85 86 87 88 89 90 91 |
# File 'utils/formatter.rb', line 83 def self.format_help_text(string, width: 172) desc = OPTION_DESC_WIDTH indent = width - desc string.gsub(/(?<=\S) *\n(?=\S)/, " ") .gsub(/([`>)\]]:) /, "\\1\n ") .gsub(/^( +-.+ +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)(?!-)\n?/, "\\1\\2\n#{" " * indent}") .gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)(?!-)\n?/, "\\1\\2\n#{" " * indent}") .gsub(/(.{1,#{width}})( +|$)(?!-)\n?/, "\\1\n") end |
.headline(string, color: nil) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Format a string as headline.
20 21 22 |
# File 'utils/formatter.rb', line 20 def self.headline(string, color: nil) arrow("#{Tty.bold}#{string}#{Tty.reset}", color:) end |
.identifier(string) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
24 25 26 |
# File 'utils/formatter.rb', line 24 def self.identifier(string) "#{Tty.green}#{string}#{Tty.default}" end |
.option(string) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
32 33 34 |
# File 'utils/formatter.rb', line 32 def self.option(string) bold(string) end |
.success(string, label: nil) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Format a string as success, with an optional label.
39 40 41 |
# File 'utils/formatter.rb', line 39 def self.success(string, label: nil) label(label, string, :green) end |
.truncate(string, max: 30, omission: "...") ⇒ String
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Truncate a string to a specific length.
61 62 63 64 65 66 67 68 |
# File 'utils/formatter.rb', line 61 def self.truncate(string, max: 30, omission: "...") return string if string.length <= max length_with_room_for_omission = max - omission.length truncated = string[0, length_with_room_for_omission] "#{truncated}#{omission}" end |
.url(string) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
93 94 95 |
# File 'utils/formatter.rb', line 93 def self.url(string) "#{Tty.underline}#{string}#{Tty.no_underline}" end |
.warning(string, label: nil) ⇒ Object
This method is part of an internal API. This method may only be used internally in repositories owned by Homebrew, except in casks or formulae. Third parties should avoid using this method if possible, as it may be removed or changed without warning.
Format a string as warning, with an optional label.
46 47 48 |
# File 'utils/formatter.rb', line 46 def self.warning(string, label: nil) label(label, string, :yellow) end |