Class: Pathname Private

Inherits:
Object show all
Includes:
DiskUsageExtension, EagerInitializeExtension, 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

#issue_reporting_message, #odebug, #odeprecated, #odie, #odisabled, #ofail, #oh1, #oh1_title, #ohai, #ohai_title, #onoe, #opoo, #opoo_outside_github_actions, #opoo_without_github_actions_annotation, #pretty_deprecated, #pretty_disabled, #pretty_duration, #pretty_install_status, #pretty_installed, #pretty_outdated, #pretty_uninstalled, #pretty_upgradable

Methods included from DiskUsageExtension

#abv, #disk_usage, #file_count

Methods included from SystemCommand::Mixin

#system_command, #system_command!

Methods included from EagerInitializeExtension

#initialize

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.



36
37
38
 
# File 'extend/pathname.rb', line 36

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) 


99
100
101
102
103
 
# File 'extend/pathname.rb', line 99

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) 


427
428
429
 
# File 'extend/pathname.rb', line 427

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:



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
139
140
 
# File 'extend/pathname.rb', line 111

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) 


412
413
414
 
# File 'extend/pathname.rb', line 412

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)) 


244
245
246
 
# File 'extend/pathname.rb', line 244

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:



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

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) 


407
408
409
 
# File 'extend/pathname.rb', line 407

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) 


422
423
424
 
# File 'extend/pathname.rb', line 422

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) 


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

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:



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

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:



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

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:



449
450
451
452
453
 
# File 'extend/pathname.rb', line 449

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:



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

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.



290
291
292
 
# File 'extend/pathname.rb', line 290

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:



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

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:



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

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) 


417
418
419
 
# File 'extend/pathname.rb', line 417

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:



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

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:



272
273
274
275
 
# File 'extend/pathname.rb', line 272

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:



257
258
259
 
# File 'extend/pathname.rb', line 257

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) 


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

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) 


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

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:



432
433
434
 
# File 'extend/pathname.rb', line 432

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:



221
222
223
224
 
# File 'extend/pathname.rb', line 221

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

#stem ⇒ String

For filetypes we support, returns basename without extension.

Returns:



187
188
189
 
# File 'extend/pathname.rb', line 187

def stem
  File.basename(self, extname)
end

#subdirs ⇒ Array<Pathname>

Get all sub-directories of this directory.

Returns:



252
253
254
 
# File 'extend/pathname.rb', line 252

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) 


216
217
218
 
# File 'extend/pathname.rb', line 216

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.



295
296
297
 
# File 'extend/pathname.rb', line 295

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:



227
228
229
230
231
232
 
# File 'extend/pathname.rb', line 227

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:



210
211
212
213
 
# File 'extend/pathname.rb', line 210

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:



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

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:



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

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:



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

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:



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

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