A complex literal.
Method Complex.rect.
Method Kernel#Complex, either with numeric arguments or with certain string arguments.
Method String#to_c, for certain strings.

Note that each of the stored parts may be a an instance one of the classes Complex, Float, Integer, or Rational; they may be retrieved:

Separately, with methods Complex#real and Complex#imaginary.
Together, with method Complex#rect.

The corresponding (computed) polar values may be retrieved:

Separately, with methods Complex#abs and Complex#arg.
Together, with method Complex#polar.

Polar Coordinates

The polar coordinates of a complex number are called the absolute and argument parts; see Complex polar plane.

In this class, the argument part in expressed radians (not degrees).

You can create a Complex object from polar coordinates with:

Method Complex.polar.
Method Kernel#Complex, with certain string arguments.
Method String#to_c, for certain strings.

Note that each of the stored parts may be a an instance one of the classes Complex, Float, Integer, or Rational; they may be retrieved:

Separately, with methods Complex#abs and Complex#arg.
Together, with method Complex#polar.

The corresponding (computed) rectangular values may be retrieved:

Separately, with methods Complex#real and Complex#imag.
Together, with method Complex#rect.

What’s Here

First, what’s elsewhere:

Class Complex inherits (directly or indirectly) from classes Numeric and Object.
Includes (indirectly) module Comparable.

Here, class Complex has methods for:

Creating Complex Objects

::polar: Returns a new Complex object based on given polar coordinates.
::rect (and its alias ::rectangular): Returns a new Complex object based on given rectangular coordinates.

Querying

abs (and its alias magnitude): Returns the absolute value for self.
arg (and its aliases angle and phase): Returns the argument (angle) for self in radians.
denominator: Returns the denominator of self.
finite?: Returns whether both self.real and self.image are finite.
hash: Returns the integer hash value for self.
imag (and its alias imaginary): Returns the imaginary value for self.
infinite?: Returns whether self.real or self.image is infinite.
numerator: Returns the numerator of self.
polar: Returns the array [self.abs, self.arg].
inspect: Returns a string representation of self.
real: Returns the real value for self.
real?: Returns false; for compatibility with Numeric#real?.
rect (and its alias rectangular): Returns the array [self.real, self.imag].

Comparing

<=>: Returns whether self is less than, equal to, or greater than the given argument.
==: Returns whether self is equal to the given argument.

Converting

rationalize: Returns a Rational object whose value is exactly or approximately equivalent to that of self.real.
to_c: Returns self.
to_d: Returns the value as a BigDecimal object.
to_f: Returns the value of self.real as a Float, if possible.
to_i: Returns the value of self.real as an Integer, if possible.
to_r: Returns the value of self.real as a Rational, if possible.
to_s: Returns a string representation of self.

Performing `Complex` Arithmetic

*: Returns the product of self and the given numeric.
**: Returns self raised to power of the given numeric.
+: Returns the sum of self and the given numeric.
-: Returns the difference of self and the given numeric.
-@: Returns the negation of self.
/: Returns the quotient of self and the given numeric.
abs2: Returns square of the absolute value (magnitude) for self.
conj (and its alias conjugate): Returns the conjugate of self.
fdiv: Returns Complex.rect(self.real/numeric, self.imag/numeric).

Working with `JSON`

::json_create: Returns a new Complex object, deserialized from the given serialized hash.
as_json: Returns a serialized hash constructed from self.
to_json: Returns a JSON string representing self.

These methods are provided by the JSON gem. To make these methods available:

require 'json/add/complex'

File

A File object is a representation of a file in the underlying platform.

Class File extends module FileTest, supporting such singleton methods as File.exist?.

About the Examples

Many examples here use these variables:

# English text with newlines.
text = <<~EOT
  First line
  Second line

  Fourth line
  Fifth line
EOT

# Russian text.
russian = "\u{442 435 441 442}" # => "тест"

# Binary data.
data = "\u9990\u9991\u9992\u9993\u9994"

# Text file.
File.write('t.txt', text)

# File with Russian text.
File.write('t.rus', russian)

# File with binary data.
f = File.new('t.dat', 'wb:UTF-16')
f.write(data)
f.close

Access Modes

Methods File.new and File.open each create a File object for a given file path.

String Access Modes

Methods File.new and File.open each may take string argument mode, which:

Begins with a 1- or 2-character read/write mode.
May also contain a 1-character data mode.
May also contain a 1-character file-create mode.

Read/Write Mode

The read/write mode determines:

Whether the file is to be initially truncated.
Whether reading is allowed, and if so:
- The initial read position in the file.
- Where in the file reading can occur.
Whether writing is allowed, and if so:
- The initial write position in the file.
- Where in the file writing can occur.

These tables summarize:

Read/Write Modes for Existing File

|------|-----------|----------|----------|----------|-----------|
| R/W  | Initial   |          | Initial  |          | Initial   |
| Mode | Truncate? |  Read    | Read Pos |  Write   | Write Pos |
|------|-----------|----------|----------|----------|-----------|
| 'r'  |    No     | Anywhere |    0     |   Error  |     -     |
| 'w'  |    Yes    |   Error  |    -     | Anywhere |     0     |
| 'a'  |    No     |   Error  |    -     | End only |    End    |
| 'r+' |    No     | Anywhere |    0     | Anywhere |     0     |
| 'w+' |    Yes    | Anywhere |    0     | Anywhere |     0     |
| 'a+' |    No     | Anywhere |   End    | End only |    End    |
|------|-----------|----------|----------|----------|-----------|

Read/Write Modes for \File To Be Created

|------|----------|----------|----------|-----------|
| R/W  |          | Initial  |          | Initial   |
| Mode |  Read    | Read Pos |  Write   | Write Pos |
|------|----------|----------|----------|-----------|
| 'w'  |   Error  |    -     | Anywhere |     0     |
| 'a'  |   Error  |    -     | End only |     0     |
| 'w+' | Anywhere |    0     | Anywhere |     0     |
| 'a+' | Anywhere |    0     | End only |    End    |
|------|----------|----------|----------|-----------|

Note that modes 'r' and 'r+' are not allowed for a non-existent file (exception raised).

In the tables:

Anywhere means that methods IO#rewind, IO#pos=, and IO#seek may be used to change the file’s position, so that allowed reading or writing may occur anywhere in the file.
End only means that writing can occur only at end-of-file, and that methods IO#rewind, IO#pos=, and IO#seek do not affect writing.
Error means that an exception is raised if disallowed reading or writing is attempted.

Read/Write Modes for Existing File

'r':

File is not initially truncated:

f = File.new('t.txt') # => #<File:t.txt>
f.size == 0           # => false

File’s initial read position is 0:
```
f.pos # => 0
```

File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:

f.readline # => "First line\n"
f.readline # => "Second line\n"

f.rewind
f.readline # => "First line\n"

f.pos = 1
f.readline # => "irst line\n"

f.seek(1, :CUR)
f.readline # => "econd line\n"

Writing is not allowed:
```
f.write('foo') # Raises IOError.
```

'w':

File is initially truncated:

path = 't.tmp'
File.write(path, text)
f = File.new(path, 'w')
f.size == 0 # => true

File’s initial write position is 0:
```
f.pos # => 0
```

File may be written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

f.write('foo')
f.flush
File.read(path) # => "foo"
f.pos # => 3

f.write('bar')
f.flush
File.read(path) # => "foobar"
f.pos # => 6

f.rewind
f.write('baz')
f.flush
File.read(path) # => "bazbar"
f.pos # => 3

f.pos = 3
f.write('foo')
f.flush
File.read(path) # => "bazfoo"
f.pos # => 6

f.seek(-3, :END)
f.write('bam')
f.flush
File.read(path) # => "bazbam"
f.pos # => 6

f.pos = 8
f.write('bah')  # Zero padding as needed.
f.flush
File.read(path) # => "bazbam\u0000\u0000bah"
f.pos # => 11

Reading is not allowed:
```
f.read # Raises IOError.
```

'a':

File is not initially truncated:

path = 't.tmp'
File.write(path, 'foo')
f = File.new(path, 'a')
f.size == 0 # => false

File’s initial position is 0 (but is ignored):
```
f.pos # => 0
```

File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek do not affect writing:

f.write('bar')
f.flush
File.read(path) # => "foobar"
f.write('baz')
f.flush
File.read(path) # => "foobarbaz"

f.rewind
f.write('bat')
f.flush
File.read(path) # => "foobarbazbat"

Reading is not allowed:
```
f.read # Raises IOError.
```

'r+':

File is not initially truncated:

path = 't.tmp'
File.write(path, text)
f = File.new(path, 'r+')
f.size == 0 # => false

File’s initial read position is 0:
```
f.pos # => 0
```

File may be read or written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

f.readline # => "First line\n"
f.readline # => "Second line\n"

f.rewind
f.readline # => "First line\n"

f.pos = 1
f.readline # => "irst line\n"

f.seek(1, :CUR)
f.readline # => "econd line\n"

f.rewind
f.write('WWW')
f.flush
File.read(path)
# => "WWWst line\nSecond line\nFourth line\nFifth line\n"

f.pos = 10
f.write('XXX')
f.flush
File.read(path)
# => "WWWst lineXXXecond line\nFourth line\nFifth line\n"

f.seek(-6, :END)
# => 0
f.write('YYY')
# => 3
f.flush
# => #<File:t.tmp>
File.read(path)
# => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n"

f.seek(2, :END)
f.write('ZZZ') # Zero padding as needed.
f.flush
File.read(path)
# => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"

'a+':

File is not initially truncated:

path = 't.tmp'
File.write(path, 'foo')
f = File.new(path, 'a+')
f.size == 0 # => false

File’s initial read position is 0:
```
f.pos # => 0
```

File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek do not affect writing:

f.write('bar')
f.flush
File.read(path)      # => "foobar"
f.write('baz')
f.flush
File.read(path)      # => "foobarbaz"

f.rewind
f.write('bat')
f.flush
File.read(path) # => "foobarbazbat"

File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:

f.rewind
f.read # => "foobarbazbat"

f.pos = 3
f.read # => "barbazbat"

f.seek(-3, :END)
f.read # => "bat"

Read/Write Modes for File To Be Created

Note that modes 'r' and 'r+' are not allowed for a non-existent file (exception raised).

'w':

File’s initial write position is 0:

path = 't.tmp'
FileUtils.rm_f(path)
f = File.new(path, 'w')
f.pos # => 0

File may be written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

f.write('foo')
f.flush
File.read(path) # => "foo"
f.pos # => 3

f.write('bar')
f.flush
File.read(path) # => "foobar"
f.pos # => 6

f.rewind
f.write('baz')
f.flush
File.read(path) # => "bazbar"
f.pos # => 3

f.pos = 3
f.write('foo')
f.flush
File.read(path) # => "bazfoo"
f.pos # => 6

f.seek(-3, :END)
f.write('bam')
f.flush
File.read(path) # => "bazbam"
f.pos # => 6

f.pos = 8
f.write('bah')  # Zero padding as needed.
f.flush
File.read(path) # => "bazbam\u0000\u0000bah"
f.pos # => 11

Reading is not allowed:
```
f.read # Raises IOError.
```

'a':

File’s initial write position is 0:

path = 't.tmp'
FileUtils.rm_f(path)
f = File.new(path, 'a')
f.pos # => 0

Writing occurs only at end-of-file:

f.write('foo')
f.pos # => 3
f.write('bar')
f.pos # => 6
f.flush
File.read(path) # => "foobar"

f.rewind
f.write('baz')
f.flush
File.read(path) # => "foobarbaz"

Reading is not allowed:
```
f.read # Raises IOError.
```

'w+':

File’s initial position is 0:

path = 't.tmp'
FileUtils.rm_f(path)
f = File.new(path, 'w+')
f.pos # => 0

File may be written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

f.write('foo')
f.flush
File.read(path) # => "foo"
f.pos # => 3

f.write('bar')
f.flush
File.read(path) # => "foobar"
f.pos # => 6

f.rewind
f.write('baz')
f.flush
File.read(path) # => "bazbar"
f.pos # => 3

f.pos = 3
f.write('foo')
f.flush
File.read(path) # => "bazfoo"
f.pos # => 6

f.seek(-3, :END)
f.write('bam')
f.flush
File.read(path) # => "bazbam"
f.pos # => 6

f.pos = 8
f.write('bah')  # Zero padding as needed.
f.flush
File.read(path) # => "bazbam\u0000\u0000bah"
f.pos # => 11

File may be read anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

f.rewind
# => 0
f.read
# => "bazbam\u0000\u0000bah"

f.pos = 3
# => 3
f.read
# => "bam\u0000\u0000bah"

f.seek(-3, :END)
# => 0
f.read
# => "bah"

'a+':

File’s initial write position is 0:

path = 't.tmp'
FileUtils.rm_f(path)
f = File.new(path, 'a+')
f.pos # => 0

Writing occurs only at end-of-file:

f.write('foo')
f.pos # => 3
f.write('bar')
f.pos # => 6
f.flush
File.read(path) # => "foobar"

f.rewind
f.write('baz')
f.flush
File.read(path) # => "foobarbaz"

File may be read anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

f.rewind
f.read # => "foobarbaz"

f.pos = 3
f.read # => "barbaz"

f.seek(-3, :END)
f.read # => "baz"

f.pos = 800
f.read # => ""

Data Mode

To specify whether data is to be treated as text or as binary data, either of the following may be suffixed to any of the string read/write modes above:

't': Text data; sets the default external encoding to Encoding::UTF_8; on Windows, enables conversion between EOL and CRLF and enables interpreting 0x1A as an end-of-file marker.
'b': Binary data; sets the default external encoding to Encoding::ASCII_8BIT; on Windows, suppresses conversion between EOL and CRLF and disables interpreting 0x1A as an end-of-file marker.

If neither is given, the stream defaults to text data.

Examples:

File.new('t.txt', 'rt')
File.new('t.dat', 'rb')

When the data mode is specified, the read/write mode may not be omitted, and the data mode must precede the file-create mode, if given:

File.new('t.dat', 'b')   # Raises an exception.
File.new('t.dat', 'rxb') # Raises an exception.

File-Create Mode

The following may be suffixed to any writable string mode above:

'x': Creates the file if it does not exist; raises an exception if the file exists.

Example:

File.new('t.tmp', 'wx')

When the file-create mode is specified, the read/write mode may not be omitted, and the file-create mode must follow the data mode:

File.new('t.dat', 'x')   # Raises an exception.
File.new('t.dat', 'rxb') # Raises an exception.

Integer Access Modes

When mode is an integer it must be one or more of the following constants, which may be combined by the bitwise OR operator |:

File::RDONLY: Open for reading only.
File::WRONLY: Open for writing only.
File::RDWR: Open for reading and writing.
File::APPEND: Open for appending only.

Examples:

File.new('t.txt', File::RDONLY)
File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)

Note: Method IO#set_encoding does not allow the mode to be specified as an integer.

File-Create Mode Specified as an Integer

These constants may also be ORed into the integer mode:

File::CREAT: Create file if it does not exist.
File::EXCL: Raise an exception if File::CREAT is given and the file exists.

Data Mode Specified as an Integer

Data mode cannot be specified as an integer. When the stream access mode is given as an integer, the data mode is always text, never binary.

Note that although there is a constant File::BINARY, setting its value in an integer stream mode has no effect; this is because, as documented in File::Constants, the File::BINARY value disables line code conversion, but does not change the external encoding.

Encodings

Any of the string modes above may specify encodings - either external encoding only or both external and internal encodings - by appending one or both encoding names, separated by colons:

f = File.new('t.dat', 'rb')
f.external_encoding # => #<Encoding:ASCII-8BIT>
f.internal_encoding # => nil
f = File.new('t.dat', 'rb:UTF-16')
f.external_encoding # => #<Encoding:UTF-16 (dummy)>
f.internal_encoding # => nil
f = File.new('t.dat', 'rb:UTF-16:UTF-16')
f.external_encoding # => #<Encoding:UTF-16 (dummy)>
f.internal_encoding # => #<Encoding:UTF-16>
f.close

The numerous encoding names are available in array Encoding.name_list:

Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]

When the external encoding is set, strings read are tagged by that encoding when reading, and strings written are converted to that encoding when writing.

When both external and internal encodings are set, strings read are converted from external to internal encoding, and strings written are converted from internal to external encoding. For further details about transcoding input and output, see Encodings.

If the external encoding is 'BOM|UTF-8', 'BOM|UTF-16LE' or 'BOM|UTF16-BE', Ruby checks for a Unicode BOM in the input document to help determine the encoding. For UTF-16 encodings the file open mode must be binary. If the BOM is found, it is stripped and the external encoding from the BOM is used.

Note that the BOM-style encoding option is case insensitive, so 'bom|utf-8' is also valid.

File Permissions

A File object has permissions, an octal integer representing the permissions of an actual file in the underlying platform.

Note that file permissions are quite different from the mode of a file stream (File object).

In a File object, the permissions are available thus, where method mode, despite its name, returns permissions:

f = File.new('t.txt')
f.lstat.mode.to_s(8) # => "100644"

On a Unix-based operating system, the three low-order octal digits represent the permissions for owner (6), group (4), and world (4). The triplet of bits in each octal digit represent, respectively, read, write, and execute permissions.

Permissions 0644 thus represent read-write access for owner and read-only access for group and world. See man pages open(2) and chmod(2).

For a directory, the meaning of the execute bit changes: when set, the directory can be searched.

Higher-order bits in permissions may indicate the type of file (plain, directory, pipe, socket, etc.) and various other special features.

On non-Posix operating systems, permissions may include only read-only or read-write, in which case, the remaining permission will resemble typical values. On Windows, for instance, the default permissions are 0644; The only change that can be made is to make the file read-only, which is reported as 0444.

For a method that actually creates a file in the underlying platform (as opposed to merely creating a File object), permissions may be specified:

File.new('t.tmp', File::CREAT, 0644)
File.new('t.tmp', File::CREAT, 0444)

Permissions may also be changed:

f = File.new('t.tmp', File::CREAT, 0444)
f.chmod(0644)
f.chmod(0444)

File Constants

Various constants for use in File and IO methods may be found in module File::Constants; an array of their names is returned by File::Constants.constants.

What’s Here

First, what’s elsewhere. Class File:

Inherits from class IO, in particular, methods for creating, reading, and writing files
Includes module FileTest, which provides dozens of additional methods.

Here, class File provides methods that are useful for:

Creating

::new: Opens the file at the given path; returns the file.
::open: Same as ::new, but when given a block will yield the file to the block, and close the file upon exiting the block.
::link: Creates a new name for an existing file using a hard link.
::mkfifo: Returns the FIFO file created at the given path.
::symlink: Creates a symbolic link for the given file path.

Querying

Paths

::absolute_path: Returns the absolute file path for the given path.
::absolute_path?: Returns whether the given path is the absolute file path.
::basename: Returns the last component of the given file path.
::dirname: Returns all but the last component of the given file path.
::expand_path: Returns the absolute file path for the given path, expanding ~ for a home directory.
::extname: Returns the file extension for the given file path.
::fnmatch? (aliased as ::fnmatch): Returns whether the given file path matches the given pattern.
::join: Joins path components into a single path string.
::path: Returns the string representation of the given path.
::readlink: Returns the path to the file at the given symbolic link.
::realdirpath: Returns the real path for the given file path, where the last component need not exist.
::realpath: Returns the real path for the given file path, where all components must exist.
::split: Returns an array of two strings: the directory name and basename of the file at the given path.
path (aliased as to_path): Returns the string representation of the given path.

Times

::atime: Returns a Time for the most recent access to the given file.
::birthtime: Returns a Time for the creation of the given file.
::ctime: Returns a Time for the metadata change of the given file.
::mtime: Returns a Time for the most recent data modification to the content of the given file.
atime: Returns a Time for the most recent access to self.
birthtime: Returns a Time the creation for self.
ctime: Returns a Time for the metadata change of self.
mtime: Returns a Time for the most recent data modification to the content of self.

Types

::blockdev?: Returns whether the file at the given path is a block device.
::chardev?: Returns whether the file at the given path is a character device.
::directory?: Returns whether the file at the given path is a directory.
::executable?: Returns whether the file at the given path is executable by the effective user and group of the current process.
::executable_real?: Returns whether the file at the given path is executable by the real user and group of the current process.
::exist?: Returns whether the file at the given path exists.
::file?: Returns whether the file at the given path is a regular file.
::ftype: Returns a string giving the type of the file at the given path.
::grpowned?: Returns whether the effective group of the current process owns the file at the given path.
::identical?: Returns whether the files at two given paths are identical.
::lstat: Returns the File::Stat object for the last symbolic link in the given path.
::owned?: Returns whether the effective user of the current process owns the file at the given path.
::pipe?: Returns whether the file at the given path is a pipe.
::readable?: Returns whether the file at the given path is readable by the effective user and group of the current process.
::readable_real?: Returns whether the file at the given path is readable by the real user and group of the current process.
::setgid?: Returns whether the setgid bit is set for the file at the given path.
::setuid?: Returns whether the setuid bit is set for the file at the given path.
::socket?: Returns whether the file at the given path is a socket.
::stat: Returns the File::Stat object for the file at the given path.
::sticky?: Returns whether the file at the given path has its sticky bit set.
::symlink?: Returns whether the file at the given path is a symbolic link.
::umask: Returns the umask value for the current process.
::world_readable?: Returns whether the file at the given path is readable by others.
::world_writable?: Returns whether the file at the given path is writable by others.
::writable?: Returns whether the file at the given path is writable by the effective user and group of the current process.
::writable_real?: Returns whether the file at the given path is writable by the real user and group of the current process.
lstat: Returns the File::Stat object for the last symbolic link in the path for self.

Contents

::empty? (aliased as ::zero?): Returns whether the file at the given path exists and is empty.
::size: Returns the size (bytes) of the file at the given path.
::size?: Returns nil if there is no file at the given path, or if that file is empty; otherwise returns the file size (bytes).
size: Returns the size (bytes) of self.

Settings

::chmod: Changes permissions of the file at the given path.
::chown: Change ownership of the file at the given path.
::lchmod: Changes permissions of the last symbolic link in the given path.
::lchown: Change ownership of the last symbolic in the given path.
::lutime: For each given file path, sets the access time and modification time of the last symbolic link in the path.
::rename: Moves the file at one given path to another given path.
::utime: Sets the access time and modification time of each file at the given paths.
flock: Locks or unlocks self.

Other

::truncate: Truncates the file at the given file path to the given size.
::unlink (aliased as ::delete): Deletes the file for each given file path.
truncate: Truncates self to the given size.

NoMethodError

Raised when a method is called on a receiver which doesn’t have it defined and also fails to respond with method_missing.

"hello".to_ary

raises the exception:

NoMethodError: undefined method `to_ary' for an instance of String

NoMemoryError

Raised when memory allocation fails.

SystemCallError

SystemCallError is the base class for all low-level platform-dependent errors.

The errors available on the current platform are subclasses of SystemCallError and are defined in the Errno module.

File.open("does/not/exist")

raises the exception:

Errno::ENOENT: No such file or directory - does/not/exist

Delegator

This library provides three different ways to delegate method calls to an object. The easiest to use is SimpleDelegator. Pass an object to the constructor and all methods supported by the object will be delegated. This object can be changed later.

Going a step further, the top level DelegateClass method allows you to easily setup delegation through class inheritance. This is considerably more flexible and thus probably the most common use for this library.

Finally, if you need full control over the delegation scheme, you can inherit from the abstract class Delegator and customize as needed. (If you find yourself needing this control, have a look at Forwardable which is also in the standard library. It may suit your needs better.)

SimpleDelegator’s implementation serves as a nice example of the use of Delegator:

require 'delegate'

class SimpleDelegator < Delegator
  def __getobj__
    @delegate_sd_obj # return object we are delegating to, required
  end

  def __setobj__(obj)
    @delegate_sd_obj = obj # change delegation object,
                           # a feature we're providing
  end
end

Notes

Be advised, RDoc will not detect delegated methods.

Tempfile

A utility class for managing temporary files.

There are two kind of methods of creating a temporary file:

Tempfile.create (recommended)
Tempfile.new and Tempfile.open (mostly for backward compatibility, not recommended)

Tempfile.create creates a usual File object. The timing of file deletion is predictable. Also, it supports open-and-unlink technique which removes the temporary file immediately after creation.

Tempfile.new and Tempfile.open creates a Tempfile object. The created file is removed by the GC (finalizer). The timing of file deletion is not predictable.

Synopsis

require 'tempfile'

# Tempfile.create with a block
# The filename are choosen automatically.
# (You can specify the prefix and suffix of the filename by an optional argument.)
Tempfile.create {|f|
  f.puts "foo"
  f.rewind
  f.read                # => "foo\n"
}                       # The file is removed at block exit.

# Tempfile.create without a block
# You need to unlink the file in non-block form.
f = Tempfile.create
f.puts "foo"
f.close
File.unlink(f.path)     # You need to unlink the file.

# Tempfile.create(anonymous: true) without a block
f = Tempfile.create(anonymous: true)
# The file is already removed because anonymous.
f.path                  # => "/tmp/"  (no filename since no file)
f.puts "foo"
f.rewind
f.read                  # => "foo\n"
f.close

# Tempfile.create(anonymous: true) with a block
Tempfile.create(anonymous: true) {|f|
  # The file is already removed because anonymous.
  f.path                # => "/tmp/"  (no filename since no file)
  f.puts "foo"
  f.rewind
  f.read                # => "foo\n"
}

# Not recommended: Tempfile.new without a block
file = Tempfile.new('foo')
file.path      # => A unique filename in the OS's temp directory,
               #    e.g.: "/tmp/foo.24722.0"
               #    This filename contains 'foo' in its basename.
file.write("hello world")
file.rewind
file.read      # => "hello world"
file.close
file.unlink    # deletes the temp file

About `Tempfile.new` and `Tempfile.open`

This section does not apply to Tempfile.create because it returns a File object (not a Tempfile object).

When you create a Tempfile object, it will create a temporary file with a unique filename. A Tempfile objects behaves just like a File object, and you can perform all the usual file operations on it: reading data, writing data, changing its permissions, etc. So although this class does not explicitly document all instance methods supported by File, you can in fact call any File instance method on a Tempfile object.

A Tempfile object has a finalizer to remove the temporary file. This means that the temporary file is removed via GC. This can cause several problems:

Long GC intervals and conservative GC can accumulate temporary files that are not removed.
Temporary files are not removed if Ruby exits abnormally (such as SIGKILL, SEGV).

There are legacy good practices for Tempfile.new and Tempfile.open as follows.

Explicit close

When a Tempfile object is garbage collected, or when the Ruby interpreter exits, its associated temporary file is automatically deleted. This means that it’s unnecessary to explicitly delete a Tempfile after use, though it’s a good practice to do so: not explicitly deleting unused Tempfiles can potentially leave behind a large number of temp files on the filesystem until they’re garbage collected. The existence of these temp files can make it harder to determine a new Tempfile filename.

Therefore, one should always call unlink or close in an ensure block, like this:

file = Tempfile.new('foo')
begin
   # ...do something with file...
ensure
   file.close
   file.unlink   # deletes the temp file
end

Tempfile.create { … } exists for this purpose and is more convenient to use. Note that Tempfile.create returns a File instance instead of a Tempfile, which also avoids the overhead and complications of delegation.

Tempfile.create('foo') do |file|
   # ...do something with file...
end

Unlink after creation

On POSIX systems, it’s possible to unlink a file right after creating it, and before closing it. This removes the filesystem entry without closing the file handle, so it ensures that only the processes that already had the file handle open can access the file’s contents. It’s strongly recommended that you do this if you do not want any other processes to be able to read from or write to the Tempfile, and you do not need to know the Tempfile’s filename either.

Also, this guarantees the temporary file is removed even if Ruby exits abnormally. The OS reclaims the storage for the temporary file when the file is closed or the Ruby process exits (normally or abnormally).

For example, a practical use case for unlink-after-creation would be this: you need a large byte buffer that’s too large to comfortably fit in RAM, e.g. when you’re writing a web server and you want to buffer the client’s file upload data.

‘Tempfile.create(anonymous: true)` supports this behavior. It also works on Windows.

Minor notes

Tempfile’s filename picking method is both thread-safe and inter-process-safe: it guarantees that no other threads or processes will pick the same filename.

Tempfile itself however may not be entirely thread-safe. If you access the same Tempfile object from multiple threads then you should protect it with a mutex.

Method

Method objects are created by Object#method, and are associated with a particular object (not just with a class). They may be used to invoke the method within the object, and as a block associated with an iterator. They may also be unbound from one object (creating an UnboundMethod) and bound to another.

class Thing
  def square(n)
    n*n
  end
end
thing = Thing.new
meth  = thing.method(:square)

meth.call(9)                 #=> 81
[ 1, 2, 3 ].collect(&meth)   #=> [1, 4, 9]

[ 1, 2, 3 ].each(&method(:puts)) #=> prints 1, 2, 3

require 'date'
%w[2017-03-01 2017-03-02].collect(&Date.method(:parse))
#=> [#<Date: 2017-03-01 ((2457814j,0s,0n),+0s,2299161j)>, #<Date: 2017-03-02 ((2457815j,0s,0n),+0s,2299161j)>]

Comparable

The Comparable mixin is used by classes whose objects may be ordered. The class must define the <=> operator, which compares the receiver against another object, returning a value less than 0, returning 0, or returning a value greater than 0, depending on whether the receiver is less than, equal to, or greater than the other object. If the other object is not comparable then the <=> operator should return nil. Comparable uses <=> to implement the conventional comparison operators (<, <=, ==, >=, and >) and the method between?.

class StringSorter
  include Comparable

  attr :str
  def <=>(other)
    str.size <=> other.str.size
  end

  def initialize(str)
    @str = str
  end

  def inspect
    @str
  end
end

s1 = StringSorter.new("Z")
s2 = StringSorter.new("YY")
s3 = StringSorter.new("XXX")
s4 = StringSorter.new("WWWW")
s5 = StringSorter.new("VVVVV")

s1 < s2                       #=> true
s4.between?(s1, s3)           #=> false
s4.between?(s3, s5)           #=> true
[ s3, s2, s5, s4, s1 ].sort   #=> [Z, YY, XXX, WWWW, VVVVV]

What’s Here

Module Comparable provides these methods, all of which use method #<=>:

<: Returns whether self is less than the given object.
<=: Returns whether self is less than or equal to the given object.
==: Returns whether self is equal to the given object.
>: Returns whether self is greater than the given object.
>=: Returns whether self is greater than or equal to the given object.
between?: Returns true if self is between two given objects.
clamp: For given objects min and max, or range (min..max), returns:
- min if (self <=> min) < 0.
- max if (self <=> max) > 0.
- self otherwise.

Enumerable

What’s Here

Module Enumerable provides methods that are useful to a collection class for:

Methods for Querying

These methods return information about the Enumerable other than the elements themselves:

member? (aliased as include?): Returns true if self == object, false otherwise.
all?: Returns true if all elements meet a specified criterion; false otherwise.
any?: Returns true if any element meets a specified criterion; false otherwise.
none?: Returns true if no element meets a specified criterion; false otherwise.
one?: Returns true if exactly one element meets a specified criterion; false otherwise.
count: Returns the count of elements, based on an argument or block criterion, if given.
tally: Returns a new Hash containing the counts of occurrences of each element.

Methods for Fetching

These methods return entries from the Enumerable, without modifying it:

Leading, trailing, or all elements:

to_a (aliased as entries): Returns all elements.
first: Returns the first element or leading elements.
take: Returns a specified number of leading elements.
drop: Returns a specified number of trailing elements.
take_while: Returns leading elements as specified by the given block.
drop_while: Returns trailing elements as specified by the given block.

Minimum and maximum value elements:

min: Returns the elements whose values are smallest among the elements, as determined by #<=> or a given block.
max: Returns the elements whose values are largest among the elements, as determined by #<=> or a given block.
minmax: Returns a 2-element Array containing the smallest and largest elements.
min_by: Returns the smallest element, as determined by the given block.
max_by: Returns the largest element, as determined by the given block.
minmax_by: Returns the smallest and largest elements, as determined by the given block.

Groups, slices, and partitions:

group_by: Returns a Hash that partitions the elements into groups.
partition: Returns elements partitioned into two new Arrays, as determined by the given block.
slice_after: Returns a new Enumerator whose entries are a partition of self, based either on a given object or a given block.
slice_before: Returns a new Enumerator whose entries are a partition of self, based either on a given object or a given block.
slice_when: Returns a new Enumerator whose entries are a partition of self based on the given block.
chunk: Returns elements organized into chunks as specified by the given block.
chunk_while: Returns elements organized into chunks as specified by the given block.

Methods for Searching and Filtering

These methods return elements that meet a specified criterion:

find (aliased as detect): Returns an element selected by the block.
find_all (aliased as filter, select): Returns elements selected by the block.
find_index: Returns the index of an element selected by a given object or block.
reject: Returns elements not rejected by the block.
uniq: Returns elements that are not duplicates.

Methods for Sorting

These methods return elements in sorted order:

sort: Returns the elements, sorted by #<=> or the given block.
sort_by: Returns the elements, sorted by the given block.

Methods for Iterating

each_entry: Calls the block with each successive element (slightly different from each).
each_with_index: Calls the block with each successive element and its index.
each_with_object: Calls the block with each successive element and a given object.
each_slice: Calls the block with successive non-overlapping slices.
each_cons: Calls the block with successive overlapping slices. (different from each_slice).
reverse_each: Calls the block with each successive element, in reverse order.

Other Methods

collect (aliased as map): Returns objects returned by the block.
filter_map: Returns truthy objects returned by the block.
flat_map (aliased as collect_concat): Returns flattened objects returned by the block.
grep: Returns elements selected by a given object or objects returned by a given block.
grep_v: Returns elements not selected by a given object or objects returned by a given block.
inject (aliased as reduce): Returns the object formed by combining all elements.
sum: Returns the sum of the elements, using method +.
zip: Combines each element with elements from other enumerables; returns the n-tuples or calls the block with each.
cycle: Calls the block with each element, cycling repeatedly.

Usage

To use module Enumerable in a collection class:

Include it:
```
include Enumerable
```
Implement method #each which must yield successive elements of the collection. The method will be called by almost any Enumerable method.

Example:

class Foo
  include Enumerable
  def each
    yield 1
    yield 1, 2
    yield
  end
end
Foo.new.each_entry{ |element| p element }

Output:

1
[1, 2]
nil

Enumerable in `Ruby` Classes

These Ruby core classes include (or extend) Enumerable:

These Ruby standard library classes include Enumerable:

CSV
CSV::Table
CSV::Row
Set

Virtually all methods in Enumerable call method #each in the including class:

Hash#each yields the next key-value pair as a 2-element Array.
Struct#each yields the next name-value pair as a 2-element Array.
For the other classes above, #each yields the next object from the collection.

About the Examples

The example code snippets for the Enumerable methods:

Always show the use of one or more Array-like classes (often Array itself).
Sometimes show the use of a Hash-like class. For some methods, though, the usage would not make sense, and so it is not shown. Example: tally would find exactly one of each Hash entry.

FileTest

FileTest implements file test operations similar to those used in File::Stat. It exists as a standalone module, and its methods are also insinuated into the File class. (Note that this is not done by inclusion: the interpreter cheats).

Forwardable

The Forwardable module provides delegation of specified methods to a designated object, using the methods def_delegator and def_delegators.

For example, say you have a class RecordCollection which contains an array @records. You could provide the lookup method record_number(), which simply calls [] on the @records array, like this:

require 'forwardable'

class RecordCollection
  attr_accessor :records
  extend Forwardable
  def_delegator :@records, :[], :record_number
end

We can use the lookup method like so:

r = RecordCollection.new
r.records = [4,5,6]
r.record_number(0)  # => 4

Further, if you wish to provide the methods size, <<, and map, all of which delegate to @records, this is how you can do it:

class RecordCollection # re-open RecordCollection class
  def_delegators :@records, :size, :<<, :map
end

r = RecordCollection.new
r.records = [1,2,3]
r.record_number(0)   # => 1
r.size               # => 3
r << 4               # => [1, 2, 3, 4]
r.map { |x| x * 2 }  # => [2, 4, 6, 8]

You can even extend regular objects with Forwardable.

my_hash = Hash.new
my_hash.extend Forwardable              # prepare object for delegation
my_hash.def_delegator "STDOUT", "puts"  # add delegation for STDOUT.puts()
my_hash.puts "Howdy!"

Another example

You could use Forwardable as an alternative to inheritance, when you don’t want to inherit all methods from the superclass. For instance, here is how you might add a range of Array instance methods to a new class Queue:

class Queue
  extend Forwardable

  def initialize
    @q = [ ]    # prepare delegate object
  end

  # setup preferred interface, enq() and deq()...
  def_delegator :@q, :push, :enq
  def_delegator :@q, :shift, :deq

  # support some general Array methods that fit Queues well
  def_delegators :@q, :clear, :first, :push, :shift, :size
end

q = Thread::Queue.new
q.enq 1, 2, 3, 4, 5
q.push 6

q.shift    # => 1
while q.size > 0
  puts q.deq
end

q.enq "Ruby", "Perl", "Python"
puts q.first
q.clear
puts q.first

This should output:

2
3
4
5
6
Ruby
nil

Notes

Be advised, RDoc will not detect delegated methods.

forwardable.rb provides single-method delegation via the def_delegator and def_delegators methods. For full-class delegation via DelegateClass, see delegate.rb.

MakeMakefile

mkmf.rb is used by Ruby C extensions to generate a Makefile which will correctly compile and link the C extension to Ruby and a third-party library.

Enumerator::ArithmeticSequence

Enumerator::ArithmeticSequence is a subclass of Enumerator, that is a representation of sequences of numbers with common difference. Instances of this class can be generated by the Range#step and Numeric#step methods.

The class can be used for slicing Array (see Array#slice) or custom collections.

Zlib::VersionError

Subclass of Zlib::Error

When zlib returns a Z_VERSION_ERROR, usually if the zlib library version is incompatible with the version assumed by the caller.

CGI::Session

Overview

This file provides the CGI::Session class, which provides session support for CGI scripts. A session is a sequence of HTTP requests and responses linked together and associated with a single client. Information associated with the session is stored on the server between requests. A session id is passed between client and server with every request and response, transparently to the user. This adds state information to the otherwise stateless HTTP request/response protocol.

Lifecycle

A CGI::Session instance is created from a CGI object. By default, this CGI::Session instance will start a new session if none currently exists, or continue the current session for this client if one does exist. The new_session option can be used to either always or never create a new session. See new() for more details.

delete() deletes a session from session storage. It does not however remove the session id from the client. If the client makes another request with the same id, the effect will be to start a new session with the old session’s id.

Setting and retrieving session data.

The Session class associates data with a session as key-value pairs. This data can be set and retrieved by indexing the Session instance using ‘[]’, much the same as hashes (although other hash methods are not supported).

When session processing has been completed for a request, the session should be closed using the close() method. This will store the session’s state to persistent storage. If you want to store the session’s state to persistent storage without finishing session processing for this request, call the update() method.

Storing session state

The caller can specify what form of storage to use for the session’s data with the database_manager option to CGI::Session::new. The following storage classes are provided as part of the standard library:

CGI::Session::FileStore: stores data as plain text in a flat file. Only works with String data. This is the default storage type.
CGI::Session::MemoryStore: stores data in an in-memory hash. The data only persists for as long as the current Ruby interpreter instance does.
CGI::Session::PStore: stores data in Marshalled format. Provided by cgi/session/pstore.rb. Supports data of any type, and provides file-locking and transaction support.

Custom storage types can also be created by defining a class with the following methods:

new(session, options)
restore  # returns hash of session data.
update
close
delete

Changing storage type mid-session does not work. Note in particular that by default the FileStore and PStore session data files have the same name. If your application switches from one to the other without making sure that filenames will be different and clients still have old sessions lying around in cookies, then things will break nastily!

Maintaining the session id.

Most session state is maintained on the server. However, a session id must be passed backwards and forwards between client and server to maintain a reference to this session state.

The simplest way to do this is via cookies. The CGI::Session class provides transparent support for session id communication via cookies if the client has cookies enabled.

If the client has cookies disabled, the session id must be included as a parameter of all requests sent by the client to the server. The CGI::Session class in conjunction with the CGI class will transparently add the session id as a hidden input field to all forms generated using the CGI#form() HTML generation method. No built-in support is provided for other mechanisms, such as URL re-writing. The caller is responsible for extracting the session id from the session_id attribute and manually encoding it in URLs and adding it as a hidden input to HTML forms created by other mechanisms. Also, session expiry is not automatically handled.

Examples of use

Setting the user’s name

require 'cgi'
require 'cgi/session'
require 'cgi/session/pstore'     # provides CGI::Session::PStore

cgi = CGI.new("html4")

session = CGI::Session.new(cgi,
    'database_manager' => CGI::Session::PStore,  # use PStore
    'session_key' => '_rb_sess_id',              # custom session key
    'session_expires' => Time.now + 30 * 60,     # 30 minute timeout
    'prefix' => 'pstore_sid_')                   # PStore option
if cgi.has_key?('user_name') and cgi['user_name'] != ''
    # coerce to String: cgi[] returns the
    # string-like CGI::QueryExtension::Value
    session['user_name'] = cgi['user_name'].to_s
elsif !session['user_name']
    session['user_name'] = "guest"
end
session.close

Creating a new session safely

require 'cgi'
require 'cgi/session'

cgi = CGI.new("html4")

# We make sure to delete an old session if one exists,
# not just to free resources, but to prevent the session
# from being maliciously hijacked later on.
begin
    session = CGI::Session.new(cgi, 'new_session' => false)
    session.delete
rescue ArgumentError  # if no old session
end
session = CGI::Session.new(cgi, 'new_session' => true)
session.close

Previous Next

… 8 9 10 11 12 13 14 …

Search took: 14ms · Total Results: 3346

Results for: "module_function"

Rectangular Coordinates

Polar Coordinates

What’s Here

Creating Complex Objects

Querying

Comparing

Converting

Performing Complex Arithmetic

Working with JSON

About the Examples

Access Modes

String Access Modes

Read/Write Mode

Read/Write Modes for Existing File

Read/Write Modes for File To Be Created

Data Mode

File-Create Mode

Integer Access Modes

File-Create Mode Specified as an Integer

Data Mode Specified as an Integer

Encodings

File Permissions

File Constants

What’s Here

Creating

Querying

Settings

Other

Notes

Synopsis

About Tempfile.new and Tempfile.open

Explicit close

Unlink after creation

Minor notes

What’s Here

What’s Here

Methods for Querying

Methods for Fetching

Methods for Searching and Filtering

Methods for Sorting

Methods for Iterating

Other Methods

Usage

Enumerable in Ruby Classes

About the Examples

Another example

Notes

Overview

Lifecycle

Setting and retrieving session data.

Storing session state

Maintaining the session id.

Examples of use

Setting the user’s name

Creating a new session safely

Performing `Complex` Arithmetic

Working with `JSON`

About `Tempfile.new` and `Tempfile.open`

Enumerable in `Ruby` Classes