Module: Puppet::FileSystem Private

Defined in:
lib/puppet/file_system.rb,
lib/puppet/file_system/path_pattern.rb

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.

Defined Under Namespace

Classes: AbsolutePathPattern, FileImpl, JRuby, MemoryFile, MemoryImpl, PathPattern, Posix, RelativePathPattern, Uniquefile, Windows

Class Method Summary collapse

Class Method Details

.assert_path(path) ⇒ Object

Asserts that the given path is of the expected type produced by #pathname

Raises:

  • (ArgumentError) —

    when path is not of the expected type



366
367
368
 
# File 'lib/puppet/file_system.rb', line 366

def self.assert_path(path)
  @impl.assert_path(path)
end

.basename(path) ⇒ Object

Returns the name of the file as a opaque handle.



85
86
87
 
# File 'lib/puppet/file_system.rb', line 85

def self.basename(path)
  @impl.basename(assert_path(path))
end

.basename_string(path) ⇒ String

Returns the name of the file.



93
94
95
 
# File 'lib/puppet/file_system.rb', line 93

def self.basename_string(path)
  @impl.path_string(@impl.basename(assert_path(path)))
end

.binread(path) ⇒ String

Returns The binary contents of the file.



156
157
158
 
# File 'lib/puppet/file_system.rb', line 156

def self.binread(path)
  @impl.binread(assert_path(path))
end

.children(path) ⇒ Array<Object>

Returns references to all of the children of the given directory path, excluding ‘.` and `..`.



230
231
232
 
# File 'lib/puppet/file_system.rb', line 230

def self.children(path)
  @impl.children(assert_path(path))
end

.chmod(mode, path) ⇒ Object

Changes permission bits on the named path to the bit pattern represented by mode.

Raises:

  • (Errno::ENOENT) —

    : path doesn’t exist



401
402
403
 
# File 'lib/puppet/file_system.rb', line 401

def self.chmod(mode, path)
  @impl.chmod(mode, assert_path(path))
end

.compare_stream(path, stream) ⇒ Boolean

Compares the contents of this file against the contents of a stream.



326
327
328
 
# File 'lib/puppet/file_system.rb', line 326

def self.compare_stream(path, stream)
  @impl.compare_stream(assert_path(path), stream)
end

.dir(path) ⇒ Object

Returns The directory of this file as an opaque handle.



59
60
61
 
# File 'lib/puppet/file_system.rb', line 59

def self.dir(path)
  @impl.dir(assert_path(path))
end

.dir_exist?(path) ⇒ 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 Does the directory of the given path exist?.



72
73
74
 
# File 'lib/puppet/file_system.rb', line 72

def self.dir_exist?(path)
  @impl.exist?(@impl.dir(assert_path(path)))
end

.dir_mkpath(path) ⇒ Object

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.

Creates all directories down to (inclusive) the dir of the given path



77
78
79
 
# File 'lib/puppet/file_system.rb', line 77

def self.dir_mkpath(path)
  @impl.mkpath(@impl.dir(assert_path(path)))
end

.dir_string(path) ⇒ String

Returns The directory of this file as a String.



67
68
69
 
# File 'lib/puppet/file_system.rb', line 67

def self.dir_string(path)
  @impl.path_string(@impl.dir(assert_path(path)))
end

.directory?(path) ⇒ Boolean

Determines if a file is a directory.



176
177
178
 
# File 'lib/puppet/file_system.rb', line 176

def self.directory?(path)
  @impl.directory?(assert_path(path))
end

.each_line(path, &block) ⇒ Object

Processes each line of the file by yielding it to the given block



127
128
129
 
# File 'lib/puppet/file_system.rb', line 127

def self.each_line(path, &block)
  @impl.each_line(assert_path(path), &block)
end

.exclusive_create(path, mode, &block) ⇒ Object

Create and open a file for write only if it doesn’t exist.

Raises:

  • (Errno::EEXIST) —

    path already exists.

See Also:

  • open


387
388
389
 
# File 'lib/puppet/file_system.rb', line 387

def self.exclusive_create(path, mode, &block)
  @impl.exclusive_create(assert_path(path), mode, &block)
end

.exclusive_open(path, mode, options = 'r', timeout = 300) { ... } ⇒ Void

Allows exclusive updates to a file to be made by excluding concurrent access using flock. This means that if the file is on a filesystem that does not support flock, this method will provide no protection.

While polling to acquire the lock the process will wait ever increasing amounts of time in order to prevent multiple processes from wasting resources.

Yields:

  • The file handle, in the mode given by options, else read-write mode

Raises:

  • (Timeout::Error) —

    If the timeout is exceeded while waiting to acquire the lock



119
120
121
 
# File 'lib/puppet/file_system.rb', line 119

def self.exclusive_open(path, mode, options = 'r', timeout = 300, &block)
  @impl.exclusive_open(assert_path(path), mode, options, timeout, &block)
end

.executable?(path) ⇒ Boolean

TODO:

Should this take into account extensions on the windows platform?

Determines if a file is executable.



197
198
199
 
# File 'lib/puppet/file_system.rb', line 197

def self.executable?(path)
  @impl.executable?(assert_path(path))
end

.exist?(path) ⇒ Boolean

Determines if a file exists by verifying that the file can be stat’d. Will follow symlinks and verify that the actual target path exists.



167
168
169
 
# File 'lib/puppet/file_system.rb', line 167

def self.exist?(path)
  @impl.exist?(assert_path(path))
end

.expand_path(path, dir_string = nil) ⇒ 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.

Produces a string representation of the opaque path handle, with expansions performed on ~. For Windows, this means that C:UsersAdmini~1AppData will be expanded to C:UsersAdministratorAppData. On POSIX filesystems, the value ~ will be expanded to something like /Users/Foo

This method exists primarlily to resolve a Ruby deficiency where File.expand_path doesn’t convert short paths to long paths, which is important when resolving the path to load.



356
357
358
 
# File 'lib/puppet/file_system.rb', line 356

def self.expand_path(path, dir_string = nil)
  @impl.expand_path(path, dir_string)
end

.file?(path) ⇒ Boolean

Determines if a file is a file.



185
186
187
 
# File 'lib/puppet/file_system.rb', line 185

def self.file?(path)
  @impl.file?(assert_path(path))
end

.lstat(path) ⇒ File::Stat

link. Instead, reports on the link itself.



315
316
317
 
# File 'lib/puppet/file_system.rb', line 315

def self.lstat(path)
  @impl.lstat(assert_path(path))
end

.mkpath(path) ⇒ Object

Creates directories for all parts of the given path.



223
224
225
 
# File 'lib/puppet/file_system.rb', line 223

def self.mkpath(path)
  @impl.mkpath(assert_path(path))
end

.open(path, mode, options) { ... } ⇒ Void

Opens the given path with given mode, and options and optionally yields it to the given block.

Yields:

  • The file handle, in the mode given by options, else read-write mode



51
52
53
 
# File 'lib/puppet/file_system.rb', line 51

def self.open(path, mode, options, &block)
  @impl.open(assert_path(path), mode, options, &block)
end

.overlay(*files, &block) ⇒ Object

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.

Allows overriding the filesystem for the duration of the given block. The filesystem will only contain the given file(s).



30
31
32
33
34
35
36
 
# File 'lib/puppet/file_system.rb', line 30

def self.overlay(*files, &block)
  old_impl = @impl
  @impl = Puppet::FileSystem::MemoryImpl.new(*files)
  yield
ensure
  @impl = old_impl
end

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

Produces a string representation of the opaque path handle.



375
376
377
 
# File 'lib/puppet/file_system.rb', line 375

def self.path_string(path)
  @impl.path_string(path)
end

.pathname(path) ⇒ Object

Produces an opaque pathname “handle” object representing the given path. Different implementations of the underlying file system may use different runtime objects. The produced “handle” should be used in all other operations that take a “path”. No operation should be directly invoked on the returned opaque object



340
341
342
 
# File 'lib/puppet/file_system.rb', line 340

def self.pathname(path)
  @impl.pathname(path)
end

.read(path, opts = {}) ⇒ String

Returns The contents of the file.



135
136
137
 
# File 'lib/puppet/file_system.rb', line 135

def self.read(path, opts = {})
  @impl.read(assert_path(path), opts)
end

.read_preserve_line_endings(path) ⇒ String

Read a file keeping the original line endings intact. This attempts to open files using binary mode using some encoding overrides and falling back to IO.read when none of the encodings are valid.



148
149
150
 
# File 'lib/puppet/file_system.rb', line 148

def self.read_preserve_line_endings(path)
  @impl.read_preserve_line_endings(assert_path(path))
end

.readlink(path) ⇒ String

Returns the name of the file referenced by the given link.



277
278
279
 
# File 'lib/puppet/file_system.rb', line 277

def self.readlink(path)
  @impl.readlink(assert_path(path))
end

.replace_file(path, mode = nil, &block) ⇒ Object

Replace the contents of a file atomically, creating the file if necessary. If a ‘mode` is specified, then it will always be applied to the file. If a `mode` is not specified and the file exists, its mode will be preserved. If the file doesn’t exist, the mode will be set to a platform-specific default.

Raises:

  • (Errno::EISDIR) —

    : path is a directory



418
419
420
 
# File 'lib/puppet/file_system.rb', line 418

def self.replace_file(path, mode = nil, &block)
  @impl.replace_file(assert_path(path), mode, &block)
end

.size(path) ⇒ Integer

Returns the size of the file.



306
307
308
 
# File 'lib/puppet/file_system.rb', line 306

def self.size(path)
  @impl.size(assert_path(path))
end

.stat(path) ⇒ File::Stat

Returns object for the named file.



298
299
300
 
# File 'lib/puppet/file_system.rb', line 298

def self.stat(path)
  @impl.stat(assert_path(path))
end

.symlink(path, dest, options = {}) ⇒ Integer

Creates a symbolic link dest which points to the current file. If dest already exists:

  • and is a file, will raise Errno::EEXIST

  • and is a directory, will return 0 but perform no action

  • and is a symlink referencing a file, will raise Errno::EEXIST

  • and is a symlink referencing a directory, will return 0 but perform no action

With the :force option set to true, when dest already exists:

  • and is a file, will replace the existing file with a symlink (DANGEROUS)

  • and is a directory, will return 0 but perform no action

  • and is a symlink referencing a file, will modify the existing symlink

  • and is a symlink referencing a directory, will return 0 but perform no action

Options Hash (options):

  • :force (Boolean) —

    overwrite dest

  • :noop (Boolean) —

    do not perform the operation

  • :verbose (Boolean) —

    verbose output

Raises:

  • (Errno::EEXIST) —

    dest already exists as a file and, :force is not set



261
262
263
 
# File 'lib/puppet/file_system.rb', line 261

def self.symlink(path, dest, options = {})
  @impl.symlink(assert_path(path), dest, options)
end

.symlink?(path) ⇒ Boolean

Returns true if the file is a symbolic link.



269
270
271
 
# File 'lib/puppet/file_system.rb', line 269

def self.symlink?(path)
  @impl.symlink?(assert_path(path))
end

.touch(path, mtime: nil) ⇒ Object

Touches the file. On most systems this updates the mtime of the file.



215
216
217
 
# File 'lib/puppet/file_system.rb', line 215

def self.touch(path, mtime: nil)
  @impl.touch(assert_path(path), mtime: mtime)
end

.unlink(*paths) ⇒ Integer

Deletes the given paths, returning the number of names passed as arguments. See also Dir::rmdir.

Raises:

  • an exception on any error.



290
291
292
 
# File 'lib/puppet/file_system.rb', line 290

def self.unlink(*paths)
  @impl.unlink(*(paths.map { |p| assert_path(p) }))
end

.writable?(path) ⇒ Boolean

Returns Whether the file is writable by the current process.



205
206
207
 
# File 'lib/puppet/file_system.rb', line 205

def self.writable?(path)
  @impl.writable?(assert_path(path))
end