module Puppet::FileSystem - Puppet - Configuration Management

assert_path(path) click to toggle source

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

@raise [ArgumentError] when path is not of the expected type

@api public

    # File lib/puppet/file_system.rb
365 def self.assert_path(path)
366   @impl.assert_path(path)
367 end

basename(path) click to toggle source

@return [Object] the name of the file as a opaque handle

@api public

   # File lib/puppet/file_system.rb
84 def self.basename(path)
85   @impl.basename(assert_path(path))
86 end

basename_string(path) click to toggle source

@return [String] the name of the file

@api public

   # File lib/puppet/file_system.rb
92 def self.basename_string(path)
93   @impl.path_string(@impl.basename(assert_path(path)))
94 end

binread(path) click to toggle source

@return [String] The binary contents of the file

@api public

    # File lib/puppet/file_system.rb
155 def self.binread(path)
156   @impl.binread(assert_path(path))
157 end

children(path) click to toggle source

@return [Array<Object>] references to all of the children of the given

directory path, excluding `.` and `..`.

@api public

    # File lib/puppet/file_system.rb
229 def self.children(path)
230   @impl.children(assert_path(path))
231 end

chmod(mode, path) click to toggle source

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

@param mode [Integer] The mode to apply to the file if it is created @param path [String] The path to the file, can also accept [PathName]

@raise [Errno::ENOENT]: path doesn't exist

@api public

    # File lib/puppet/file_system.rb
400 def self.chmod(mode, path)
401   @impl.chmod(mode, assert_path(path))
402 end

compare_stream(path, stream) click to toggle source

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

@param stream [IO] The stream to compare the contents against @return [Boolean] Whether the contents were the same

@api public

    # File lib/puppet/file_system.rb
325 def self.compare_stream(path, stream)
326   @impl.compare_stream(assert_path(path), stream)
327 end

dir(path) click to toggle source

@return [Object] The directory of this file as an opaque handle

@api public

   # File lib/puppet/file_system.rb
58 def self.dir(path)
59   @impl.dir(assert_path(path))
60 end

dir_exist?(path) click to toggle source

@return [Boolean] Does the directory of the given path exist?

   # File lib/puppet/file_system.rb
71 def self.dir_exist?(path)
72   @impl.exist?(@impl.dir(assert_path(path)))
73 end

dir_mkpath(path) click to toggle source

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

   # File lib/puppet/file_system.rb
76 def self.dir_mkpath(path)
77   @impl.mkpath(@impl.dir(assert_path(path)))
78 end

dir_string(path) click to toggle source

@return [String] The directory of this file as a String

@api public

   # File lib/puppet/file_system.rb
66 def self.dir_string(path)
67   @impl.path_string(@impl.dir(assert_path(path)))
68 end

directory?(path) click to toggle source

Determines if a file is a directory.

@return [Boolean] true if the given file is a directory.

@api public

    # File lib/puppet/file_system.rb
175 def self.directory?(path)
176   @impl.directory?(assert_path(path))
177 end

each_line(path, &block) click to toggle source

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

@api public

    # File lib/puppet/file_system.rb
126 def self.each_line(path, &block)
127   @impl.each_line(assert_path(path), &block)
128 end

exclusive_create(path, mode, &block) click to toggle source

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

@see Puppet::FileSystem::open

@raise [Errno::EEXIST] path already exists.

@api public

    # File lib/puppet/file_system.rb
386 def self.exclusive_create(path, mode, &block)
387   @impl.exclusive_create(assert_path(path), mode, &block)
388 end

exclusive_open(path, mode, options = 'r', timeout = 300, &block) click to toggle source

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.

@param path [Pathname] the path to the file to operate on @param mode [Integer] The mode to apply to the file if it is created @param options [String] 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

@param timeout [Integer] Number of seconds to wait for the lock (defaults to 300) @yield The file handle, in the mode given by options, else read-write mode @return [Void] @raise [Timeout::Error] If the timeout is exceeded while waiting to acquire the lock

@api public

    # File lib/puppet/file_system.rb
118 def self.exclusive_open(path, mode, options = 'r', timeout = 300, &block)
119   @impl.exclusive_open(assert_path(path), mode, options, timeout, &block)
120 end

executable?(path) click to toggle source

Determines if a file is executable.

@todo Should this take into account extensions on the windows platform?

@return [Boolean] true if this file can be executed

@api public

    # File lib/puppet/file_system.rb
196 def self.executable?(path)
197   @impl.executable?(assert_path(path))
198 end

exist?(path) click to toggle source

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.

@return [Boolean] true if the named file exists.

@api public

    # File lib/puppet/file_system.rb
166 def self.exist?(path)
167   @impl.exist?(assert_path(path))
168 end

expand_path(path, dir_string = nil) click to toggle source

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.

@param path [Object] a path handle produced by {#pathname} @return [String] a string representation of the path

    # File lib/puppet/file_system.rb
355 def self.expand_path(path, dir_string = nil)
356   @impl.expand_path(path, dir_string)
357 end

file?(path) click to toggle source

Determines if a file is a file.

@return [Boolean] true if the given file is a file.

@api public

    # File lib/puppet/file_system.rb
184 def self.file?(path)
185   @impl.file?(assert_path(path))
186 end

lstat(path) click to toggle source

@return [File::Stat] Same as stat, but does not follow the last symbolic link. Instead, reports on the link itself.

@api public

    # File lib/puppet/file_system.rb
314 def self.lstat(path)
315   @impl.lstat(assert_path(path))
316 end

mkpath(path) click to toggle source

Creates directories for all parts of the given path.

@api public

    # File lib/puppet/file_system.rb
222 def self.mkpath(path)
223   @impl.mkpath(assert_path(path))
224 end

open(path, mode, options, &block) click to toggle source

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

@param path [String, Pathname] the path to the file to operate on @param mode [Integer] The mode to apply to the file if it is created @param 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

@yield The file handle, in the mode given by options, else read-write mode @return [Void]

@api public

   # File lib/puppet/file_system.rb
50 def self.open(path, mode, options, &block)
51   @impl.open(assert_path(path), mode, options, &block)
52 end

overlay(*files) { || ... } click to toggle source

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

@param files [Puppet::FileSystem::MemoryFile] the files to have available

@api private

   # File lib/puppet/file_system.rb
29 def self.overlay(*files, &block)
30   old_impl = @impl
31   @impl = Puppet::FileSystem::MemoryImpl.new(*files)
32   yield
33 ensure
34   @impl = old_impl
35 end

path_string(path) click to toggle source

Produces a string representation of the opaque path handle.

@param path [Object] a path handle produced by {#pathname} @return [String] a string representation of the path

    # File lib/puppet/file_system.rb
374 def self.path_string(path)
375   @impl.path_string(path)
376 end

pathname(path) click to toggle source

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

@param path [String] The string representation of the path @return [Object] An opaque path handle on which no operations should be directly performed

@api public

    # File lib/puppet/file_system.rb
339 def self.pathname(path)
340   @impl.pathname(path)
341 end

read(path, opts = {}) click to toggle source

@return [String] The contents of the file

@api public

    # File lib/puppet/file_system.rb
134 def self.read(path, opts = {})
135   @impl.read(assert_path(path), opts)
136 end

read_preserve_line_endings(path) click to toggle source

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.

@return [String] The contents of the file

@api public

    # File lib/puppet/file_system.rb
147 def self.read_preserve_line_endings(path)
148   @impl.read_preserve_line_endings(assert_path(path))
149 end

readlink(path) click to toggle source

@return [String] the name of the file referenced by the given link.

@api public

    # File lib/puppet/file_system.rb
276 def self.readlink(path)
277   @impl.readlink(assert_path(path))
278 end

replace_file(path, mode = nil, &block) click to toggle source

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.

@param path [String] The path to the file, can also accept [PathName] @param mode [Integer] Optional mode for the file.

@raise [Errno::EISDIR]: path is a directory

@api public

    # File lib/puppet/file_system.rb
417 def self.replace_file(path, mode = nil, &block)
418   @impl.replace_file(assert_path(path), mode, &block)
419 end

size(path) click to toggle source

@return [Integer] the size of the file

@api public

    # File lib/puppet/file_system.rb
305 def self.size(path)
306   @impl.size(assert_path(path))
307 end

stat(path) click to toggle source

@return [File::Stat] object for the named file.

@api public

    # File lib/puppet/file_system.rb
297 def self.stat(path)
298   @impl.stat(assert_path(path))
299 end

symlink(path, dest, options = {}) click to toggle source

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

@param dest [String] The path to create the new symlink at @param [Hash] options the options to create the symlink with @option options [Boolean] :force overwrite dest @option options [Boolean] :noop do not perform the operation @option options [Boolean] :verbose verbose output

@raise [Errno::EEXIST] dest already exists as a file and, :force is not set

@return [Integer] 0

@api public

    # File lib/puppet/file_system.rb
260 def self.symlink(path, dest, options = {})
261   @impl.symlink(assert_path(path), dest, options)
262 end

symlink?(path) click to toggle source

@return [Boolean] true if the file is a symbolic link.

@api public

    # File lib/puppet/file_system.rb
268 def self.symlink?(path)
269   @impl.symlink?(assert_path(path))
270 end

touch(path, mtime: nil) click to toggle source

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

@param mtime [Time] The last modified time or nil to use the current time

@api public

    # File lib/puppet/file_system.rb
214 def self.touch(path, mtime: nil)
215   @impl.touch(assert_path(path), mtime: mtime)
216 end

unlink(*paths) click to toggle source

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

@raise an exception on any error.

@return [Integer] the number of paths passed as arguments

@api public

    # File lib/puppet/file_system.rb
289 def self.unlink(*paths)
290   @impl.unlink(*(paths.map {|p| assert_path(p) }))
291 end

writable?(path) click to toggle source

@return [Boolean] Whether the file is writable by the current process

@api public

    # File lib/puppet/file_system.rb
204 def self.writable?(path)
205   @impl.writable?(assert_path(path))
206 end