Module: Mutineer::FsPath

Defined in:
lib/mutineer/fs_path.rb

Overview

Filesystem paths as one encoding (#346).

With LANG and LC_ALL unset, Ruby's filesystem encoding is US-ASCII. A non-ASCII name then comes back as ASCII-8BIT, or as US-ASCII with those bytes marked invalid (Coverage result keys). The same bytes in two encodings compare unequal, a regexp raises, and JSON.generate refuses the string. Read every such path as UTF-8 when the bytes are UTF-8, and as binary otherwise, so both copies share one encoding.

Defined Under Namespace

Modules: PathFilter

Constant Summary collapse

PATH =

This file, so a coverage subprocess can require the same rule.

File.expand_path(__FILE__)

Class Method Summary collapse

Class Method Details

.bytes_delete_prefix(text, prefix) ⇒ String

text without a byte prefix, read again as UTF-8 or binary. text itself when the prefix is absent.

Parameters:

  • text (String)
  • prefix (String)

Returns:

  • (String)


51
52
53
54
55
56
57
# File 'lib/mutineer/fs_path.rb', line 51

def self.bytes_delete_prefix(text, prefix)
  raw = text.to_s.b
  pre = prefix.to_s.b
  return read(text) unless raw.start_with?(pre)

  read(raw.byteslice(pre.bytesize..).b)
end

.bytes_start_with?(text, prefix) ⇒ Boolean

True when text's bytes begin with prefix's bytes. Encodings are not compared, so a UTF-8 root and a binary file name do not raise (#346).

Parameters:

  • text (String)
  • prefix (String)

Returns:

  • (Boolean)


41
42
43
# File 'lib/mutineer/fs_path.rb', line 41

def self.bytes_start_with?(text, prefix)
  text.to_s.b.start_with?(prefix.to_s.b)
end

.expand(path, base = nil) ⇒ String

Absolute form of path, passed through read.

Parameters:

  • path (String)
  • base (String, nil) (defaults to: nil) —

    directory path is relative to.

Returns:

  • (String)


64
65
66
67
# File 'lib/mutineer/fs_path.rb', line 64

def self.expand(path, base = nil)
  expanded = base.nil? ? File.expand_path(path) : File.expand_path(path, base)
  read(expanded)
end

.filesystem(path) ⇒ String

path tagged the way Dir.pwd is tagged in this process.

read is for comparison and JSON. load must use this encoding: Minitest records the path it was given and later calls delete_prefix with "#{Dir.pwd}/". Those two encodings differ for a non-ASCII directory under LC_ALL=C, and delete_prefix raises (#346).

Parameters:

  • path (String)

Returns:

  • (String)


78
79
80
81
82
83
84
# File 'lib/mutineer/fs_path.rb', line 78

def self.filesystem(path)
  text = read(path)
  tagged = text.dup.force_encoding(Dir.pwd.encoding)
  return tagged if tagged.valid_encoding?

  text.dup.force_encoding(Encoding::ASCII_8BIT)
end

.install_minitest_path_filter! ⇒ void

This method returns an undefined value.

Minitest filters a failure backtrace with a regexp and then shortens the path against Dir.pwd. Under LC_ALL=C those lines are US-ASCII with the directory's bytes, so the regexp raises and a killed mutant is reported as an error (#346). Retag each line to filesystem first. No-op until Minitest is loaded. Safe to call more than once.



93
94
95
96
97
98
# File 'lib/mutineer/fs_path.rb', line 93

def self.install_minitest_path_filter!
  return unless defined?(::Minitest::BacktraceFilter)
  return if ::Minitest::BacktraceFilter < PathFilter

  ::Minitest::BacktraceFilter.prepend(PathFilter)
end

.read(path) ⇒ String?

path as UTF-8 when its bytes are UTF-8, otherwise as binary. ASCII-only text is returned as it is: ASCII encodings already compare equal. nil stays nil.

Parameters:

  • path (String, nil)

Returns:

  • (String, nil)


22
23
24
25
26
27
28
29
30
31
32
# File 'lib/mutineer/fs_path.rb', line 22

def self.read(path)
  return path if path.nil?

  text = String.try_convert(path) || path.to_s
  return text if stable?(text)

  utf8 = text.dup.force_encoding(Encoding::UTF_8)
  return utf8 if utf8.valid_encoding?

  text.dup.force_encoding(Encoding::ASCII_8BIT)
end

.stable?(text) ⇒ Boolean (private)

True when text needs no retag: valid UTF-8, or bytes that are ASCII in whatever encoding they carry. An invalid byte sequence is not stable.

Parameters:

  • text (String)

Returns:

  • (Boolean)


116
117
118
119
120
121
122
# File 'lib/mutineer/fs_path.rb', line 116

def self.stable?(text)
  return true if text.encoding == Encoding::UTF_8 && text.valid_encoding?

  text.ascii_only?
rescue ArgumentError
  false
end