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. 

(HOMEBREW_LIBRARY_PATH/"cmd").freeze
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. 

(HOMEBREW_LIBRARY_PATH/"dev-cmd").freeze
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

{
  "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",
}.freeze
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) ⇒ 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. 



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

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



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

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

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



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'commands.rb', line 218

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]
      return T.must(desc).split(DESCRIPTION_SPLITTING_PATTERN).first if short

      return desc
    end
  end
end

.command_options(command) ⇒ 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:

Returns:



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'commands.rb', line 192

def self.command_options(command)
  return if command == "help"

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

  if (cmd_parser = Homebrew::CLI::Parser.from_cmd_path(path))
    cmd_parser.processed_options.filter_map do |short, long, _, desc, hidden|
      next if hidden

      [long || short, 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

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



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

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



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

def self.external_cmd_path(cmd)
  require "tap"

  which("brew-#{cmd}", PATH.new(ENV.fetch("PATH")).append(Tap.cmd_directories))
end

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



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

def self.external_commands
  require "tap"

  Tap.cmd_directories.flat_map do |path|
    find_commands(path).select(&:executable?)
                       .map { basename_without_extension(_1) }
                       .map { |p| p.to_s.delete_prefix("brew-").strip }
  end.map(&:to_s)
     .sort
end

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

Ruby commands which are run by being required.



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

def self.external_ruby_cmd_path(cmd)
  require "tap"

  which("brew-#{cmd}.rb", PATH.new(ENV.fetch("PATH")).append(Tap.cmd_directories))
end

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

Ruby commands which can be required without being run.



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

def self.external_ruby_v2_cmd_path(cmd)
  require "tap"

  path = which("#{cmd}.rb", Tap.cmd_directories)
  path if require?(path)
end

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



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

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

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



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

def self.find_internal_commands(path)
  find_commands(path).map(&:basename)
                     .map { basename_without_extension(_1) }
                     .uniq
end

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



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

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

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



128
129
130
 
# File 'commands.rb', line 128

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

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



136
137
138
 
# File 'commands.rb', line 136

def self.internal_commands_aliases
  HOMEBREW_INTERNAL_COMMAND_ALIASES.keys
end

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



110
111
112
 
# File 'commands.rb', line 110

def self.internal_commands_paths
  find_commands HOMEBREW_CMD_PATH
end

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



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

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



132
133
134
 
# File 'commands.rb', line 132

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

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



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

def self.internal_developer_commands_paths
  find_commands HOMEBREW_DEV_CMD_PATH
end

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



44
45
46
47
48
49
 
# File 'commands.rb', line 44

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

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



244
245
246
247
248
249
250
251
252
 
# File 'commands.rb', line 244

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

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

  Array(cmd_parser.named_args_type)
end

.official_external_commands_paths(quiet:) ⇒ 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. 



118
119
120
121
122
123
124
125
126
 
# File 'commands.rb', line 118

def self.official_external_commands_paths(quiet:)
  require "tap"

  OFFICIAL_CMD_TAPS.flat_map do |tap_name, cmds|
    tap = Tap.fetch(tap_name)
    tap.install(quiet:) unless tap.installed?
    cmds.map(&method(:external_ruby_v2_cmd_path)).compact
  end
end

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

Returns the conflicts of a given option for command.



255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'commands.rb', line 255

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?

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

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



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

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



177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'commands.rb', line 177

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(aliases: true) - 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 ⇒ 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. 



167
168
169
170
171
172
173
174
175
 
# File 'commands.rb', line 167

def self.rebuild_internal_commands_completion_list
  require "completions"

  cmds = internal_commands + internal_developer_commands + internal_commands_aliases
  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

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

Returns:

  • (Boolean) 


36
37
38
 
# File 'commands.rb', line 36

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

Returns:

  • (Boolean) 


40
41
42
 
# File 'commands.rb', line 40

def self.valid_internal_dev_cmd?(cmd)
  require?(HOMEBREW_DEV_CMD_PATH/cmd)
end