Response class for Unavailable For Legal Reasons responses (status code 451).
A server operator has received a legal demand to deny access to a resource or to a set of resources that includes the requested resource. See 451 Unavailable For Legal Reasons.
Helper methods for both Gem::Installer and Gem::Uninstaller
FIXME: This isn’t documented in Nutshell.
Since MonitorMixin.new_cond returns a ConditionVariable, and the example above calls while_wait and signal, this class should be documented.
Response class for Precondition Failed responses (status code 412).
The server does not meet one of the preconditions specified in the request headers. See 412 Precondition Failed.
Response class for Expectation Failed responses (status code 417).
The server cannot meet the requirements of the Expect request-header field. See 417 Expectation Failed.
ConditionVariable objects augment class Mutex. Using condition variables, it is possible to suspend while in the middle of a critical section until a resource becomes available.
Example:
mutex = Thread::Mutex.new resource = Thread::ConditionVariable.new a = Thread.new { mutex.synchronize { # Thread 'a' now needs the resource resource.wait(mutex) # 'a' can now have the resource } } b = Thread.new { mutex.synchronize { # Thread 'b' has finished using the resource resource.signal } }
Module that defines the default UserInteraction. Any class including this module will have access to the ui method that returns the default UI.
Potentially raised when a specification is validated.
Represents an error communicating via HTTP.
Raised by Resolver when a dependency requests a gem for which there is no spec.
Keyword completion module. This allows partial arguments to be specified and resolved against a list of acceptable values.
Mixin methods for local and remote Gem::Command options.
An Encoding instance represents a character encoding usable in Ruby. It is defined as a constant under the Encoding namespace. It has a name and, optionally, aliases:
Encoding::US_ASCII.name # => "US-ASCII" Encoding::US_ASCII.names # => ["US-ASCII", "ASCII", "ANSI_X3.4-1968", "646"]
A Ruby method that accepts an encoding as an argument will accept:
An Encoding object.
The name of an encoding.
An alias for an encoding name.
These are equivalent:
'foo'.encode(Encoding::US_ASCII) # Encoding object. 'foo'.encode('US-ASCII') # Encoding name. 'foo'.encode('ASCII') # Encoding alias.
For a full discussion of encodings and their uses, see the Encodings document.
Encoding::ASCII_8BIT is a special-purpose encoding that is usually used for a string of bytes, not a string of characters. But as the name indicates, its characters in the ASCII range are considered as ASCII characters. This is useful when you use other ASCII-compatible encodings.
Raised when a feature is not implemented on the current platform. For example, methods depending on the fsync or fork system calls may raise this exception if the underlying operating system or Ruby runtime does not support them.
Note that if fork raises a NotImplementedError, then respond_to?(:fork) returns false.
EncodingError is the base class for encoding errors.
Use the Monitor class when you want to have a lock object for blocks with mutual exclusion.
require 'monitor' lock = Monitor.new lock.synchronize do # exclusive access end
Namespace for file utility methods for copying, moving, removing, etc.
First, what’s elsewhere. Module FileUtils:
Inherits from class Object.
Supplements class File (but is not included or extended there).
Here, module FileUtils provides methods that are useful for:
::mkdir: Creates directories.
::mkdir_p, ::makedirs, ::mkpath: Creates directories, also creating ancestor directories as needed.
::link_entry: Creates a hard link.
::ln_sf: Creates symbolic links, overwriting if necessary.
::ln_sr: Creates symbolic links relative to targets
::remove_dir: Removes a directory and its descendants.
::remove_entry: Removes an entry, including its descendants if it is a directory.
::remove_entry_secure: Like ::remove_entry, but removes securely.
::remove_file: Removes a file entry.
::rm_f, ::safe_unlink: Like ::rm, but removes forcibly.
::rm_r: Removes entries and their descendants.
::rmdir: Removes directories.
::uptodate?: Returns whether a given entry is newer than given other entries.
::chmod: Sets permissions for an entry.
::chmod_R: Sets permissions for an entry and its descendants.
::chown: Sets the owner and group for entries.
::chown_R: Sets the owner and group for entries and their descendants.
::touch: Sets modification and access times for entries, creating if necessary.
::compare_file, ::cmp, ::identical?: Returns whether two entries are identical.
::compare_stream: Returns whether two streams are identical.
::copy_entry: Recursively copies an entry.
::copy_file: Copies an entry.
::copy_stream: Copies a stream.
::cp_lr: Recursively creates hard links.
::cp_r: Recursively copies files, retaining mode, owner, and group.
::install: Recursively copies files, optionally setting mode, owner, and group.
::collect_method: Returns the names of methods that accept a given option.
::commands: Returns the names of methods that accept options.
::have_option?: Returns whether a given method accepts a given option.
::options: Returns all option names.
::options_of: Returns the names of the options for a given method.
Some methods in FileUtils accept path arguments, which are interpreted as paths to filesystem entries:
If the argument is a string, that value is the path.
If the argument has method :to_path, it is converted via that method.
If the argument has method :to_str, it is converted via that method.
Some examples here involve trees of file entries. For these, we sometimes display trees using the tree command-line utility, which is a recursive directory-listing utility that produces a depth-indented listing of files and directories.
We use a helper method to launch the command and control the format:
def tree(dirpath = '.') command = "tree --noreport --charset=ascii #{dirpath}" system(command) end
To illustrate:
tree('src0') # => src0 # |-- sub0 # | |-- src0.txt # | `-- src1.txt # `-- sub1 # |-- src2.txt # `-- src3.txt
For certain methods that recursively remove entries, there is a potential vulnerability called the Time-of-check to time-of-use, or TOCTTOU, vulnerability that can exist when:
An ancestor directory of the entry at the target path is world writable; such directories include /tmp.
The directory tree at the target path includes:
A world-writable descendant directory.
A symbolic link.
To avoid that vulnerability, you can use this method to remove entries:
FileUtils.remove_entry_secure: removes recursively if the target path points to a directory.
Also available are these methods, each of which calls FileUtils.remove_entry_secure:
FileUtils.rm_r with keyword argument secure: true.
FileUtils.rm_rf with keyword argument secure: true.
Finally, this method for moving entries calls FileUtils.remove_entry_secure if the source and destination are on different file systems (which means that the “move” is really a copy and remove):
FileUtils.mv with keyword argument secure: true.
Method FileUtils.remove_entry_secure removes securely by applying a special pre-process:
If the target path points to a directory, this method uses methods File#chown and File#chmod in removing directories.
The owner of the target directory should be either the current process or the super user (root).
WARNING: You must ensure that ALL parent directories cannot be moved by other untrusted users. For example, parent directories should not be owned by untrusted users, and should not be world writable except when the sticky bit is set.
For details of this security vulnerability, see Perl cases: