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. 



53
54
55
56
57
 
# File 'commands.rb', line 53

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. 



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

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. 



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'commands.rb', line 205

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:



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'commands.rb', line 179

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. 



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

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. 



84
85
86
 
# File 'commands.rb', line 84

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



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

def self.external_commands
  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
 
# File 'commands.rb', line 80

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



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

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



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

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. 



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

def self.find_internal_commands(path)
  find_commands(path).map(&:basename)
                     .map { basename_without_extension(_1) }
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. 



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

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. 



122
123
124
 
# File 'commands.rb', line 122

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. 



130
131
132
 
# File 'commands.rb', line 130

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. 



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

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. 



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

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. 



126
127
128
 
# File 'commands.rb', line 126

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. 



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

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. 



46
47
48
49
50
51
 
# File 'commands.rb', line 46

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. 



231
232
233
234
235
236
237
238
239
 
# File 'commands.rb', line 231

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. 



114
115
116
117
118
119
120
 
# File 'commands.rb', line 114

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



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

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. 



88
89
90
91
92
93
94
95
96
 
# File 'commands.rb', line 88

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. 



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

def self.rebuild_commands_completion_list
  # 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. 



158
159
160
161
162
163
164
 
# File 'commands.rb', line 158

def self.rebuild_internal_commands_completion_list
  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) 


38
39
40
 
# File 'commands.rb', line 38

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) 


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

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