fileutils.rb

Copyright © 2000-2007 Minero Aoki

This program is free software. You can distribute/modify this program under the same terms of ruby.

module FileUtils

Namespace for several file utility methods for copying, moving, removing, etc.

Module Functions

require 'fileutils'

FileUtils.cd(dir, **options)
FileUtils.cd(dir, **options) {|dir| block }
FileUtils.pwd()
FileUtils.mkdir(dir, **options)
FileUtils.mkdir(list, **options)
FileUtils.mkdir_p(dir, **options)
FileUtils.mkdir_p(list, **options)
FileUtils.rmdir(dir, **options)
FileUtils.rmdir(list, **options)
FileUtils.ln(target, link, **options)
FileUtils.ln(targets, dir, **options)
FileUtils.ln_s(target, link, **options)
FileUtils.ln_s(targets, dir, **options)
FileUtils.ln_sf(target, link, **options)
FileUtils.cp(src, dest, **options)
FileUtils.cp(list, dir, **options)
FileUtils.cp_r(src, dest, **options)
FileUtils.cp_r(list, dir, **options)
FileUtils.mv(src, dest, **options)
FileUtils.mv(list, dir, **options)
FileUtils.rm(list, **options)
FileUtils.rm_r(list, **options)
FileUtils.rm_rf(list, **options)
FileUtils.install(src, dest, **options)
FileUtils.chmod(mode, list, **options)
FileUtils.chmod_R(mode, list, **options)
FileUtils.chown(user, group, list, **options)
FileUtils.chown_R(user, group, list, **options)
FileUtils.touch(list, **options)

Possible options are:

:force

forced operation (rewrite files if exist, remove directories if not empty, etc.);

:verbose

print command to be run, in bash syntax, before performing it;

:preserve

preserve object’s group, user and modification time on copying;

:noop

no changes are made (usable in combination with :verbose which will print the command to run)

Each method documents the options that it honours. See also ::commands, ::options and ::options_of methods to introspect which command have which options.

All methods that have the concept of a “source” file or directory can take either one file or a list of files in that argument. See the method documentation for examples.

There are some ‘low level’ methods, which do not accept keyword arguments:

FileUtils.copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
FileUtils.copy_file(src, dest, preserve = false, dereference = true)
FileUtils.copy_stream(srcstream, deststream)
FileUtils.remove_entry(path, force = false)
FileUtils.remove_entry_secure(path, force = false)
FileUtils.remove_file(path, force = false)
FileUtils.compare_file(path_a, path_b)
FileUtils.compare_stream(stream_a, stream_b)
FileUtils.uptodate?(file, cmp_list)

module FileUtils::Verbose

This module has all methods of FileUtils module, but it outputs messages before acting. This equates to passing the :verbose flag to methods in FileUtils.

module FileUtils::NoWrite

This module has all methods of FileUtils module, but never changes files/directories. This equates to passing the :noop flag to methods in FileUtils.

module FileUtils::DryRun

This module has all methods of FileUtils module, but never changes files/directories. This equates to passing the :noop and :verbose flags to methods in FileUtils.

The Singleton module implements the Singleton pattern.

Usage

To use Singleton, include the module in your class.

class Klass
   include Singleton
   # ...
end

This ensures that only one instance of Klass can be created.

a,b  = Klass.instance, Klass.instance

a == b
# => true

Klass.new
# => NoMethodError - new is private ...

The instance is created at upon the first call of Klass.instance().

class OtherKlass
  include Singleton
  # ...
end

ObjectSpace.each_object(OtherKlass){}
# => 0

OtherKlass.instance
ObjectSpace.each_object(OtherKlass){}
# => 1

This behavior is preserved under inheritance and cloning.

Implementation

This above is achieved by:

• Making Klass.new and Klass.allocate private.

• Overriding Klass.inherited(sub_klass) and Klass.clone() to ensure that the Singleton properties are kept when inherited and cloned.

• Providing the Klass.instance() method that returns the same object each time it is called.

• Overriding Klass._load(str) to call Klass.instance().

• Overriding Klass#clone and Klass#dup to raise TypeErrors to prevent cloning or duping.

Singleton and Marshal

By default Singleton’s _dump(depth) returns the empty string. Marshalling by default will strip state information, e.g. instance variables from the instance. Classes using Singleton can provide custom _load(str) and _dump(depth) methods to retain some of the previous state of the instance.

require 'singleton'

class Example
  include Singleton
  attr_accessor :keep, :strip
  def _dump(depth)
    # this strips the @strip information from the instance
    Marshal.dump(@keep, depth)
  end

  def self._load(str)
    instance.keep = Marshal.load(str)
    instance
  end
end

a = Example.instance
a.keep = "keep this"
a.strip = "get rid of this"

stored_state = Marshal.dump(a)

a.keep = nil
a.strip = nil
b = Marshal.load(stored_state)
p a == b  #  => true
p a.keep  #  => "keep this"
p a.strip #  => nil

define UnicodeNormalize module here so that we don’t have to look it up

Signals that a file permission error is preventing the user from operating on the given directory.

Mixin module providing HTML generation methods.

For example,

cgi.a("http://www.example.com") { "Example" }
  # => "<A HREF=\"http://www.example.com\">Example</A>"

Modules Html3, Html4, etc., contain more basic HTML-generation methods (#title, #h1, etc.).

See class CGI for a detailed example.

Configuration options for dumping YAML.

An InstalledSpecification represents a gem that is already installed locally.

This exception is raised if the required unicode support is missing on the system. Usually this means that the iconv library is not installed.

Exception raised when there is an invalid encoding detected