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",
  "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|$)/.freeze

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. 



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

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



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

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. 



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

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

        return desc
      end
    end
  end
end

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



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

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

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

      [long || short, desc]
    end.compact
  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. 



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

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. 



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

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. 



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

def self.external_commands
  Tap.cmd_directories.flat_map do |path|
    find_commands(path).select(&:executable?)
                       .map(&method(:basename_without_extension))
                       .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.



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

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.



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

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. 



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

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. 



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

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



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

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. 



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

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. 



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

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. 



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

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. 



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

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. 



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

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. 



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

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. 



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

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. 



229
230
231
232
233
234
235
236
237
 
# File 'commands.rb', line 229

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. 



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

def self.official_external_commands_paths(quiet:)
  OFFICIAL_CMD_TAPS.flat_map do |tap_name, cmds|
    tap = Tap.fetch(tap_name)
    tap.install(quiet: 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.



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

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. 



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

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. 



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

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. 



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

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) 


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

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) 


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

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