Module: Homebrew::Completions Private

Extended by:
T::Sig
Defined in:
brew/Library/Homebrew/completions.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Helper functions for generating shell completions.

Constant Summary collapse

COMPLETIONS_DIR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

(HOMEBREW_REPOSITORY/"completions").freeze
TEMPLATE_DIR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

(HOMEBREW_LIBRARY_PATH/"completions").freeze
SHELLS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

%w[bash fish zsh].freeze
COMPLETIONS_EXCLUSION_LIST =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

%w[
  instal
  uninstal
  update-report
].freeze
BASH_NAMED_ARGS_COMPLETION_FUNCTION_MAPPING =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

{
  formula:           "__brew_complete_formulae",
  installed_formula: "__brew_complete_installed_formulae",
  outdated_formula:  "__brew_complete_outdated_formulae",
  cask:              "__brew_complete_casks",
  installed_cask:    "__brew_complete_installed_casks",
  outdated_cask:     "__brew_complete_outdated_casks",
  tap:               "__brew_complete_tapped",
  installed_tap:     "__brew_complete_tapped",
  command:           "__brew_complete_commands",
  diagnostic_check:  '__brewcomp "$(brew doctor --list-checks)"',
  file:              "__brew_complete_files",
}.freeze

Class Method Summary collapse

Class Method Details

.command_gets_completions?(command) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

Returns:

  • (Boolean)


100
101
102
103
104
# File 'brew/Library/Homebrew/completions.rb', line 100

def command_gets_completions?(command)
  return false if command.start_with? "cask " # TODO: (2.8) remove when `brew cask` commands are removed

  command_options(command).any?
end

.command_options(command) ⇒ Array<String>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

Returns:



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# File 'brew/Library/Homebrew/completions.rb', line 107

def command_options(command)
  options = []
  Commands.command_options(command)&.each do |option|
    next if option.blank?

    name = option.first
    if name.start_with? "--[no-]"
      options << name.remove("[no-]")
      options << name.sub("[no-]", "no-")
    else
      options << name
    end
  end&.compact
  options.sort
end

.completions_to_link?Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean)


65
66
67
68
69
70
71
72
73
74
75
# File 'brew/Library/Homebrew/completions.rb', line 65

def completions_to_link?
  Tap.each do |tap|
    next if tap.official?

    SHELLS.each do |shell|
      return true if (tap.path/"completions/#{shell}").exist?
    end
  end

  false
end

.generate_bash_completion_file(commands) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

Returns:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# File 'brew/Library/Homebrew/completions.rb', line 156

def generate_bash_completion_file(commands)
  variables = OpenStruct.new

  variables[:completion_functions] = commands.map do |command|
    generate_bash_subcommand_completion command
  end.compact

  variables[:function_mappings] = commands.map do |command|
    next unless command_gets_completions? command

    "#{command}) _brew_#{Commands.method_name command} ;;"
  end.compact

  ERB.new((TEMPLATE_DIR/"bash.erb").read, trim_mode: ">").result(variables.instance_eval { binding })
end

.generate_bash_subcommand_completion(command) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

Returns:



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
# File 'brew/Library/Homebrew/completions.rb', line 124

def generate_bash_subcommand_completion(command)
  return unless command_gets_completions? command

  named_completion_string = ""
  if types = Commands.named_args_type(command)
    named_args_strings, named_args_types = types.partition { |type| type.is_a? String }

    named_args_types.each do |type|
      next unless BASH_NAMED_ARGS_COMPLETION_FUNCTION_MAPPING.key? type

      named_completion_string += "\n  #{BASH_NAMED_ARGS_COMPLETION_FUNCTION_MAPPING[type]}"
    end

    named_completion_string += "\n  __brewcomp \"#{named_args_strings.join(" ")}\"" if named_args_strings.any?
  end

  <<~COMPLETION
    _brew_#{Commands.method_name command}() {
      local cur="${COMP_WORDS[COMP_CWORD]}"
      case "$cur" in
        -*)
          __brewcomp "
          #{command_options(command).join("\n      ")}
          "
          return
          ;;
      esac#{named_completion_string}
    }
  COMPLETION
end

.link!void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.



42
43
44
45
46
47
# File 'brew/Library/Homebrew/completions.rb', line 42

def link!
  Settings.write :linkcompletions, true
  Tap.each do |tap|
    Utils::Link.link_completions tap.path, "brew completions link"
  end
end

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean)


60
61
62
# File 'brew/Library/Homebrew/completions.rb', line 60

def link_completions?
  Settings.read(:linkcompletions) == "true"
end

.show_completions_message_if_neededvoid

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.



78
79
80
81
82
83
84
85
86
87
88
89
90
# File 'brew/Library/Homebrew/completions.rb', line 78

def show_completions_message_if_needed
  return if Settings.read(:completionsmessageshown) == "true"
  return unless completions_to_link?

  ohai "Homebrew completions for external commands are unlinked by default!"
  puts <<~EOS
    To opt-in to automatically linking external tap shell competion files, run:
      brew completions link
    Then, follow the directions at #{Formatter.url("https://docs.brew.sh/Shell-Completion")}
  EOS

  Settings.write :completionsmessageshown, true
end

.unlink!void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.



50
51
52
53
54
55
56
57
# File 'brew/Library/Homebrew/completions.rb', line 50

def unlink!
  Settings.write :linkcompletions, false
  Tap.each do |tap|
    next if tap.official?

    Utils::Link.unlink_completions tap.path
  end
end

.update_shell_completions!void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.



93
94
95
96
97
# File 'brew/Library/Homebrew/completions.rb', line 93

def update_shell_completions!
  commands = Commands.commands(external: false, aliases: true).sort

  (COMPLETIONS_DIR/"bash/brew").atomic_write generate_bash_completion_file(commands)
end