exception to wait for reading by EWOULDBLOCK. see IO.select.
exception to wait for writing by EWOULDBLOCK. see IO.select.
Response class for Not Modified responses (status code 304).
Indicates that the resource has not been modified since the version specified by the request headers. See 304 Not Modified.
A complex number can be represented as a paired real number with imaginary unit; a+bi. Where a is real part, b is imaginary part and i is imaginary unit. Real a equals complex a+0i mathematically.
You can create a Complex object explicitly with:
A complex literal.
You can convert certain objects to Complex objects with:
Method Complex.
Complex object can be created as literal, and also by using Kernel#Complex, Complex::rect, Complex::polar or to_c method.
2+1i #=> (2+1i) Complex(1) #=> (1+0i) Complex(2, 3) #=> (2+3i) Complex.polar(2, 3) #=> (-1.9799849932008908+0.2822400161197344i) 3.to_c #=> (3+0i)
You can also create complex object from floating-point numbers or strings.
Complex(0.3) #=> (0.3+0i) Complex('0.3-0.5i') #=> (0.3-0.5i) Complex('2/3+3/4i') #=> ((2/3)+(3/4)*i) Complex('1@2') #=> (-0.4161468365471424+0.9092974268256817i) 0.3.to_c #=> (0.3+0i) '0.3-0.5i'.to_c #=> (0.3-0.5i) '2/3+3/4i'.to_c #=> ((2/3)+(3/4)*i) '1@2'.to_c #=> (-0.4161468365471424+0.9092974268256817i)
A complex object is either an exact or an inexact number.
Complex(1, 1) / 2 #=> ((1/2)+(1/2)*i) Complex(1, 1) / 2.0 #=> (0.5+0.5i)
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?.
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
Methods File.new and File.open each create a File object for a given file path.
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.
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.
'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"
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 # => ""
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.
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.
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.
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 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.
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.
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). See Modes at IO.
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)
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.
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:
::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.
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.
::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.
::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.
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 "hello":String
Raised when memory allocation fails.
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
WIN32OLE objects represent OLE Automation object in Ruby.
By using WIN32OLE, you can access OLE server like VBScript.
Here is sample script.
require 'win32ole' excel = WIN32OLE.new('Excel.Application') excel.visible = true workbook = excel.Workbooks.Add(); worksheet = workbook.Worksheets(1); worksheet.Range("A1:D1").value = ["North","South","East","West"]; worksheet.Range("A2:B2").value = [5.2, 10]; worksheet.Range("C2").value = 8; worksheet.Range("D2").value = 20; range = worksheet.Range("A1:D2"); range.select chart = workbook.Charts.Add; workbook.saved = true; excel.ActiveWorkbook.Close(0); excel.Quit();
Unfortunately, Win32OLE doesn’t support the argument passed by reference directly. Instead, Win32OLE provides WIN32OLE::ARGV or WIN32OLE_VARIANT object. If you want to get the result value of argument passed by reference, you can use WIN32OLE::ARGV or WIN32OLE_VARIANT.
oleobj.method(arg1, arg2, refargv3) puts WIN32OLE::ARGV[2] # the value of refargv3 after called oleobj.method
or
refargv3 = WIN32OLE_VARIANT.new(XXX, WIN32OLE::VARIANT::VT_BYREF|WIN32OLE::VARIANT::VT_XXX) oleobj.method(arg1, arg2, refargv3) p refargv3.value # the value of refargv3 after called oleobj.method.
OLEProperty helper class of Property with arguments.
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
Be advised, RDoc will not detect delegated methods.
A utility class for managing temporary files. 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.
require 'tempfile' 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
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.open('foo') do |file| # ...do something with file... end
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.
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.
Please refer to unlink for more information and a code example.
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 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)>]
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 SizeMatters include Comparable attr :str def <=>(other) str.size <=> other.str.size end def initialize(str) @str = str end def inspect @str end end s1 = SizeMatters.new("Z") s2 = SizeMatters.new("YY") s3 = SizeMatters.new("XXX") s4 = SizeMatters.new("WWWW") s5 = SizeMatters.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]
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 or equal to the given object.
>=: Returns whether self is greater than 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.
Module Enumerable provides methods that are useful to a collection class for:
These methods return information about the Enumerable other than the elements themselves:
include?, member?: 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.
These methods return entries from the Enumerable, without modifying it:
Leading, trailing, or 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.
These methods return elements that meet a specified criterion:
find_all, 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.
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.
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.
filter_map: Returns truthy objects returned by the block.
flat_map, 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 selected by a given object or objects returned by a given block.
reduce, inject: 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.
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
These Ruby core classes include (or extend) Enumerable:
These Ruby standard library classes include Enumerable:
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.
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.
A libffi wrapper for Ruby.
Fiddle is an extension to translate a foreign function interface (FFI) with ruby.
It wraps libffi, a popular C library which provides a portable interface that allows code written in one language to call code written in another language.
Here we will use Fiddle::Function to wrap floor(3) from libm
require 'fiddle' libm = Fiddle.dlopen('/lib/libm.so.6') floor = Fiddle::Function.new( libm['floor'], [Fiddle::TYPE_DOUBLE], Fiddle::TYPE_DOUBLE ) puts floor.call(3.14159) #=> 3.0
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).
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!"
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
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.
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.
The Observer pattern (also known as publish/subscribe) provides a simple mechanism for one object to inform a set of interested third-party objects when its state changes.
The notifying class mixes in the Observable module, which provides the methods for managing the associated observer objects.
The observable object must:
assert that it has #changed
call #notify_observers
An observer subscribes to updates using Observable#add_observer, which also specifies the method called via notify_observers. The default method for notify_observers is update.
The following example demonstrates this nicely. A Ticker, when run, continually receives the stock Price for its @symbol. A Warner is a general observer of the price, and two warners are demonstrated, a WarnLow and a WarnHigh, which print a warning if the price is below or above their set limits, respectively.
The update callback allows the warners to run without being explicitly called. The system is set up with the Ticker and several observers, and the observers do their duty without the top-level code having to interfere.
Note that the contract between publisher and subscriber (observable and observer) is not declared or enforced. The Ticker publishes a time and a price, and the warners receive that. But if you don’t ensure that your contracts are correct, nothing else can warn you.
require "observer" class Ticker ### Periodically fetch a stock price. include Observable def initialize(symbol) @symbol = symbol end def run last_price = nil loop do price = Price.fetch(@symbol) print "Current price: #{price}\n" if price != last_price changed # notify observers last_price = price notify_observers(Time.now, price) end sleep 1 end end end class Price ### A mock class to fetch a stock price (60 - 140). def self.fetch(symbol) 60 + rand(80) end end class Warner ### An abstract observer of Ticker objects. def initialize(ticker, limit) @limit = limit ticker.add_observer(self) end end class WarnLow < Warner def update(time, price) # callback for observer if price < @limit print "--- #{time.to_s}: Price below #@limit: #{price}\n" end end end class WarnHigh < Warner def update(time, price) # callback for observer if price > @limit print "+++ #{time.to_s}: Price above #@limit: #{price}\n" end end end ticker = Ticker.new("MSFT") WarnLow.new(ticker, 80) WarnHigh.new(ticker, 120) ticker.run
Produces:
Current price: 83 Current price: 75 --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 75 Current price: 90 Current price: 134 +++ Sun Jun 09 00:10:25 CDT 2002: Price above 120: 134 Current price: 134 Current price: 112 Current price: 79 --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 79
The #notify_observers method can also be used with +proc+s by using the :call as func parameter.
The following example illustrates the use of a lambda:
require 'observer' class Ticker include Observable def run # logic to retrieve the price (here 77.0) changed notify_observers(77.0) end end ticker = Ticker.new warner = ->(price) { puts "New price received: #{price}" } ticker.add_observer(warner, :call) ticker.run
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.