Class: Pathname Private

Inherits:
Object show all
Includes:
DiskUsageExtension, SystemCommand::Mixin, Utils::Output::Mixin
Defined in:
extend/pathname.rb

Overview

This class is part of a private API. This class may only be used in the Homebrew/brew repository. Third parties should avoid using this class if possible, as it may be removed or changed without warning.

TODO:

move all of these to other modules e.g. Utils.

Homebrew extends Ruby's Pathname to make our code more readable.

See Also:

Class Method Summary collapse

Instance 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_deprecated, #pretty_disabled, #pretty_duration, #pretty_installed, #pretty_outdated, #pretty_uninstalled

Methods included from DiskUsageExtension

#abv, #disk_usage, #file_count

Methods included from SystemCommand::Mixin

#system_command, #system_command!

Class Method Details

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



34
35
36
 
# File 'extend/pathname.rb', line 34

def self.activate_extensions!
  Pathname.prepend(WriteMkpathExtension)
end

Instance Method Details

#append_lines(content, **open_args) ⇒ void

This method returns an undefined value.

Only appends to a file that is already created.

Parameters:

  • content (String)
  • open_args (T.untyped) 


97
98
99
100
101
 
# File 'extend/pathname.rb', line 97

def append_lines(content, **open_args)
  raise "Cannot append file that doesn't exist: #{self}" unless exist?

  T.unsafe(self).open("a", **open_args) { |f| f.puts(content) }
end

#arch_compatible?(_wanted_arch) ⇒ 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) 


425
426
427
 
# File 'extend/pathname.rb', line 425

def arch_compatible?(_wanted_arch)
  true
end

#atomic_write(content) ⇒ void

Note:

This always overwrites.

This method returns an undefined value.

Write to a file atomically.

Parameters:



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'extend/pathname.rb', line 109

def atomic_write(content)
  require "extend/file/atomic"

  old_stat = stat if exist?
  File.atomic_write(self) do |file|
    file.write(content)
  end

  return unless old_stat

  # Try to restore original file's permissions separately
  # atomic_write does it itself, but it actually erases
  # them if chown fails
  begin
    # Set correct permissions on new file
    chown(old_stat.uid, nil)
    chown(nil, old_stat.gid)
  rescue Errno::EPERM, Errno::EACCES
    # Changing file ownership failed, moving on.
    nil
  end

  begin
    # This operation will affect filesystem ACL's
    chmod(old_stat.mode)
  rescue Errno::EPERM, Errno::EACCES
    # Changing file permissions failed, moving on.
    nil
  end
end

#binary_executable? ⇒ 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) 


410
411
412
 
# File 'extend/pathname.rb', line 410

def binary_executable?
  false
end

#cd(&_block) ⇒ T.type_parameter(:U)

Change to this directory, optionally executing the given block.

Parameters:

  • _block (T.proc.params(path: Pathname).returns(T.type_parameter(:U)))

Returns:

  • (T.type_parameter(:U)) 


242
243
244
 
# File 'extend/pathname.rb', line 242

def cd(&_block)
  Dir.chdir(self) { yield self }
end

#cp_path_sub(pattern, replacement, &_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:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'extend/pathname.rb', line 144

def cp_path_sub(pattern, replacement, &_block)
  raise "#{self} does not exist" unless exist?

  pattern = pattern.to_s if pattern.is_a?(Pathname)
  replacement = replacement.to_s if replacement.is_a?(Pathname)
  dst = sub(pattern, replacement)

  raise "#{self} is the same file as #{dst}" if self == dst

  if directory?
    dst.mkpath
  else
    dst.dirname.mkpath
    dst = yield(self, dst) if block_given?
    FileUtils.cp(self, dst)
  end
end

#ds_store? ⇒ 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) 


405
406
407
 
# File 'extend/pathname.rb', line 405

def ds_store?
  basename.to_s == ".DS_Store"
end

#dylib? ⇒ 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) 


420
421
422
 
# File 'extend/pathname.rb', line 420

def dylib?
  false
end

#ensure_writable(&_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:

  • _block (T.proc.void) 


276
277
278
279
280
281
282
283
284
285
 
# File 'extend/pathname.rb', line 276

def ensure_writable(&_block)
  saved_perms = nil
  unless writable?
    saved_perms = stat.mode
    FileUtils.chmod "u+rw", to_path
  end
  yield
ensure
  chmod saved_perms if saved_perms
end

#env_script_all_files(dst, env) ⇒ void

This method returns an undefined value.

Writes a wrapper env script and moves all files to the dst.

Parameters:



351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'extend/pathname.rb', line 351

def env_script_all_files(dst, env)
  dst.mkpath
  Pathname.glob("#{self}/*") do |file|
    next if file.directory?

    new_file = dst.join(file.basename)
    raise Errno::EEXIST, new_file.to_s if new_file.exist?

    dst.install(file)
    file.write_env_script(new_file, env)
  end
end

#extname ⇒ String

Extended to support common double extensions.

Returns:



166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'extend/pathname.rb', line 166

def extname
  basename = File.basename(self)

  bottle_ext, = HOMEBREW_BOTTLES_EXTNAME_REGEX.match(basename).to_a
  return bottle_ext if bottle_ext

  archive_ext = basename[/(\.(tar|cpio|pax)\.(gz|bz2|lz|xz|zst|Z))\Z/, 1]
  return archive_ext if archive_ext

  # Don't treat version numbers as extname.
  return "" if basename.match?(/\b\d+\.\d+[^.]*\Z/) && !basename.end_with?(".7z")

  File.extname(basename)
end

#file_type ⇒ 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:



447
448
449
450
451
 
# File 'extend/pathname.rb', line 447

def file_type
  @file_type ||= T.let(nil, T.nilable(String))
  @file_type ||= system_command("file", args: ["-b", self], print_stderr: false)
                 .stdout.chomp
end

#install(*sources) ⇒ void

This method returns an undefined value.

Moves a file from the original location to the Pathname's.

Parameters:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'extend/pathname.rb', line 47

def install(*sources)
  sources.each do |src|
    case src
    when Resource
      src.stage(self)
    when Resource::Partial
      src.resource.stage { install(*src.files) }
    when Array
      if src.empty?
        opoo "Tried to install empty array to #{self}"
        break
      end
      src.each { |s| install_p(s, File.basename(s)) }
    when Hash
      if src.empty?
        opoo "Tried to install empty hash to #{self}"
        break
      end
      src.each { |s, new_basename| install_p(s, new_basename) }
    else
      install_p(src, File.basename(src))
    end
  end
end

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



288
289
290
 
# File 'extend/pathname.rb', line 288

def install_info
  quiet_system(which_install_info, "--quiet", to_s, "#{dirname}/dir")
end

#install_metafiles(from = Pathname.pwd) ⇒ 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:



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
 
# File 'extend/pathname.rb', line 385

def install_metafiles(from = Pathname.pwd)
  require "metafiles"

  Pathname(from).children.each do |p|
    next if p.directory?
    next if File.empty?(p)
    next unless Metafiles.copy?(p.basename.to_s)

    # Some software symlinks these files (see help2man.rb)
    filename = p.resolved_path
    # Some software links metafiles together, so by the time we iterate to one of them
    # we may have already moved it. libxml2's COPYING and Copyright are affected by this.
    next unless filename.exist?

    filename.chmod 0644
    install(filename)
  end
end

#install_symlink(*sources) ⇒ void

This method returns an undefined value.

Creates symlinks to sources in this folder.

Parameters:



80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'extend/pathname.rb', line 80

def install_symlink(*sources)
  sources.each do |src|
    case src
    when Array
      src.each { |s| install_symlink_p(s, File.basename(s)) }
    when Hash
      src.each { |s, new_basename| install_symlink_p(s, new_basename) }
    else
      install_symlink_p(src, File.basename(src))
    end
  end
end

#mach_o_bundle? ⇒ 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) 


415
416
417
 
# File 'extend/pathname.rb', line 415

def mach_o_bundle?
  false
end

#magic_number ⇒ 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:



435
436
437
438
439
440
441
442
443
444
 
# File 'extend/pathname.rb', line 435

def magic_number
  @magic_number ||= T.let(nil, T.nilable(String))
  @magic_number ||= if directory?
    ""
  else
    # Length of the longest regex (currently Tar).
    max_magic_number_length = 262
    binread(max_magic_number_length) || ""
  end
end

#make_relative_symlink(src) ⇒ 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:



270
271
272
273
 
# File 'extend/pathname.rb', line 270

def make_relative_symlink(src)
  dirname.mkpath
  File.symlink(src.relative_path_from(dirname), self)
end

#resolved_path ⇒ Pathname

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:



255
256
257
 
# File 'extend/pathname.rb', line 255

def resolved_path
  symlink? ? dirname.join(readlink) : self
end

#resolved_path_exists? ⇒ 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) 


260
261
262
263
264
265
266
267
 
# File 'extend/pathname.rb', line 260

def resolved_path_exists?
  link = readlink
rescue ArgumentError
  # The link target contains NUL bytes
  false
else
  dirname.join(link).exist?
end

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

I don't trust the children.length == 0 check particularly, not to mention it is slow to enumerate the whole directory just to see if it is empty, instead rely on good ol' libc and the filesystem

Returns:

  • (Boolean) 


193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'extend/pathname.rb', line 193

def rmdir_if_possible
  rmdir
  true
rescue Errno::ENOTEMPTY
  if (ds_store = join(".DS_Store")).exist? && children.length == 1
    ds_store.unlink
    retry
  else
    false
  end
rescue Errno::EACCES, Errno::ENOENT, Errno::EBUSY, Errno::EPERM
  false
end

#rpaths ⇒ Array<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:



430
431
432
 
# File 'extend/pathname.rb', line 430

def rpaths
  []
end

#sha256 ⇒ 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:



219
220
221
222
 
# File 'extend/pathname.rb', line 219

def sha256
  require "digest/sha2"
  Digest::SHA256.file(self).hexdigest
end

#stem ⇒ String

For filetypes we support, returns basename without extension.

Returns:



185
186
187
 
# File 'extend/pathname.rb', line 185

def stem
  File.basename(self, extname)
end

#subdirs ⇒ Array<Pathname>

Get all sub-directories of this directory.

Returns:



250
251
252
 
# File 'extend/pathname.rb', line 250

def subdirs
  children.select(&:directory?)
end

#text_executable? ⇒ 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) 


214
215
216
 
# File 'extend/pathname.rb', line 214

def text_executable?
  /\A#!\s*\S+/.match?(open("r") { |f| f.read(1024) })
end

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



293
294
295
 
# File 'extend/pathname.rb', line 293

def uninstall_info
  quiet_system(which_install_info, "--delete", "--quiet", to_s, "#{dirname}/dir")
end

#verify_checksum(expected) ⇒ 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:

Raises:



225
226
227
228
229
230
 
# File 'extend/pathname.rb', line 225

def verify_checksum(expected)
  raise ChecksumMissingError if expected.blank?

  actual = Checksum.new(sha256.downcase)
  raise ChecksumMismatchError.new(self, expected, actual) if expected != actual
end

#version ⇒ Version

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:



208
209
210
211
 
# File 'extend/pathname.rb', line 208

def version
  require "version"
  Version.parse(basename)
end

#write_env_script(target, args_or_env, env = T.unsafe(nil)) ⇒ void

This method returns an undefined value.

Writes an exec script that sets environment variables.

Parameters:



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'extend/pathname.rb', line 325

def write_env_script(target, args_or_env, env = T.unsafe(nil))
  args = if env.nil?
    env = args_or_env if args_or_env.is_a?(Hash)

    nil
  elsif args_or_env.is_a?(Array)
    args_or_env.join(" ")
  else
    T.cast(args_or_env, T.nilable(String))
  end

  env_export = +""
  env.each { |key, value| env_export << "#{key}=\"#{value}\" " }

  dirname.mkpath

  write <<~SH
    #!/bin/bash
    #{env_export}exec "#{target}" #{args} "$@"
  SH
end

#write_exec_script(*targets) ⇒ void

This method returns an undefined value.

Writes an exec script in this folder for each target pathname.

Parameters:



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'extend/pathname.rb', line 301

def write_exec_script(*targets)
  targets.flatten!
  if targets.empty?
    opoo "Tried to write exec scripts to #{self} for an empty list of targets"
    return
  end
  mkpath
  targets.each do |target|
    target = Pathname.new(target) # allow pathnames or strings
    join(target.basename).write <<~SH
      #!/bin/bash
      exec "#{target}" "$@"
    SH
  end
end

#write_jar_script(target_jar, script_name, java_opts = "", java_version: nil) ⇒ Integer

Writes an exec script that invokes a Java jar.

Parameters:

Returns:



375
376
377
378
379
380
381
382
 
# File 'extend/pathname.rb', line 375

def write_jar_script(target_jar, script_name, java_opts = "", java_version: nil)
  mkpath
  (self/script_name).write <<~EOS
    #!/bin/bash
    export JAVA_HOME="#{Language::Java.overridable_java_home_env(java_version)[:JAVA_HOME]}"
    exec "${JAVA_HOME}/bin/java" #{java_opts} -jar "#{target_jar}" "$@"
  EOS
end

#zipinfo ⇒ Array<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:



454
455
456
457
458
459
460
461
462
 
# File 'extend/pathname.rb', line 454

def zipinfo
  @zipinfo ||= T.let(
    system_command("zipinfo", args: ["-1", self], print_stderr: false)
    .stdout
    .encode(Encoding::UTF_8, invalid: :replace)
    .split("\n"),
    T.nilable(T::Array[String]),
  )
end