A StringIO duck-typed class that uses Tempfile instead of String as the backing store.
This is available when rubygems/test_utilities is required.
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’s it’s unnecessary to explicitly delete a Tempfile after use, though it’s good practice to do so: not explicitly deleting unused Tempfiles can potentially leave behind large amounts of tempfiles 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
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.
Weak Reference class that allows a referenced object to be garbage-collected.
A WeakRef may be used exactly like the object it references.
Usage:
foo = Object.new # create a new object instance p foo.to_s # original's class foo = WeakRef.new(foo) # reassign foo with WeakRef instance p foo.to_s # should be same class GC.start # start the garbage collector p foo.to_s # should raise exception (recycled)
With help from WeakRef, we can implement our own rudimentary WeakHash class.
We will call it WeakHash, since it’s really just a Hash except all of it’s keys and values can be garbage collected.
require 'weakref' class WeakHash < Hash def []= key, obj super WeakRef.new(key), WeakRef.new(obj) end end
This is just a simple implementation, we’ve opened the Hash class and changed Hash#store to create a new WeakRef object with key and obj parameters before passing them as our key-value pair to the hash.
With this you will have to limit your self to String keys, otherwise you will get an ArgumentError because WeakRef cannot create a finalizer for a Symbol. Symbols are immutable and cannot be garbage collected.
Let’s see it in action:
omg = "lol" c = WeakHash.new c['foo'] = "bar" c['baz'] = Object.new c['qux'] = omg puts c.inspect #=> {"foo"=>"bar", "baz"=>#<Object:0x007f4ddfc6cb48>, "qux"=>"lol"} # Now run the garbage collector GC.start c['foo'] #=> nil c['baz'] #=> nil c['qux'] #=> nil omg #=> "lol" puts c.inspect #=> WeakRef::RefError: Invalid Reference - probably recycled
You can see the local variable omg stayed, although its reference in our hash object was garbage collected, along with the rest of the keys and values. Also, when we tried to inspect our hash, we got a WeakRef::RefError. This is because these objects were also garbage collected.
Threads are the Ruby implementation for a concurrent programming model.
Programs that require multiple threads of execution are a perfect candidate for Ruby’s Thread class.
For example, we can create a new thread separate from the main thread’s execution using ::new.
thr = Thread.new { puts "Whats the big deal" }
Then we are able to pause the execution of the main thread and allow our new thread to finish, using join:
thr.join #=> "Whats the big deal"
If we don’t call thr.join before the main thread terminates, then all other threads including thr will be killed.
Alternatively, you can use an array for handling multiple threads at once, like in the following example:
threads = [] threads << Thread.new { puts "Whats the big deal" } threads << Thread.new { 3.times { puts "Threads are fun!" } }
After creating a few threads we wait for them all to finish consecutively.
threads.each { |thr| thr.join }
Thread initialization In order to create new threads, Ruby provides ::new, ::start, and ::fork. A block must be provided with each of these methods, otherwise a ThreadError will be raised.
When subclassing the Thread class, the initialize method of your subclass will be ignored by ::start and ::fork. Otherwise, be sure to call super in your initialize method.
Thread termination For terminating threads, Ruby provides a variety of ways to do this.
The class method ::kill, is meant to exit a given thread:
thr = Thread.new { ... }
Thread.kill(thr) # sends exit() to thr
Alternatively, you can use the instance method exit, or any of its aliases kill or terminate.
thr.exit
Thread status Ruby provides a few instance methods for querying the state of a given thread. To get a string with the current thread’s state use status
thr = Thread.new { sleep } thr.status # => "sleep" thr.exit thr.status # => false
You can also use alive? to tell if the thread is running or sleeping, and stop? if the thread is dead or sleeping.
Thread variables and scope Since threads are created with blocks, the same rules apply to other Ruby blocks for variable scope. Any local variables created within this block are accessible to only this thread.
Each fiber has its own bucket for Thread#[] storage. When you set a new fiber-local it is only accessible within this Fiber. To illustrate:
Thread.new { Thread.current[:foo] = "bar" Fiber.new { p Thread.current[:foo] # => nil }.resume }.join
This example uses [] for getting and []= for setting fiber-locals, you can also use keys to list the fiber-locals for a given thread and key? to check if a fiber-local exists.
When it comes to thread-locals, they are accessible within the entire scope of the thread. Given the following example:
Thread.new{ Thread.current.thread_variable_set(:foo, 1) p Thread.current.thread_variable_get(:foo) # => 1 Fiber.new{ Thread.current.thread_variable_set(:foo, 2) p Thread.current.thread_variable_get(:foo) # => 2 }.resume p Thread.current.thread_variable_get(:foo) # => 2 }.join
You can see that the thread-local :foo carried over into the fiber and was changed to 2 by the end of the thread.
This example makes use of thread_variable_set to create new thread-locals, and thread_variable_get to reference them.
There is also thread_variables to list all thread-locals, and thread_variable? to check if a given thread-local exists.
Exception handling Any thread can raise an exception using the raise instance method, which operates similarly to Kernel#raise.
However, it’s important to note that an exception that occurs in any thread except the main thread depends on abort_on_exception. This option is false by default, meaning that any unhandled exception will cause the thread to terminate silently when waited on by either join or value. You can change this default by either abort_on_exception= true or setting $DEBUG to true.
With the addition of the class method ::handle_interrupt, you can now handle exceptions asynchronously with threads.
Ruby provides a few ways to support scheduling threads in your program.
The first way is by using the class method ::stop, to put the current running thread to sleep and schedule the execution of another thread.
Once a thread is asleep, you can use the instance method wakeup to mark your thread as eligible for scheduling.
You can also try ::pass, which attempts to pass execution to another thread but is dependent on the OS whether a running thread will switch or not. The same goes for priority, which lets you hint to the thread scheduler which threads you want to take precedence when passing execution. This method is also dependent on the OS and may be ignored on some platforms.
Raised when given an invalid regexp expression.
Regexp.new("?")
raises the exception:
RegexpError: target of repeat operator is not specified: /?/
ThreadGroup provides a means of keeping track of a number of threads as a group.
A given Thread object can only belong to one ThreadGroup at a time; adding a thread to a new group will remove it from any previous group.
Newly created threads belong to the same group as the thread from which they were created.
Raised when an invalid operation is attempted on a thread.
For example, when no other thread has been started:
Thread.stop
This will raises the following exception:
ThreadError: stopping only thread note: use sleep to stop forever
Solves a*x = b for x, using LU decomposition.
The Readline module provides interface for GNU Readline. This module defines a number of methods to facilitate completion and accesses input history from the Ruby interpreter. This module supported Edit Line(libedit) too. libedit is compatible with GNU Readline.
Reads one inputted line with line edit by Readline.readline method. At this time, the facilitatation completion and the key bind like Emacs can be operated like GNU Readline.
require "readline" while buf = Readline.readline("> ", true) p buf end
The content that the user input can be recorded to the history. The history can be accessed by Readline::HISTORY constant.
require "readline" while buf = Readline.readline("> ", true) p Readline::HISTORY.to_a print("-> ", buf, "\n") end
Documented by Kouji Takao <kouji dot takao at gmail dot com>.
Calculates the set of unambiguous abbreviations for a given set of strings.
require 'abbrev' require 'pp' pp Abbrev.abbrev(['ruby']) #=> {"ruby"=>"ruby", "rub"=>"ruby", "ru"=>"ruby", "r"=>"ruby"} pp Abbrev.abbrev(%w{ ruby rules })
Generates:
{ "ruby" => "ruby",
"rub" => "ruby",
"rules" => "rules",
"rule" => "rules",
"rul" => "rules" }
It also provides an array core extension, Array#abbrev.
pp %w{ summer winter }.abbrev
Generates:
{ "summer" => "summer",
"summe" => "summer",
"summ" => "summer",
"sum" => "summer",
"su" => "summer",
"s" => "summer",
"winter" => "winter",
"winte" => "winter",
"wint" => "winter",
"win" => "winter",
"wi" => "winter",
"w" => "winter" }
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.
a = Node.new a << “B” # => <a>B</a> a.b # => <a>B<b/></a> a.b # => <a>B<b/><b/><a> a.b[“x”] = “y” # => <a>B<b/><b x=“y”/></a> a.b.c # => <a>B<c/><b x=“y”/></a> a.b.c << “D” # => <a>B<c>D</c><b x=“y”/></a>
REXML is an XML toolkit for Ruby, in Ruby.
REXML is a pure Ruby, XML 1.0 conforming, non-validating toolkit with an intuitive API. REXML passes 100% of the non-validating Oasis tests, and provides tree, stream, SAX2, pull, and lightweight APIs. REXML also includes a full XPath 1.0 implementation. Since Ruby 1.8, REXML is included in the standard Ruby distribution.
This API documentation can be downloaded from the REXML home page, or can be accessed online
A tutorial is available in the REXML distribution in docs/tutorial.html, or can be accessed online
RubyGems is the Ruby standard for publishing and managing third party libraries.
For user documentation, see:
gem help and gem help [command]
For gem developer documentation see:
Gem::Version for version dependency notes
Further RubyGems documentation can be found at:
RubyGems API (also available from gem server)
As of RubyGems 1.3.2, RubyGems will load plugins installed in gems or $LOAD_PATH. Plugins must be named ‘rubygems_plugin’ (.rb, .so, etc) and placed at the root of your gem’s require_path. Plugins are discovered via Gem::find_files then loaded. Take care when implementing a plugin as your plugin file may be loaded multiple times if multiple versions of your gem are installed.
For an example plugin, see the graph gem which adds a ‘gem graph` command.
RubyGems defaults are stored in rubygems/defaults.rb. If you’re packaging RubyGems or implementing Ruby you can change RubyGems’ defaults.
For RubyGems packagers, provide lib/rubygems/defaults/operating_system.rb and override any defaults from lib/rubygems/defaults.rb.
For Ruby implementers, provide lib/rubygems/defaults/#{RUBY_ENGINE}.rb and override any defaults from lib/rubygems/defaults.rb.
If you need RubyGems to perform extra work on install or uninstall, your defaults override file can set pre and post install and uninstall hooks. See Gem::pre_install, Gem::pre_uninstall, Gem::post_install, Gem::post_uninstall.
You can submit bugs to the RubyGems bug tracker on GitHub
RubyGems is currently maintained by Eric Hodel.
RubyGems was originally developed at RubyConf 2003 by:
Rich Kilmer – rich(at)infoether.com
Chad Fowler – chad(at)chadfowler.com
David Black – dblack(at)wobblini.net
Paul Brannan – paul(at)atdesk.com
Jim Weirich – jim(at)weirichhouse.org
Contributors:
Gavin Sinclair – gsinclair(at)soyabean.com.au
George Marrows – george.marrows(at)ntlworld.com
Dick Davies – rasputnik(at)hellooperator.net
Mauricio Fernandez – batsman.geo(at)yahoo.com
Simon Strandgaard – neoneye(at)adslhome.dk
Dave Glasser – glasser(at)mit.edu
Paul Duncan – pabs(at)pablotron.org
Ville Aine – vaine(at)cs.helsinki.fi
Eric Hodel – drbrain(at)segment7.net
Daniel Berger – djberg96(at)gmail.com
Phil Hagelberg – technomancy(at)gmail.com
Ryan Davis – ryand-ruby(at)zenspider.com
Evan Phoenix – evan(at)fallingsnow.net
Steve Klabnik – steve(at)steveklabnik.com
(If your name is missing, PLEASE let us know!)
See LICENSE.txt for permissions.
Thanks!
-The RubyGems Team
This library is an interface to secure random number generators which are suitable for generating session keys in HTTP cookies, etc.
You can use this library in your application by requiring it:
require 'securerandom'
It supports the following secure random number generators:
openssl
/dev/urandom
Win32
Generate random hexadecimal strings:
require 'securerandom' p SecureRandom.hex(10) #=> "52750b30ffbc7de3b362" p SecureRandom.hex(10) #=> "92b15d6c8dc4beb5f559" p SecureRandom.hex(13) #=> "39b290146bea6ce975c37cfc23"
Generate random base64 strings:
p SecureRandom.base64(10) #=> "EcmTPZwWRAozdA==" p SecureRandom.base64(10) #=> "KO1nIU+p9DKxGg==" p SecureRandom.base64(12) #=> "7kJSM/MzBJI+75j8"
Generate random binary strings:
p SecureRandom.random_bytes(10) #=> "\016\t{\370g\310pbr\301" p SecureRandom.random_bytes(10) #=> "\323U\030TO\234\357\020\a\337"
Generate UUIDs:
p SecureRandom.uuid #=> "2d931510-d99f-494a-8c67-87feb05e1594" p SecureRandom.uuid #=> "bad85eb9-0713-4da7-8d36-07a8e4b00eab"
An SSLContext is used to set various options regarding certificates, algorithms, verification, session caching, etc. The SSLContext is used to create an SSLSocket.
All attributes must be set before creating an SSLSocket as the SSLContext will be frozen afterward.
Configuration options for dumping YAML.
SSLConfig handles the needed SSL information for establishing a DRbSSLSocket connection, including generating the X509 / RSA pair.
An instance of this config can be passed to DRbSSLSocket.new, DRbSSLSocket.open and DRbSSLSocket.open_server
See DRb::DRbSSLSocket::SSLConfig.new for more details
See Net::HTTPGenericRequest for attributes and methods.