Module: Puppet::FileSystem

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

Overview

API:

  • public

Defined Under Namespace

Classes: AbsolutePathPattern, File18, File19, File19Windows, FileImpl, MemoryFile, MemoryImpl, PathPattern, RelativePathPattern, Uniquefile

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:

  • when path is not of the expected type

API:

  • public



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

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

.basename(path) ⇒ Object

Returns the name of the file as a opaque handle.

Returns:

  • the name of the file as a opaque handle

API:

  • public



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

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

.basename_string(path) ⇒ String

Returns the name of the file.

Returns:

  • the name of the file

API:

  • public



81
82
83
 
# File 'lib/puppet/file_system.rb', line 81

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:

  • The binary contents of the file

API:

  • public



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

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:

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

API:

  • public



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

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:

  • The mode to apply to the file if it is created

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

Raises:

  • : path doesn’t exist

API:

  • public



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

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

.compare_stream(path, stream) ⇒ Boolean

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

Parameters:

  • The stream to compare the contents against

Returns:

  • Whether the contents were the same

API:

  • public



317
318
319
 
# File 'lib/puppet/file_system.rb', line 317

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:

  • The directory of this file as an opaque handle

API:

  • public



47
48
49
 
# File 'lib/puppet/file_system.rb', line 47

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

.dir_exist?(path) ⇒ Boolean

Returns Does the directory of the given path exist?.

Returns:

  • Does the directory of the given path exist?

API:

  • public



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

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

.dir_mkpath(path) ⇒ Object

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

API:

  • public



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

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:

  • The directory of this file as a String

API:

  • public



55
56
57
 
# File 'lib/puppet/file_system.rb', line 55

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:

  • true if the given file is a directory.

API:

  • public



169
170
171
 
# File 'lib/puppet/file_system.rb', line 169

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

API:

  • public



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

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:

  • path already exists.

See Also:

  • open

API:

  • public



362
363
364
 
# File 'lib/puppet/file_system.rb', line 362

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 aquire the lock the process will wait ever increasing amounts of time in order to prevent multiple processes from wasting resources.

Parameters:

  • the path to the file to operate on

  • The mode to apply to the file if it is created

  • (defaults to: 'r')

    Extra file operation mode information to use (defaults to read-only mode)

  • (defaults to: 300)

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

Yields:

  • The file handle, in read-write mode

Returns:

Raises:

  • If the timeout is exceeded while waiting to acquire the lock

API:

  • public



112
113
114
 
# File 'lib/puppet/file_system.rb', line 112

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:

  • true if this file can be executed

API:

  • public



190
191
192
 
# File 'lib/puppet/file_system.rb', line 190

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:

  • true if the named file exists.

API:

  • public



160
161
162
 
# File 'lib/puppet/file_system.rb', line 160

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

.file?(path) ⇒ Boolean

Determines if a file is a file.

Returns:

  • true if the given file is a file.

API:

  • public



178
179
180
 
# File 'lib/puppet/file_system.rb', line 178

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

.lstat(path) ⇒ File::Stat

link. Instead, reports on the link itself.

Returns:

  • Same as stat, but does not follow the last symbolic

API:

  • public



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

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

.mkpath(path) ⇒ Object

Creates directories for all parts of the given path.

API:

  • public



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

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

.open(path, mode, options, &block) ⇒ Object

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

API:

  • public



39
40
41
 
# File 'lib/puppet/file_system.rb', line 39

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:

  • the files to have available

API:

  • private



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

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

.path_string(path) ⇒ String

Produces a string representation of the opaque path handle.

Parameters:

  • a path handle produced by #pathname

Returns:

  • a string representation of the path

API:

  • public



350
351
352
 
# File 'lib/puppet/file_system.rb', line 350

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:

  • The string representation of the path

Returns:

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

API:

  • public



331
332
333
 
# File 'lib/puppet/file_system.rb', line 331

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

.read(path) ⇒ String

Returns The contents of the file.

Returns:

  • The contents of the file

API:

  • public



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

def self.read(path)
  @impl.read(assert_path(path))
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:

  • The contents of the file

API:

  • public



141
142
143
 
# File 'lib/puppet/file_system.rb', line 141

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:

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

API:

  • public



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

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

.size(path) ⇒ Integer

Returns the size of the file.

Returns:

  • the size of the file

API:

  • public



89
90
91
 
# File 'lib/puppet/file_system.rb', line 89

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

.stat(path) ⇒ File::Stat

Returns object for the named file.

Returns:

  • object for the named file.

API:

  • public



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

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:

  • The path to create the new symlink at

  • (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:

  • 0

Raises:

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

API:

  • public



252
253
254
 
# File 'lib/puppet/file_system.rb', line 252

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:

  • true if the file is a symbolic link.

API:

  • public



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

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

.touch(path) ⇒ Object

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

API:

  • public



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

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

.unlink(*paths) ⇒ Integer

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

Returns:

  • the number of paths passed as arguments

Raises:

  • an exception on any error.

API:

  • public



281
282
283
 
# File 'lib/puppet/file_system.rb', line 281

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:

  • Whether the file is writable by the current process

API:

  • public



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

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