Class: Puppet::FileSystem::File Private

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/file_system/file.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

An abstraction over the ruby file system operations for a single file.

For the time being this is being kept private so that we can evolve it for a while.

Direct Known Subclasses

File18, File19

Constant Summary collapse

IMPL =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

if RUBY_VERSION =~ /^1\.8/
  require 'puppet/file_system/file18'
  Puppet::FileSystem::File18
elsif Puppet::Util::Platform.windows?
  require 'puppet/file_system/file19windows'
  Puppet::FileSystem::File19Windows
else
  require 'puppet/file_system/file19'
  Puppet::FileSystem::File19
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path) ⇒ File

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 a new instance of File.



63
64
65
66
67
68
69
 
# File 'lib/puppet/file_system/file.rb', line 63

def initialize(path)
  if path.is_a?(Pathname)
    @path = path
  else
    @path = Pathname.new(path)
  end
end

Instance Attribute Details

#path ⇒ Object (readonly)

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. 



8
9
10
 
# File 'lib/puppet/file_system/file.rb', line 8

def path
  @path
end

Class Method Details

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

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



151
152
153
154
 
# File 'lib/puppet/file_system/file.rb', line 151

def self.exist?(path)
  return IMPL.exist?(path) if IMPL.method(:exist?) != self.method(:exist?)
  File.exist?(path)
end

.forget(file) ⇒ 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.

Note:

This API should only be used for testing

Forget a remembered file

Parameters:

  • file (Object) —

    an object that conforms to the Puppet::FileSystem::File interface



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

def self.forget(file)
  @remembered.delete(file.path.to_s)
end

.new(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. 



23
24
25
26
27
28
29
30
31
 
# File 'lib/puppet/file_system/file.rb', line 23

def self.new(path)
  if @remembered.include?(path.to_s)
    @remembered[path.to_s]
  else
    file = IMPL.allocate
    file.send(:initialize, path)
    file
  end
end

.overlay(file, &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.

Note:

This API should only be used for testing

Run a block of code with a file accessible in the filesystem.

Parameters:

  • file (Object) —

    an object that conforms to the Puppet::FileSystem::File interface



38
39
40
41
42
43
 
# File 'lib/puppet/file_system/file.rb', line 38

def self.overlay(file, &block)
  remember(file)
  yield
ensure
  forget(file)
end

.remember(file) ⇒ 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.

Note:

This API should only be used for testing

Create a binding between a filename and a particular instance of a file object.

Parameters:

  • file (Object) —

    an object that conforms to the Puppet::FileSystem::File interface



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

def self.remember(file)
  @remembered[file.path.to_s] = file
end

.unlink(*file_names) ⇒ Integer

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.

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

Returns:

  • (Integer) —

    the number of names passed as arguments

Raises:

  • an exception on any error.



233
234
235
236
 
# File 'lib/puppet/file_system/file.rb', line 233

def self.unlink(*file_names)
  return IMPL.unlink(*file_names) if IMPL.method(:unlink) != self.method(:unlink)
  File.unlink(*file_names)
end

Instance Method Details

#basename ⇒ String

Returns the name of the file.

Returns:

  • (String) —

    the name of the file



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

def basename
  @path.basename.to_s
end

#binread ⇒ 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.

Returns The binary contents of the file.

Returns:

  • (String) —

    The binary contents of the file

Raises:

  • (NotImplementedError) 


143
144
145
 
# File 'lib/puppet/file_system/file.rb', line 143

def binread
  raise NotImplementedError
end

#compare_stream(stream) ⇒ 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.

Compare 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



262
263
264
265
266
 
# File 'lib/puppet/file_system/file.rb', line 262

def compare_stream(stream)
  open(0, 'rb') do |this|
    FileUtils.compare_stream(this, stream)
  end
end

#dir ⇒ Puppet::FileSystem::File

Returns The directory of this file.

Returns:



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

def dir
  Puppet::FileSystem::File.new(@path.dirname)
end

#each_line(&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. 



129
130
131
132
133
134
135
 
# File 'lib/puppet/file_system/file.rb', line 129

def each_line(&block)
  ::File.open(@path) do |f|
    f.each_line do |line|
      yield line
    end
  end
end

#exclusive_open(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.

(defaults to read-only mode)

Parameters:

  • mode (Integer) —

    The mode to apply to the file if it is created

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

    Extra file operation mode information to use

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

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

Yields:

  • The file handle, in read-write mode

Returns:

  • (Void)

Raises:

  • (Timeout::Error) —

    If the timeout is exceeded while waiting to aquire the lock



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/puppet/file_system/file.rb', line 109

def exclusive_open(mode, options = 'r', timeout = 300, &block)
  wait = 0.001 + (Kernel.rand / 1000)
  written = false
  while !written
    ::File.open(@path, options, mode) do |rf|
      if rf.flock(::File::LOCK_EX|::File::LOCK_NB)
        yield rf
        written = true
      else
        sleep wait
        timeout -= wait
        wait *= 2
        if timeout < 0
          raise Timeout::Error, "Timeout waiting for exclusive lock on #{@path}"
        end
      end
    end
  end
end

#executable? ⇒ 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.

TODO:

Should this take into account extensions on the windows platform?

Determine if a file is executable.

Returns:

  • (Boolean) —

    true if this file can be executed



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

def executable?
  ::File.executable?(@path)
end

#exist? ⇒ 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.

Determine 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 path of this file is present



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

def exist?
  self.class.exist?(@path)
end

#lstat ⇒ File::Stat

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.

link. Instead, reports on the link itself.

Returns:

  • (File::Stat) —

    Same as stat, but does not follow the last symbolic



255
256
257
 
# File 'lib/puppet/file_system/file.rb', line 255

def lstat
  File.lstat(@path)
end

#mkpath ⇒ 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.

Create the entire path as directories



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

def mkpath
  @path.mkpath
end

#open(mode, options, &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. 



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

def open(mode, options, &block)
  ::File.open(@path, options, mode, &block)
end

#read ⇒ 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.

Returns The contents of the file.

Returns:

  • (String) —

    The contents of the file



138
139
140
 
# File 'lib/puppet/file_system/file.rb', line 138

def read
  @path.read
end

#readlink ⇒ 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.

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

Returns:

  • (String) —

    the name of the file referenced by the given link.



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

def readlink
  File.readlink(@path)
end

#size ⇒ Num

Returns The size of this file.

Returns:

  • (Num) —

    The size of this file



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

def size
  @path.size
end

#stat ⇒ File::Stat

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 object for the named file.

Returns:

  • (File::Stat) —

    object for the named file.



249
250
251
 
# File 'lib/puppet/file_system/file.rb', line 249

def stat
  File.stat(@path)
end

#symlink(dest, options = {}) ⇒ Integer

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



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

def symlink(dest, options = {})
  FileUtils.symlink(@path, dest, options)
end

#symlink? ⇒ 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 true if the file is a symbolic link.

Returns:

  • (Boolean) —

    true if the file is a symbolic link.



218
219
220
 
# File 'lib/puppet/file_system/file.rb', line 218

def symlink?
  File.symlink?(@path)
end

#to_s ⇒ 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. 



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

def to_s
  @path.to_s
end

#touch ⇒ 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.

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



180
181
182
 
# File 'lib/puppet/file_system/file.rb', line 180

def touch
  ::FileUtils.touch(@path)
end

#unlink ⇒ Integer

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.

Deletes the file. See also Dir::rmdir.

Returns:

  • (Integer) —

    the number of names passed as arguments, in this case 1

Raises:

  • an exception on any error.



244
245
246
 
# File 'lib/puppet/file_system/file.rb', line 244

def unlink
  self.class.unlink(@path)
end

#writable? ⇒ 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.

process

Returns:

  • (Boolean) —

    Whether the file is writable by the current



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

def writable?
  @path.writable?
end