module Puppet::FileSystem
Public Class Methods
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 363 def self.assert_path(path) 364 @impl.assert_path(path) 365 end
@return [Object] the name of the file as a opaque handle
@api public
# File lib/puppet/file_system.rb 83 def self.basename(path) 84 @impl.basename(assert_path(path)) 85 end
@return [String] the name of the file
@api public
# File lib/puppet/file_system.rb 91 def self.basename_string(path) 92 @impl.path_string(@impl.basename(assert_path(path))) 93 end
@return [String] The binary contents of the file
@api public
# File lib/puppet/file_system.rb 154 def self.binread(path) 155 @impl.binread(assert_path(path)) 156 end
@return [Array<Object>] references to all of the children of the given
directory path, excluding `.` and `..`.
@api public
# File lib/puppet/file_system.rb 228 def self.children(path) 229 @impl.children(assert_path(path)) 230 end
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 398 def self.chmod(mode, path) 399 @impl.chmod(mode, path) 400 end
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 324 def self.compare_stream(path, stream) 325 @impl.compare_stream(assert_path(path), stream) 326 end
@return [Object] The directory of this file as an opaque handle
@api public
# File lib/puppet/file_system.rb 57 def self.dir(path) 58 @impl.dir(assert_path(path)) 59 end
@return [Boolean] Does the directory of the given path exist?
# File lib/puppet/file_system.rb 70 def self.dir_exist?(path) 71 @impl.exist?(@impl.dir(assert_path(path))) 72 end
Creates all directories down to (inclusive) the dir of the given path
# File lib/puppet/file_system.rb 75 def self.dir_mkpath(path) 76 @impl.mkpath(@impl.dir(assert_path(path))) 77 end
@return [String] The directory of this file as a String
@api public
# File lib/puppet/file_system.rb 65 def self.dir_string(path) 66 @impl.path_string(@impl.dir(assert_path(path))) 67 end
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 174 def self.directory?(path) 175 @impl.directory?(assert_path(path)) 176 end
Processes each line of the file by yielding it to the given block
@api public
# File lib/puppet/file_system.rb 125 def self.each_line(path, &block) 126 @impl.each_line(assert_path(path), &block) 127 end
Create and open a file for write only if it doesn't exist.
@raise [Errno::EEXIST] path already exists.
@api public
# File lib/puppet/file_system.rb 384 def self.exclusive_create(path, mode, &block) 385 @impl.exclusive_create(assert_path(path), mode, &block) 386 end
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 117 def self.exclusive_open(path, mode, options = 'r', timeout = 300, &block) 118 @impl.exclusive_open(assert_path(path), mode, options, timeout, &block) 119 end
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 195 def self.executable?(path) 196 @impl.executable?(assert_path(path)) 197 end
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 165 def self.exist?(path) 166 @impl.exist?(assert_path(path)) 167 end
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 handle ~ in each segment on a Windows
path
@param path [Object] a path handle produced by {#pathname} @return [String] a string representation of the path
# File lib/puppet/file_system.rb 353 def self.expand_path(path, dir_string = nil) 354 @impl.expand_path(path, dir_string) 355 end
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 183 def self.file?(path) 184 @impl.file?(assert_path(path)) 185 end
@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 313 def self.lstat(path) 314 @impl.lstat(assert_path(path)) 315 end
Creates directories for all parts of the given path.
@api public
# File lib/puppet/file_system.rb 221 def self.mkpath(path) 222 @impl.mkpath(assert_path(path)) 223 end
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 49 def self.open(path, mode, options, &block) 50 @impl.open(assert_path(path), mode, options, &block) 51 end
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 28 def self.overlay(*files, &block) 29 old_impl = @impl 30 @impl = Puppet::FileSystem::MemoryImpl.new(*files) 31 yield 32 ensure 33 @impl = old_impl 34 end
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 372 def self.path_string(path) 373 @impl.path_string(path) 374 end
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 338 def self.pathname(path) 339 @impl.pathname(path) 340 end
@return [String] The contents of the file
@api public
# File lib/puppet/file_system.rb 133 def self.read(path, opts = {}) 134 @impl.read(assert_path(path), opts) 135 end
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 146 def self.read_preserve_line_endings(path) 147 @impl.read_preserve_line_endings(assert_path(path)) 148 end
@return [String] the name of the file referenced by the given link.
@api public
# File lib/puppet/file_system.rb 275 def self.readlink(path) 276 @impl.readlink(assert_path(path)) 277 end
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 415 def self.replace_file(path, mode = nil, &block) 416 @impl.replace_file(assert_path(path), mode, &block) 417 end
@return [Integer] the size of the file
@api public
# File lib/puppet/file_system.rb 304 def self.size(path) 305 @impl.size(assert_path(path)) 306 end
@return [File::Stat] object for the named file.
@api public
# File lib/puppet/file_system.rb 296 def self.stat(path) 297 @impl.stat(assert_path(path)) 298 end
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 259 def self.symlink(path, dest, options = {}) 260 @impl.symlink(assert_path(path), dest, options) 261 end
@return [Boolean] true if the file is a symbolic link.
@api public
# File lib/puppet/file_system.rb 267 def self.symlink?(path) 268 @impl.symlink?(assert_path(path)) 269 end
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 213 def self.touch(path, mtime: nil) 214 @impl.touch(assert_path(path), mtime: mtime) 215 end
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 288 def self.unlink(*paths) 289 @impl.unlink(*(paths.map {|p| assert_path(p) })) 290 end
@return [Boolean] Whether the file is writable by the current process
@api public
# File lib/puppet/file_system.rb 203 def self.writable?(path) 204 @impl.writable?(assert_path(path)) 205 end