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



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

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

.basename(path) ⇒ Object

Returns the name of the file as a opaque handle.

Returns:

  • (Object) —

    the name of the file as a opaque handle



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

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

.basename_string(path) ⇒ String

Returns the name of the file.

Returns:

  • (String) —

    the name of the file



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

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

.binread(path) ⇒ String

Returns The binary contents of the file.

Returns:

  • (String) —

    The binary contents of the file



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

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 `..`.

Returns:

  • (Array<Object>) —

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



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

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.

Parameters:

  • mode (Integer) —

    The mode to apply to the file if it is created

  • path (String) —

    The path to the file, can also accept [PathName]

Raises:

  • (Errno::ENOENT) —

    : path doesn’t exist



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

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.

Parameters:

  • stream (IO) —

    The stream to compare the contents against

Returns:

  • (Boolean) —

    Whether the contents were the same



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

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.

Returns:

  • (Object) —

    The directory of this file as an opaque handle



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

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?.

Returns:

  • (Boolean) —

    Does the directory of the given path exist?



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

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



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

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.

Returns:

  • (String) —

    The directory of this file as a String



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

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

.directory?(path) ⇒ Boolean

Determines if a file is a directory.

Returns:

  • (Boolean) —

    true if the given file is a directory.



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

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



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

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


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

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.

Parameters:

  • path (Pathname) —

    the path to the file to operate on

  • mode (Integer) —

    The mode to apply to the file if it is created

  • options (String) (defaults to: 'r') —

    Extra file operation mode information to use (defaults to read-only mode ‘r’) This is the standard mechanism Ruby uses in the IO class, and therefore encoding may be specified explicitly as fmode : encoding or fmode : “BOM|UTF-*” for example, a:ASCII or w+:UTF-8

  • timeout (Integer) (defaults to: 300) —

    Number of seconds to wait for the lock (defaults to 300)

Yields:

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

Returns:

  • (Void)

Raises:

  • (Timeout::Error) —

    If the timeout is exceeded while waiting to acquire the lock



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

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.

Returns:

  • (Boolean) —

    true if this file can be executed



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

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.

Returns:

  • (Boolean) —

    true if the named file exists.



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

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.

Parameters:

  • path (Object) —

    a path handle produced by #pathname

Returns:

  • (String) —

    a string representation of the path



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

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.

Returns:

  • (Boolean) —

    true if the given file is a file.



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

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

.lstat(path) ⇒ File::Stat

link. Instead, reports on the link itself.

Returns:

  • (File::Stat) —

    Same as stat, but does not follow the last symbolic



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

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

.mkpath(path) ⇒ Object

Creates directories for all parts of the given path.



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

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.

Parameters:

  • path (String, Pathname) —

    the path to the file to operate on

  • mode (Integer) —

    The mode to apply to the file if it is created

  • options (String) —

    Extra file operation mode information to use This is the standard mechanism Ruby uses in the IO class, and therefore encoding may be specified explicitly as fmode : encoding or fmode : “BOM|UTF-*” for example, a:ASCII or w+:UTF-8

Yields:

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

Returns:

  • (Void) 


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

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

Parameters:



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

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.

Parameters:

  • path (Object) —

    a path handle produced by #pathname

Returns:

  • (String) —

    a string representation of the path



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

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

Parameters:

  • path (String) —

    The string representation of the path

Returns:

  • (Object) —

    An opaque path handle on which no operations should be directly performed



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

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

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

Returns The contents of the file.

Returns:

  • (String) —

    The contents of the file



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

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.

Returns:

  • (String) —

    The contents of the file



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

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.

Returns:

  • (String) —

    the name of the file referenced by the given link.



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

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.

Parameters:

  • path (String) —

    The path to the file, can also accept [PathName]

  • mode (Integer) (defaults to: nil) —

    Optional mode for the file.

Raises:

  • (Errno::EISDIR) —

    : path is a directory



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

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.

Returns:

  • (Integer) —

    the size of the file



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

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

.stat(path) ⇒ File::Stat

Returns object for the named file.

Returns:

  • (File::Stat) —

    object for the named file.



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

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

Parameters:

  • dest (String) —

    The path to create the new symlink at

  • options (Hash) (defaults to: {}) —

    the options to create the symlink with

Options Hash (options):

  • :force (Boolean) —

    overwrite dest

  • :noop (Boolean) —

    do not perform the operation

  • :verbose (Boolean) —

    verbose output

Returns:

  • (Integer) —

    0

Raises:

  • (Errno::EEXIST) —

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



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

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.

Returns:

  • (Boolean) —

    true if the file is a symbolic link.



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

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.

Parameters:

  • mtime (Time) (defaults to: nil) —

    The last modified time or nil to use the current time



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

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.

Returns:

  • (Integer) —

    the number of paths passed as arguments

Raises:

  • an exception on any error.



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

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.

Returns:

  • (Boolean) —

    Whether the file is writable by the current process



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

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