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:



66
67
68
69
70
 
# File 'commands.rb', line 66

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:



209
210
211
 
# File 'commands.rb', line 209

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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'commands.rb', line 287

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:



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'commands.rb', line 252

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:



317
318
319
320
321
322
323
324
325
 
# File 'commands.rb', line 317

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:



132
133
134
135
136
137
138
 
# File 'commands.rb', line 132

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:



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

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:



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

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:



98
99
100
101
102
 
# File 'commands.rb', line 98

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:



90
91
92
93
94
 
# File 'commands.rb', line 90

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! { Homebrew.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:



214
215
216
217
218
 
# File 'commands.rb', line 214

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) 


183
184
185
186
187
188
189
190
191
 
# File 'commands.rb', line 183

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_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:



73
74
75
76
77
78
 
# File 'commands.rb', line 73

def self.internal_cmd_path(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:



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

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:



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

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:



158
159
160
 
# File 'commands.rb', line 158

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:



81
82
83
84
85
86
 
# File 'commands.rb', line 81

def self.internal_dev_cmd_path(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:



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

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:



163
164
165
 
# File 'commands.rb', line 163

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:



58
59
60
61
62
63
 
# File 'commands.rb', line 58

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:



331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'commands.rb', line 331

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:



348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
 
# File 'commands.rb', line 348

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:



121
122
123
124
125
126
127
128
129
 
# File 'commands.rb', line 121

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.



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

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.



221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'commands.rb', line 221

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:



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

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:



141
142
143
144
145
146
147
148
149
 
# File 'commands.rb', line 141

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 #{suggestions.to_sentence(two_words_connector: " or ", last_word_connector: " 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:



153
154
155
 
# File 'commands.rb', line 153

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) 


42
43
44
 
# File 'commands.rb', line 42

def self.valid_internal_cmd?(cmd)
  Homebrew.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) 


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

def self.valid_internal_dev_cmd?(cmd)
  Homebrew.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) 


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

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