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

Class Method Details

.arrow(string, color: nil) ⇒ String

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.

Parameters:

Returns:



14
15
16
 
# File 'utils/formatter.rb', line 14

def self.arrow(string, color: nil)
  prefix("==>", string, color)
end

.bold(string) ⇒ String

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.

Parameters:

Returns:



32
33
34
 
# File 'utils/formatter.rb', line 32

def self.bold(string)
  "#{Tty.bold}#{string}#{Tty.reset}"
end

.columns(objects, gap_size: 2) ⇒ 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.

Layout objects in columns that fit the current terminal width.

Parameters:

  • objects (Array<String>)
  • gap_size (Integer) (defaults to: 2)

Returns:



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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'utils/formatter.rb', line 134

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.fetch(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) ⇒ 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.

Format a string as error, with an optional label.

Parameters:

  • string (String, Exception)
  • label (String, nil) (defaults to: nil)

Returns:



61
62
63
 
# File 'utils/formatter.rb', line 61

def self.error(string, label: nil)
  label(label, string, :red)
end

.format_help_text(string, width: 172) ⇒ String

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:

  1. convert hard-wrapped paragraphs to a single line
  2. add line break and indent to subcommand descriptions
  3. find any option descriptions longer than a pre-set length and wrap between words with a hanging indent, without breaking any words that overflow
  4. wrap any remaining description lines that need wrapping with the same indent
  5. 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.

Parameters:

  • string (String)
  • width (Integer) (defaults to: 172)

Returns:

See Also:



92
93
94
95
96
97
98
99
100
 
# File 'utils/formatter.rb', line 92

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) ⇒ 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.

Format a string as headline.

Parameters:

Returns:



22
23
24
 
# File 'utils/formatter.rb', line 22

def self.headline(string, color: nil)
  arrow("#{Tty.bold}#{string}#{Tty.reset}", color:)
end

.identifier(string) ⇒ String

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.

Parameters:

Returns:



27
28
29
 
# File 'utils/formatter.rb', line 27

def self.identifier(string)
  "#{Tty.green}#{string}#{Tty.default}"
end

.option(string) ⇒ String

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.

Parameters:

Returns:



37
38
39
 
# File 'utils/formatter.rb', line 37

def self.option(string)
  bold(string)
end

.success(string, label: nil) ⇒ 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.

Format a string as success, with an optional label.

Parameters:

Returns:



45
46
47
 
# File 'utils/formatter.rb', line 45

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.

Parameters:

  • string (String)
  • max (Integer) (defaults to: 30)
  • omission (String) (defaults to: "...")

Returns:



69
70
71
72
73
74
75
76
 
# File 'utils/formatter.rb', line 69

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) ⇒ String

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.

Parameters:

  • string (nil, String, URI::Generic)

Returns:



103
104
105
 
# File 'utils/formatter.rb', line 103

def self.url(string)
  "#{Tty.underline}#{string}#{Tty.no_underline}"
end

.warning(string, label: nil) ⇒ 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.

Format a string as warning, with an optional label.

Parameters:

  • string (String, Exception)
  • label (String, nil) (defaults to: nil)

Returns:



53
54
55
 
# File 'utils/formatter.rb', line 53

def self.warning(string, label: nil)
  label(label, string, :yellow)
end