Module: Cask::Utils Private

Extended by:
Utils::Output::Mixin
Defined in:
cask/utils.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 various cask operations.

Constant Summary collapse

BUG_REPORTS_URL =

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. 

"https://github.com/Homebrew/homebrew-cask#reporting-bugs"

Class Method Summary collapse

Methods included from Utils::Output::Mixin

odebug, odeprecated, odie, odisabled, ofail, oh1, oh1_title, ohai, ohai_title, onoe, opoo, opoo_outside_github_actions, pretty_duration, pretty_installed, pretty_outdated, pretty_uninstalled

Class Method Details

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



136
137
138
139
140
141
 
# File 'cask/utils.rb', line 136

def self.error_message_with_suggestions
  <<~EOS
    Follow the instructions here:
      #{Formatter.url(BUG_REPORTS_URL)}
  EOS
end

.gain_permissions(path, command_args, command, &_block) ⇒ 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:



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'cask/utils.rb', line 75

def self.gain_permissions(path, command_args, command, &_block)
  tried_permissions = false
  tried_ownership = false
  begin
    yield path
  rescue
    # in case of permissions problems
    unless tried_permissions
      print_stderr = Context.current.debug? || Context.current.verbose?
      # TODO: Better handling for the case where path is a symlink.
      #       The `-h` and `-R` flags cannot be combined and behavior is
      #       dependent on whether the file argument has a trailing
      #       slash. This should do the right thing, but is fragile.
      command.run("/usr/bin/chflags",
                  print_stderr:,
                  args:         command_args + ["--", "000", path])
      command.run("chmod",
                  print_stderr:,
                  args:         command_args + ["--", "u+rwx", path])
      command.run("chmod",
                  print_stderr:,
                  args:         command_args + ["-N", path])
      tried_permissions = true
      retry # rmtree
    end

    unless tried_ownership
      # in case of ownership problems
      # TODO: Further examine files to see if ownership is the problem
      #       before using `sudo` and `chown`.
      ohai "Using sudo to gain ownership of path '#{path}'"
      command.run("chown",
                  args: command_args + ["--", User.current, path],
                  sudo: true)
      tried_ownership = true
      # retry chflags/chmod after chown
      tried_permissions = false
      retry # rmtree
    end

    raise
  end
end

.gain_permissions_mkpath(path, command: SystemCommand) ⇒ 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:



16
17
18
19
20
21
22
23
24
25
 
# File 'cask/utils.rb', line 16

def self.gain_permissions_mkpath(path, command: SystemCommand)
  dir = path.ascend.find(&:directory?)
  return if path == dir

  if dir&.writable?
    path.mkpath
  else
    command.run!("mkdir", args: ["-p", "--", path], sudo: true, print_stderr: false)
  end
end

.gain_permissions_remove(path, command: SystemCommand) ⇒ 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:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'cask/utils.rb', line 39

def self.gain_permissions_remove(path, command: SystemCommand)
  directory = false
  permission_flags = if path.symlink?
    ["-h"]
  elsif path.directory?
    directory = true
    ["-R"]
  elsif path.exist?
    []
  else
    # Nothing to remove.
    return
  end

  gain_permissions(path, permission_flags, command) do |p|
    if p.parent.writable?
      if directory
        FileUtils.rm_r p
      else
        FileUtils.rm_f p
      end
    else
      recursive_flag = directory ? ["-R"] : []
      command.run!("/bin/rm", args: recursive_flag + ["-f", "--", p], sudo: true, print_stderr: false)
    end
  end
end

.gain_permissions_rmdir(path, command: SystemCommand) ⇒ 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:



28
29
30
31
32
33
34
35
36
 
# File 'cask/utils.rb', line 28

def self.gain_permissions_rmdir(path, command: SystemCommand)
  gain_permissions(path, [], command) do |p|
    if p.parent.writable?
      FileUtils.rmdir p
    else
      command.run!("rmdir", args: ["--", p], sudo: true, print_stderr: false)
    end
  end
end

.method_missing_message(method, token, section = nil) ⇒ 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:



144
145
146
147
148
149
150
 
# File 'cask/utils.rb', line 144

def self.method_missing_message(method, token, section = nil)
  message = "Unexpected method '#{method}' called "
  message << "during #{section} " if section
  message << "on Cask #{token}."

  ofail "#{message}\n#{error_message_with_suggestions}"
end

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


120
121
122
 
# File 'cask/utils.rb', line 120

def self.path_occupied?(path)
  path.exist? || path.symlink?
end

.token_from(name) ⇒ 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:



125
126
127
128
129
130
131
132
133
 
# File 'cask/utils.rb', line 125

def self.token_from(name)
  name.downcase
      .gsub("+", "-plus-")
      .gsub(/[ _·•]/, "-")
      .gsub(/[^\w@-]/, "")
      .gsub(/--+/, "-")
      .delete_prefix("-")
      .delete_suffix("-")
end