The exception class which will be raised when pushing into a closed Queue. See Queue#close and SizedQueue#close.
Raised when throw is called with a tag which does not have corresponding catch block.
throw "foo", "bar"
raises the exception:
UncaughtThrowError: uncaught throw "foo"
newton.rb
Solves the nonlinear algebraic equation system f = 0 by Newton’s method. This program is not dependent on BigDecimal.
To call:
n = nlsolve(f,x)
where n is the number of iterations required,
x is the initial value vector
f is an Object which is used to compute the values of the equations to be solved.
It must provide the following methods:
returns the values of all functions at x
returns 0.0
returns 1.0
returns 2.0
returns 10.0
returns the convergence criterion (epsilon value) used to determine whether two values are considered equal. If |a-b| < epsilon, the two values are considered equal.
On exit, x is the solution vector.
This module provides a framework for message digest libraries.
You may want to look at OpenSSL::Digest as it supports more algorithms.
A cryptographic hash function is a procedure that takes data and returns a fixed bit string: the hash value, also known as digest. Hash functions are also called one-way functions, it is easy to compute a digest from a message, but it is infeasible to generate a message from a digest.
require 'digest' # Compute a complete digest Digest::SHA256.digest 'message' #=> "\xABS\n\x13\xE4Y..." sha256 = Digest::SHA256.new sha256.digest 'message' #=> "\xABS\n\x13\xE4Y..." # Other encoding formats Digest::SHA256.hexdigest 'message' #=> "ab530a13e459..." Digest::SHA256.base64digest 'message' #=> "q1MKE+RZFJgr..." # Compute digest by chunks md5 = Digest::MD5.new md5.update 'message1' md5 << 'message2' # << is an alias for update md5.hexdigest #=> "94af09c09bb9..." # Compute digest for a file sha256 = Digest::SHA256.file 'testfile' sha256.hexdigest
Additionally digests can be encoded in “bubble babble” format as a sequence of consonants and vowels which is more recognizable and comparable than a hexadecimal digest.
require 'digest/bubblebabble' Digest::SHA256.bubblebabble 'message' #=> "xopoh-fedac-fenyh-..."
See the bubble babble specification at web.mit.edu/kenta/www/one/bubblebabble/spec/jrtrjwzi/draft-huima-01.txt.
Digest algorithms Different digest algorithms (or hash functions) are available:
MD5
See RFC 1321 The MD5 Message-Digest Algorithm
As Digest::RMD160. See homes.esat.kuleuven.be/~bosselae/ripemd160.html.
SHA1
See FIPS 180 Secure Hash Standard.
See FIPS 180 Secure Hash Standard which defines the following algorithms:
SHA512
SHA384
SHA256
The latest versions of the FIPS publications can be found here: csrc.nist.gov/publications/PubsFIPS.html.
Psych is a YAML parser and emitter. Psych leverages libyaml [Home page: pyyaml.org/wiki/LibYAML] or [HG repo: bitbucket.org/xi/libyaml] for its YAML parsing and emitting capabilities. In addition to wrapping libyaml, Psych also knows how to serialize and de-serialize most Ruby objects to and from the YAML format.
# Parse some YAML Psych.load("--- foo") # => "foo" # Emit some YAML Psych.dump("foo") # => "--- foo\n...\n" { :a => 'b'}.to_yaml # => "---\n:a: b\n"
Got more time on your hands? Keep on reading!
Psych provides a range of interfaces for parsing a YAML document ranging from low level to high level, depending on your parsing needs. At the lowest level, is an event based parser. Mid level is access to the raw YAML AST, and at the highest level is the ability to unmarshal YAML to Ruby objects.
Psych provides a range of interfaces ranging from low to high level for producing YAML documents. Very similar to the YAML parsing interfaces, Psych provides at the lowest level, an event based system, mid-level is building a YAML AST, and the highest level is converting a Ruby object straight to a YAML document.
The high level YAML parser provided by Psych simply takes YAML as input and returns a Ruby data structure. For information on using the high level parser see Psych.load
Psych.load("--- a") # => 'a' Psych.load("---\n - a\n - b") # => ['a', 'b']
Psych.load_file("database.yml")
Exception handling begin # The second argument changes only the exception contents Psych.parse("--- `", "file.txt") rescue Psych::SyntaxError => ex ex.file # => 'file.txt' ex.message # => "(file.txt): found character that cannot start any token" end
The high level emitter has the easiest interface. Psych simply takes a Ruby data structure and converts it to a YAML document. See Psych.dump for more information on dumping a Ruby data structure.
# Dump an array, get back a YAML string Psych.dump(['a', 'b']) # => "---\n- a\n- b\n" # Dump an array to an IO object Psych.dump(['a', 'b'], StringIO.new) # => #<StringIO:0x000001009d0890> # Dump an array with indentation set Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n- - b\n" # Dump an array to an IO with indentation set Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)
Currently there is no direct API for dumping Ruby structure to file:
File.open('database.yml', 'w') do |file| file.write(Psych.dump(['a', 'b'])) end
Psych provides access to an AST produced from parsing a YAML document. This tree is built using the Psych::Parser and Psych::TreeBuilder. The AST can be examined and manipulated freely. Please see Psych::parse_stream, Psych::Nodes, and Psych::Nodes::Node for more information on dealing with YAML syntax trees.
# Returns Psych::Nodes::Stream Psych.parse_stream("---\n - a\n - b") # Returns Psych::Nodes::Document Psych.parse("---\n - a\n - b")
# Returns Psych::Nodes::Stream Psych.parse_stream(File.read('database.yml')) # Returns Psych::Nodes::Document Psych.parse_file('database.yml')
Exception handling begin # The second argument changes only the exception contents Psych.parse("--- `", "file.txt") rescue Psych::SyntaxError => ex ex.file # => 'file.txt' ex.message # => "(file.txt): found character that cannot start any token" end
At the mid level is building an AST. This AST is exactly the same as the AST used when parsing a YAML document. Users can build an AST by hand and the AST knows how to emit itself as a YAML document. See Psych::Nodes, Psych::Nodes::Node, and Psych::TreeBuilder for more information on building a YAML AST.
# We need Psych::Nodes::Stream (not Psych::Nodes::Document) stream = Psych.parse_stream("---\n - a\n - b") stream.to_yaml # => "---\n- a\n- b\n"
# We need Psych::Nodes::Stream (not Psych::Nodes::Document) stream = Psych.parse_stream(File.read('database.yml')) File.open('database.yml', 'w') do |file| file.write(stream.to_yaml) end
The lowest level parser should be used when the YAML input is already known, and the developer does not want to pay the price of building an AST or automatic detection and conversion to Ruby objects. See Psych::Parser for more information on using the event based parser.
Psych::Nodes::Stream structure parser = Psych::Parser.new(TreeBuilder.new) # => #<Psych::Parser> parser = Psych.parser # it's an alias for the above parser.parse("---\n - a\n - b") # => #<Psych::Parser> parser.handler # => #<Psych::TreeBuilder> parser.handler.root # => #<Psych::Nodes::Stream>
recorder = Psych::Handlers::Recorder.new parser = Psych::Parser.new(recorder) parser.parse("---\n - a\n - b") recorder.events # => [list of [event, args] lists] # event is one of: Psych::Handler::EVENTS # args are the arguments passed to the event
The lowest level emitter is an event based system. Events are sent to a Psych::Emitter object. That object knows how to convert the events to a YAML document. This interface should be used when document format is known in advance or speed is a concern. See Psych::Emitter for more information.
Psych.parser.parse("--- a") # => #<Psych::Parser> parser.handler.first # => #<Psych::Nodes::Stream> parser.handler.first.to_ruby # => ["a"] parser.handler.root.first # => #<Psych::Nodes::Document> parser.handler.root.first.to_ruby # => "a" # You can instantiate an Emitter manually Psych::Visitors::ToRuby.new.accept(parser.handler.root.first) # => "a"
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>.
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).
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" }
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!"
We want to rely on what has come before obviously, but with delegation we can take just the methods we need and even rename them as appropriate. In many cases this is preferable to inheritance, which gives us the entire old interface, even if much of it isn’t needed.
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 = 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.
SingleForwardable can be used to setup delegation at the object level as well.
printer = String.new printer.extend SingleForwardable # prepare object for delegation printer.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts() printer.puts "Howdy!"
Also, SingleForwardable can be used to set up delegation for a Class or Module.
class Implementation def self.service puts "serviced!" end end module Facade extend SingleForwardable def_delegator :Implementation, :service end Facade.service #=> serviced!
If you want to use both Forwardable and SingleForwardable, you can use methods def_instance_delegator and def_single_delegator, etc.
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
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' SecureRandom.hex(10) #=> "52750b30ffbc7de3b362" SecureRandom.hex(10) #=> "92b15d6c8dc4beb5f559" SecureRandom.hex(13) #=> "39b290146bea6ce975c37cfc23"
Generate random base64 strings:
SecureRandom.base64(10) #=> "EcmTPZwWRAozdA==" SecureRandom.base64(10) #=> "KO1nIU+p9DKxGg==" SecureRandom.base64(12) #=> "7kJSM/MzBJI+75j8"
Generate random binary strings:
SecureRandom.random_bytes(10) #=> "\016\t{\370g\310pbr\301" SecureRandom.random_bytes(10) #=> "\323U\030TO\234\357\020\a\337"
Generate alphanumeric strings:
SecureRandom.alphanumeric(10) #=> "S8baxMJnPl" SecureRandom.alphanumeric(10) #=> "aOxAg8BAJe"
Generate UUIDs:
SecureRandom.uuid #=> "2d931510-d99f-494a-8c67-87feb05e1594" SecureRandom.uuid #=> "bad85eb9-0713-4da7-8d36-07a8e4b00eab"
This module manipulates strings according to the word parsing rules of the UNIX Bourne shell.
The shellwords() function was originally a port of shellwords.pl, but modified to conform to the Shell & Utilities volume of the IEEE Std 1003.1-2008, 2016 Edition [1].
You can use Shellwords to parse a string into a Bourne shell friendly Array.
require 'shellwords' argv = Shellwords.split('three blind "mice"') argv #=> ["three", "blind", "mice"]
Once you’ve required Shellwords, you can use the split alias String#shellsplit.
argv = "see how they run".shellsplit argv #=> ["see", "how", "they", "run"]
Be careful you don’t leave a quote unmatched.
argv = "they all ran after the farmer's wife".shellsplit #=> ArgumentError: Unmatched double quote: ...
In this case, you might want to use Shellwords.escape, or its alias String#shellescape.
This method will escape the String for you to safely use with a Bourne shell.
argv = Shellwords.escape("special's.txt") argv #=> "special\\'s.txt" system("cat " + argv)
Shellwords also comes with a core extension for Array, Array#shelljoin.
argv = %w{ls -lta lib} system(argv.shelljoin)
You can use this method to create an escaped string out of an array of tokens separated by a space. In this example we used the literal shortcut for Array.new.
Wakou Aoyama
Akinori MUSHA <knu@iDaemons.org>
Akinori MUSHA <knu@iDaemons.org> (current maintainer)
1: IEEE Std 1003.1-2008, 2016 Edition, the Shell & Utilities volume
The Singleton module implements the Singleton pattern.
To use Singleton, include the module in your class.
class Klass include Singleton # ... end
This ensures that only one instance of Klass can be created.
a,b = Klass.instance, Klass.instance a == b # => true Klass.new # => NoMethodError - new is private ...
The instance is created at upon the first call of Klass.instance().
class OtherKlass include Singleton # ... end ObjectSpace.each_object(OtherKlass){} # => 0 OtherKlass.instance ObjectSpace.each_object(OtherKlass){} # => 1
This behavior is preserved under inheritance and cloning.
This above is achieved by:
Making Klass.new and Klass.allocate private.
Overriding Klass.inherited(sub_klass) and Klass.clone() to ensure that the Singleton properties are kept when inherited and cloned.
Providing the Klass.instance() method that returns the same object each time it is called.
Overriding Klass._load(str) to call Klass.instance().
Overriding Klass#clone and Klass#dup to raise TypeErrors to prevent cloning or duping.
Singleton and Marshal By default Singleton’s _dump(depth) returns the empty string. Marshalling by default will strip state information, e.g. instance variables and taint state, from the instance. Classes using Singleton can provide custom _load(str) and _dump(depth) methods to retain some of the previous state of the instance.
require 'singleton' class Example include Singleton attr_accessor :keep, :strip def _dump(depth) # this strips the @strip information from the instance Marshal.dump(@keep, depth) end def self._load(str) instance.keep = Marshal.load(str) instance end end a = Example.instance a.keep = "keep this" a.strip = "get rid of this" a.taint stored_state = Marshal.dump(a) a.keep = nil a.strip = nil b = Marshal.load(stored_state) p a == b # => true p a.keep # => "keep this" p a.strip # => nil
TSort implements topological sorting using Tarjan’s algorithm for strongly connected components.
TSort is designed to be able to be used with any object which can be interpreted as a directed graph.
TSort requires two methods to interpret an object as a graph, tsort_each_node and tsort_each_child.
tsort_each_node is used to iterate for all nodes over a graph.
tsort_each_child is used to iterate for child nodes of a given node.
The equality of nodes are defined by eql? and hash since TSort uses Hash internally.
The following example demonstrates how to mix the TSort module into an existing class (in this case, Hash). Here, we’re treating each key in the hash as a node in the graph, and so we simply alias the required tsort_each_node method to Hash’s each_key method. For each key in the hash, the associated value is an array of the node’s child nodes. This choice in turn leads to our implementation of the required tsort_each_child method, which fetches the array of child nodes and then iterates over that array using the user-supplied block.
require 'tsort' class Hash include TSort alias tsort_each_node each_key def tsort_each_child(node, &block) fetch(node).each(&block) end end {1=>[2, 3], 2=>[3], 3=>[], 4=>[]}.tsort #=> [3, 2, 1, 4] {1=>[2], 2=>[3, 4], 3=>[2], 4=>[]}.strongly_connected_components #=> [[4], [2, 3], [1]]
A very simple ‘make’ like tool can be implemented as follows:
require 'tsort' class Make def initialize @dep = {} @dep.default = [] end def rule(outputs, inputs=[], &block) triple = [outputs, inputs, block] outputs.each {|f| @dep[f] = [triple]} @dep[triple] = inputs end def build(target) each_strongly_connected_component_from(target) {|ns| if ns.length != 1 fs = ns.delete_if {|n| Array === n} raise TSort::Cyclic.new("cyclic dependencies: #{fs.join ', '}") end n = ns.first if Array === n outputs, inputs, block = n inputs_time = inputs.map {|f| File.mtime f}.max begin outputs_time = outputs.map {|f| File.mtime f}.min rescue Errno::ENOENT outputs_time = nil end if outputs_time == nil || inputs_time != nil && outputs_time <= inputs_time sleep 1 if inputs_time != nil && inputs_time.to_i == Time.now.to_i block.call end end } end def tsort_each_child(node, &block) @dep[node].each(&block) end include TSort end def command(arg) print arg, "\n" system arg end m = Make.new m.rule(%w[t1]) { command 'date > t1' } m.rule(%w[t2]) { command 'date > t2' } m.rule(%w[t3]) { command 'date > t3' } m.rule(%w[t4], %w[t1 t3]) { command 'cat t1 t3 > t4' } m.rule(%w[t5], %w[t4 t2]) { command 'cat t4 t2 > t5' } m.build('t5')
‘tsort.rb’ is wrong name because this library uses Tarjan’s algorithm for strongly connected components. Although ‘strongly_connected_components.rb’ is correct but too long.
Tarjan, “Depth First Search and Linear Graph Algorithms”,
SIAM Journal on Computing, Vol. 1, No. 2, pp. 146-160, June 1972.
define UnicodeNormalize module here so that we don’t have to look it up
In-memory session storage class.
Implements session storage as a global in-memory hash. Session data will only persist for as long as the Ruby interpreter instance does.
A StoreContext is used while validating a single certificate and holds the status involved.
The X509 certificate store holds trusted CA certificates used to verify peer certificates.
The easiest way to create a useful certificate store is:
cert_store = OpenSSL::X509::Store.new cert_store.set_default_paths
This will use your system’s built-in certificates.
If your system does not have a default set of certificates you can obtain a set extracted from Mozilla CA certificate store by cURL maintainers here: curl.haxx.se/docs/caextract.html (You may wish to use the firefox-db2pem.sh script to extract the certificates from a local install to avoid man-in-the-middle attacks.)
After downloading or generating a cacert.pem from the above link you can create a certificate store from the pem file like this:
cert_store = OpenSSL::X509::Store.new cert_store.add_file 'cacert.pem'
The certificate store can be used with an SSLSocket like this:
ssl_context = OpenSSL::SSL::SSLContext.new ssl_context.verify_mode = OpenSSL::SSL::VERIFY_PEER ssl_context.cert_store = cert_store tcp_socket = TCPSocket.open 'example.com', 443 ssl_socket = OpenSSL::SSL::SSLSocket.new tcp_socket, ssl_context
File-based session storage class.
Implements session storage as a flat file of ‘key=value’ values. This storage type only works directly with String values; the user is responsible for converting other types to Strings when storing and from Strings when retrieving.
Dummy session storage class.
Implements session storage place holder. No actual storage will be done.