Module: Commands Private

Defined in:
commands.rb

Overview

This module is part of a private API. This module may only be used in the Homebrew/brew repository. Third parties should avoid using this module if possible, as it may be removed or changed without warning.

Helper functions for commands.

Constant Summary collapse

HOMEBREW_CMD_PATH =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((HOMEBREW_LIBRARY_PATH/"cmd").freeze, Pathname)
HOMEBREW_DEV_CMD_PATH =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((HOMEBREW_LIBRARY_PATH/"dev-cmd").freeze, Pathname)
HOMEBREW_INTERNAL_COMMAND_ALIASES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

If you are going to change anything in below hash, be sure to also update appropriate case statement in brew.sh

T.let({
  "ls"           => "list",
  "homepage"     => "home",
  "-S"           => "search",
  "up"           => "update",
  "ln"           => "link",
  "instal"       => "install", # gem does the same
  "uninstal"     => "uninstall",
  "post_install" => "postinstall",
  "rm"           => "uninstall",
  "remove"       => "uninstall",
  "abv"          => "info",
  "dr"           => "doctor",
  "--repo"       => "--repository",
  "environment"  => "--env",
  "--config"     => "config",
  "-v"           => "--version",
  "lc"           => "livecheck",
  "tc"           => "typecheck",
  "x"            => "exec",
}.freeze, T::Hash[String, String])
DESCRIPTION_SPLITTING_PATTERN =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

This pattern is used to split descriptions at full stops. We only consider a dot as a full stop if it is either followed by a whitespace or at the end of the description. In this way we can prevent cutting off a sentence in the middle due to dots in URLs or paths.

/\.(?>\s|$)/

Class Method Summary collapse

Class Method Details

.args_method_name(cmd_path) ⇒ Symbol

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:



76
77
78
79
80
 
# File 'commands.rb', line 76

def self.args_method_name(cmd_path)
  cmd_path_basename = basename_without_extension(cmd_path)
  cmd_method_prefix = method_name(cmd_path_basename)
  :"#{cmd_method_prefix}_args"
end

.basename_without_extension(path) ⇒ 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:



223
224
225
 
# File 'commands.rb', line 223

def self.basename_without_extension(path)
  path.basename(path.extname).to_s
end

.command_description(command, short: false) ⇒ 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:

  • command (String)
  • short (Boolean) (defaults to: false)

Returns:



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'commands.rb', line 301

def self.command_description(command, short: false)
  path = self.path(command)
  return unless path

  if (cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path))
    if short
      cmd_parser.description&.split(DESCRIPTION_SPLITTING_PATTERN)&.first
    else
      cmd_parser.description
    end
  else
    comment_lines = path.read.lines.grep(/^#:/)

    # skip the comment's initial usage summary lines
    comment_lines.slice(2..-1)&.each do |line|
      match_data = /^#:  (?<desc>\w.*+)$/.match(line)
      next unless match_data

      desc = match_data[:desc]
      next if desc.nil?

      return desc.split(DESCRIPTION_SPLITTING_PATTERN).first if short

      return desc
    end
    nil
  end
end

.command_options(command, subcommand: nil) ⇒ Array<Array<(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:

  • command (String)
  • subcommand (String, nil) (defaults to: nil)

Returns:



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'commands.rb', line 266

def self.command_options(command, subcommand: nil)
  return if command == "help"

  path = self.path(command)
  return unless path

  if (cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path))
    processed_options = if subcommand.nil? && cmd_parser.subcommands.present?
      cmd_parser.processed_options_for_root_command
    else
      cmd_parser.processed_options_for_subcommand(subcommand)
    end
    processed_options.filter_map do |short, long, desc, hidden|
      next if hidden

      option = long || short
      next if option.nil?

      [option, desc]
    end
  else
    options = []
    comment_lines = path.read.lines.grep(/^#:/)
    return options if comment_lines.empty?

    # skip the comment's initial usage summary lines
    comment_lines.slice(2..-1)&.each do |line|
      match_data = / (?<option>-[-\w]+) +(?<desc>.*)$/.match(line)
      options << [match_data[:option], match_data[:desc]] if match_data
    end
    options
  end
end

.command_subcommands(command) ⇒ Array<Homebrew::CLI::Parser::Subcommand>

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:



331
332
333
334
335
336
337
338
339
 
# File 'commands.rb', line 331

def self.command_subcommands(command)
  path = self.path(command)
  return [] unless path

  cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
  return [] if cmd_parser.blank?

  cmd_parser.subcommands
end

.commands(external: true, aliases: false) ⇒ Array<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:

  • external (Boolean) (defaults to: true)
  • aliases (Boolean) (defaults to: false)

Returns:



146
147
148
149
150
151
152
 
# File 'commands.rb', line 146

def self.commands(external: true, aliases: false)
  cmds = internal_commands
  cmds += internal_developer_commands
  cmds += external_commands if external
  cmds += internal_commands_aliases if aliases
  cmds.sort
end

.external_cmd_path(cmd) ⇒ Pathname?

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:



119
120
121
122
123
 
# File 'commands.rb', line 119

def self.external_cmd_path(cmd)
  path = which("brew-#{cmd}", PATH.new(ENV.fetch("PATH")).append(tap_cmd_directories))
  require_trusted_command!(path, cmd)
  path
end

.external_commands ⇒ Array<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.

Returns:



208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'commands.rb', line 208

def self.external_commands
  tap_cmd_directories.flat_map do |path|
    commands = find_commands(path).select(&:executable?)
    if path.expand_path.ascend.any?(HOMEBREW_TAP_DIRECTORY)
      require "trust"
      commands = Homebrew::Trust.trusted_command_files(commands)
    end
    commands
      .map { |basename| basename_without_extension(basename) }
      .map { |p| p.to_s.delete_prefix("brew-").strip }
  end.map(&:to_s)
     .sort
end

.external_ruby_cmd_path(cmd) ⇒ Pathname?

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.

Ruby commands which are run by being required.

Parameters:

Returns:



112
113
114
115
116
 
# File 'commands.rb', line 112

def self.external_ruby_cmd_path(cmd)
  path = which("brew-#{cmd}.rb", PATH.new(ENV.fetch("PATH")).append(tap_cmd_directories))
  require_trusted_command!(path, cmd)
  path
end

.external_ruby_v2_cmd_path(cmd) ⇒ Pathname?

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.

Ruby commands which can be required without being run.

Parameters:

Returns:



104
105
106
107
108
 
# File 'commands.rb', line 104

def self.external_ruby_v2_cmd_path(cmd)
  path = which("#{cmd}.rb", tap_cmd_directories)
  require_trusted_command!(path, cmd)
  path if ENV.clear_sensitive_environment! { Utils::Ruby.require?(path) }
end

.find_commands(path) ⇒ Array<Pathname>

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:



228
229
230
231
232
 
# File 'commands.rb', line 228

def self.find_commands(path)
  Pathname.glob("#{path}/*")
          .select(&:file?)
          .sort
end

.find_internal_commands(path) ⇒ Array<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:

Raises:

  • (ArgumentError) 


197
198
199
200
201
202
203
204
205
 
# File 'commands.rb', line 197

def self.find_internal_commands(path)
  raise ArgumentError, "#{path} is not an official command path" \
    unless [HOMEBREW_CMD_PATH, HOMEBREW_DEV_CMD_PATH].include?(path)

  find_commands(path).map(&:basename)
                     .map { |basename| basename_without_extension(basename) }
                     .uniq
                     .reject { |name| Homebrew::CLI::Parser.from_cmd_path(path/"#{name}.rb")&.hide_from_man_page }
end

.internal_cmd_name?(cmd) ⇒ Boolean

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.

Keep in sync with the command name check in brew.sh.

Parameters:

Returns:

  • (Boolean) 


47
48
49
 
# File 'commands.rb', line 47

def self.internal_cmd_name?(cmd)
  cmd.exclude?("/") && %w[. ..].exclude?(cmd)
end

.internal_cmd_path(cmd) ⇒ Pathname?

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:



83
84
85
86
87
88
89
90
 
# File 'commands.rb', line 83

def self.internal_cmd_path(cmd)
  return unless internal_cmd_name?(cmd)

  [
    HOMEBREW_CMD_PATH/"#{cmd}.rb",
    HOMEBREW_CMD_PATH/"#{cmd}.sh",
  ].find(&:exist?)
end

.internal_commands ⇒ Array<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.

Returns:



182
183
184
 
# File 'commands.rb', line 182

def self.internal_commands
  find_internal_commands(HOMEBREW_CMD_PATH).map(&:to_s)
end

.internal_commands_aliases ⇒ Array<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.

Returns:



192
193
194
 
# File 'commands.rb', line 192

def self.internal_commands_aliases
  HOMEBREW_INTERNAL_COMMAND_ALIASES.keys
end

.internal_commands_paths ⇒ Array<Pathname>

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.

Returns:



172
173
174
 
# File 'commands.rb', line 172

def self.internal_commands_paths
  find_commands HOMEBREW_CMD_PATH
end

.internal_dev_cmd_path(cmd) ⇒ Pathname?

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:



93
94
95
96
97
98
99
100
 
# File 'commands.rb', line 93

def self.internal_dev_cmd_path(cmd)
  return unless internal_cmd_name?(cmd)

  [
    HOMEBREW_DEV_CMD_PATH/"#{cmd}.rb",
    HOMEBREW_DEV_CMD_PATH/"#{cmd}.sh",
  ].find(&:exist?)
end

.internal_developer_commands ⇒ Array<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.

Returns:



187
188
189
 
# File 'commands.rb', line 187

def self.internal_developer_commands
  find_internal_commands(HOMEBREW_DEV_CMD_PATH).map(&:to_s)
end

.internal_developer_commands_paths ⇒ Array<Pathname>

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.

Returns:



177
178
179
 
# File 'commands.rb', line 177

def self.internal_developer_commands_paths
  find_commands HOMEBREW_DEV_CMD_PATH
end

.method_name(cmd) ⇒ Symbol

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:



68
69
70
71
72
73
 
# File 'commands.rb', line 68

def self.method_name(cmd)
  cmd.to_s
     .tr("-", "_")
     .downcase
     .to_sym
end

.named_args_type(command, subcommand: nil) ⇒ Array<Symbol>, ...

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:

  • command (String)
  • subcommand (String, nil) (defaults to: nil)

Returns:



345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'commands.rb', line 345

def self.named_args_type(command, subcommand: nil)
  path = self.path(command)
  return unless path

  cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
  return if cmd_parser.blank?

  args_type = if subcommand
    cmd_parser.named_args_type_for_subcommand(subcommand)
  else
    cmd_parser.named_args_type
  end
  Array(args_type)
end

.option_conflicts(command, option) ⇒ Array<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.

Returns the conflicts of a given option for command.

Parameters:

Returns:



362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'commands.rb', line 362

def self.option_conflicts(command, option)
  path = self.path(command)
  return unless path

  cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path)
  return if cmd_parser.blank?

  hidden_options = cmd_parser.processed_options.filter_map do |short, long, _desc, hidden|
    next unless hidden

    option_name = long || short
    next unless option_name

    Homebrew::CLI::Parser.option_to_name(option_name).tr("_", "-")
  end

  cmd_parser.conflicts.map do |set|
    set = set.map { |s| s.tr "_", "-" } - hidden_options
    set - [option] if set.include? option
  end.flatten.compact
end

.path(cmd) ⇒ Pathname?

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:



135
136
137
138
139
140
141
142
143
 
# File 'commands.rb', line 135

def self.path(cmd)
  internal_cmd = HOMEBREW_INTERNAL_COMMAND_ALIASES.fetch(cmd, cmd)
  path ||= internal_cmd_path(internal_cmd)
  path ||= internal_dev_cmd_path(internal_cmd)
  path ||= external_ruby_v2_cmd_path(cmd)
  path ||= external_ruby_cmd_path(cmd)
  path ||= external_cmd_path(cmd)
  path
end

.rebuild_commands_completion_list ⇒ void

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.

This method returns an undefined value.



249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'commands.rb', line 249

def self.rebuild_commands_completion_list
  require "completions"

  # Ensure that the cache exists so we can build the commands list
  HOMEBREW_CACHE.mkpath

  # Don't reject `command_hidden_from_manpage?` commands here: internal ones
  # are already excluded and checking externals loads every tap command file.
  cmds = commands - Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST

  all_commands_file = HOMEBREW_CACHE/"all_commands_list.txt"
  external_commands_file = HOMEBREW_CACHE/"external_commands_list.txt"
  all_commands_file.atomic_write("#{cmds.sort.join("\n")}\n")
  external_commands_file.atomic_write("#{external_commands.sort.join("\n")}\n")
end

.rebuild_internal_commands_completion_list ⇒ void

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.

This method returns an undefined value.



235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'commands.rb', line 235

def self.rebuild_internal_commands_completion_list
  require "completions"

  cmds = internal_commands + internal_developer_commands
  cmds.reject! do |cmd|
    Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include?(cmd) ||
      Homebrew::Completions.command_hidden_from_manpage?(cmd)
  end

  file = HOMEBREW_REPOSITORY/"completions/internal_commands_list.txt"
  file.atomic_write("#{cmds.sort.join("\n")}\n")
end

.require_trusted_command!(path, cmd) ⇒ void

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.

This method returns an undefined value.

Parameters:



126
127
128
129
130
131
132
 
# File 'commands.rb', line 126

def self.require_trusted_command!(path, cmd)
  return unless path
  return if path.expand_path.ascend.none?(HOMEBREW_TAP_DIRECTORY)

  require "trust"
  Homebrew::Trust.require_trusted_command!(path, cmd)
end

.suggestion_message(cmd) ⇒ 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:



155
156
157
158
159
160
161
162
163
 
# File 'commands.rb', line 155

def self.suggestion_message(cmd)
  require "did_you_mean"

  suggestions = DidYouMean::SpellChecker.new(dictionary: commands(external: false, aliases: true)).correct(cmd)
  suggestions = DidYouMean::SpellChecker.new(dictionary: commands(aliases: true)).correct(cmd) if suggestions.empty?
  return "" if suggestions.empty?

  "\nDid you mean #{Utils::Text.to_sentence(suggestions, conjunction: "or")}?"
end

.tap_cmd_directories ⇒ Array<Pathname>

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.

An array of all tap cmd directory Pathnames.

Returns:



167
168
169
 
# File 'commands.rb', line 167

def self.tap_cmd_directories
  Pathname.glob HOMEBREW_TAP_DIRECTORY/"*/*/cmd"
end

.valid_internal_cmd?(cmd) ⇒ Boolean

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:

  • (Boolean) 


52
53
54
 
# File 'commands.rb', line 52

def self.valid_internal_cmd?(cmd)
  internal_cmd_name?(cmd) && Utils::Ruby.require?(HOMEBREW_CMD_PATH/cmd)
end

.valid_internal_dev_cmd?(cmd) ⇒ Boolean

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:

  • (Boolean) 


57
58
59
 
# File 'commands.rb', line 57

def self.valid_internal_dev_cmd?(cmd)
  internal_cmd_name?(cmd) && Utils::Ruby.require?(HOMEBREW_DEV_CMD_PATH/cmd)
end

.valid_ruby_cmd?(cmd) ⇒ Boolean

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:

  • (Boolean) 


62
63
64
65
 
# File 'commands.rb', line 62

def self.valid_ruby_cmd?(cmd)
  (valid_internal_cmd?(cmd) || valid_internal_dev_cmd?(cmd) || external_ruby_v2_cmd_path(cmd).present?) &&
    (Homebrew::AbstractCommand.command(cmd)&.ruby_cmd? == true)
end