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:
entries, to_a
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.
These methods return elements that meet a specified criterion.
find, detect
Returns an element selected by the block.
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.
map, collect
Returns objects returned by the block.
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
Some Ruby 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.
A pointer to a C structure
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.
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.
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.
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.
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!
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.
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
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
Timer id conversion keeps objects alive for a certain amount of time after their last access. The default time period is 600 seconds and can be changed upon initialization.
To use TimerIdConv:
DRb.install_id_conv TimerIdConv.new 60 # one minute