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:



198
199
200
 
# File 'commands.rb', line 198

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:



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 271

def self.command_description(command, short: false)
  path = self.path(command)
  return if path.blank?

  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:



236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'commands.rb', line 236

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

  path = self.path(command)
  return if path.blank?

  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:



301
302
303
304
305
306
307
308
309
 
# File 'commands.rb', line 301

def self.command_subcommands(command)
  path = self.path(command)
  return [] if path.blank?

  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:



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

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:



203
204
205
206
207
 
# File 'commands.rb', line 203

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) 


172
173
174
175
176
177
178
179
180
 
# File 'commands.rb', line 172

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:



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

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:



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

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:



147
148
149
 
# File 'commands.rb', line 147

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:



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

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:



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

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:



315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'commands.rb', line 315

def self.named_args_type(command, subcommand: nil)
  path = self.path(command)
  return if path.blank?

  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:



332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'commands.rb', line 332

def self.option_conflicts(command, option)
  path = self.path(command)
  return if path.blank?

  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.



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

def self.rebuild_commands_completion_list
  require "completions"

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

  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.



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

def self.rebuild_internal_commands_completion_list
  require "completions"

  cmds = internal_commands + internal_developer_commands
  cmds.reject! { |cmd| Homebrew::Completions::COMPLETIONS_EXCLUSION_LIST.include? cmd }

  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

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



142
143
144
 
# File 'commands.rb', line 142

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