Raised to stop the iteration, in particular by Enumerator#next. It is rescued by Kernel#loop.
loop do puts "Hello" raise StopIteration puts "World" end puts "Done!"
produces:
Hello Done!
Raised by exit to initiate the termination of the script.
Raised when the interrupt signal is received, typically because the user has pressed Control-C (on most posix platforms). As such, it is a subclass of SignalException.
begin puts "Press ctrl-C when you get bored" loop {} rescue Interrupt => e puts "Note: You will typically use Signal.trap instead." end
produces:
Press ctrl-C when you get bored
then waits until it is interrupted with Control-C and then prints:
Note: You will typically use Signal.trap instead.
The most standard error types are subclasses of StandardError. A rescue clause without an explicit Exception class will rescue all StandardErrors (and only those).
def foo raise "Oups" end foo rescue "Hello" #=> "Hello"
On the other hand:
require 'does/not/exist' rescue "Hi"
raises the exception:
LoadError: no such file to load -- does/not/exist
Raised when the given index is invalid.
a = [:foo, :bar] a.fetch(0) #=> :foo a[4] #=> nil a.fetch(4) #=> IndexError: index 4 outside of array bounds: -2...2
Raised when a given numerical value is out of range.
[1, 2, 3].drop(1 << 100)
raises the exception:
RangeError: bignum too big to convert into `long'
ScriptError is the superclass for errors raised when a script can not be executed because of a LoadError, NotImplementedError or a SyntaxError. Note these type of ScriptErrors are not StandardError and will not be rescued unless it is specified explicitly (or its ancestor Exception).
No longer used by internal code.
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
A Range object represents a collection of values that are between given begin and end values.
You can create an Range object explicitly with:
A range literal:
# Ranges that use '..' to include the given end value. (1..4).to_a # => [1, 2, 3, 4] ('a'..'d').to_a # => ["a", "b", "c", "d"] # Ranges that use '...' to exclude the given end value. (1...4).to_a # => [1, 2, 3] ('a'...'d').to_a # => ["a", "b", "c"]
A range may be created using method Range.new:
# Ranges that by default include the given end value. Range.new(1, 4).to_a # => [1, 2, 3, 4] Range.new('a', 'd').to_a # => ["a", "b", "c", "d"] # Ranges that use third argument +exclude_end+ to exclude the given end value. Range.new(1, 4, true).to_a # => [1, 2, 3] Range.new('a', 'd', true).to_a # => ["a", "b", "c"]
A beginless range has a definite end value, but a nil begin value. Such a range includes all values up to the end value.
r = (..4) # => nil..4 r.begin # => nil r.include?(-50) # => true r.include?(4) # => true r = (...4) # => nil...4 r.include?(4) # => false Range.new(nil, 4) # => nil..4 Range.new(nil, 4, true) # => nil...4
A beginless range may be used to slice an array:
a = [1, 2, 3, 4] r = (..2) # => nil...2 a[r] # => [1, 2]
Method each for a beginless range raises an exception.
An endless range has a definite begin value, but a nil end value. Such a range includes all values from the begin value.
r = (1..) # => 1.. r.end # => nil r.include?(50) # => true Range.new(1, nil) # => 1..
The literal for an endless range may be written with either two dots or three. The range has the same elements, either way. But note that the two are not equal:
r0 = (1..) # => 1.. r1 = (1...) # => 1... r0.begin == r1.begin # => true r0.end == r1.end # => true r0 == r1 # => false
An endless range may be used to slice an array:
a = [1, 2, 3, 4] r = (2..) # => 2.. a[r] # => [3, 4]
Method each for an endless range calls the given block indefinitely:
a = [] r = (1..) r.each do |i| a.push(i) if i.even? break if i > 10 end a # => [2, 4, 6, 8, 10]
A range can be both beginless and endless. For literal beginless, endless ranges, at least the beginning or end of the range must be given as an explicit nil value. It is recommended to use an explicit nil beginning and implicit nil end, since that is what Ruby uses for Range#inspect:
(nil..) # => (nil..) (..nil) # => (nil..) (nil..nil) # => (nil..)
An object may be put into a range if its class implements instance method <=>. Ruby core classes that do so include Array, Complex, File::Stat, Float, Integer, Kernel, Module, Numeric, Rational, String, Symbol, and Time.
Example:
t0 = Time.now # => 2021-09-19 09:22:48.4854986 -0500 t1 = Time.now # => 2021-09-19 09:22:56.0365079 -0500 t2 = Time.now # => 2021-09-19 09:23:08.5263283 -0500 (t0..t2).include?(t1) # => true (t0..t1).include?(t2) # => false
A range can be iterated over only if its elements implement instance method succ. Ruby core classes that do so include Integer, String, and Symbol (but not the other classes mentioned above).
Iterator methods include:
Included from module Enumerable: each_entry, each_with_index, each_with_object, each_slice, each_cons, and reverse_each.
Example:
a = [] (1..4).each {|i| a.push(i) } a # => [1, 2, 3, 4]
A user-defined class that is to be used in a range must implement instance <=>; see Integer#<=>. To make iteration available, it must also implement instance method succ; see Integer#succ.
The class below implements both <=> and succ, and so can be used both to construct ranges and to iterate over them. Note that the Comparable module is included so the == method is defined in terms of <=>.
# Represent a string of 'X' characters. class Xs include Comparable attr_accessor :length def initialize(n) @length = n end def succ Xs.new(@length + 1) end def <=>(other) @length <=> other.length end def to_s sprintf "%2d #{inspect}", @length end def inspect 'X' * @length end end r = Xs.new(3)..Xs.new(6) #=> XXX..XXXXXX r.to_a #=> [XXX, XXXX, XXXXX, XXXXXX] r.include?(Xs.new(5)) #=> true r.include?(Xs.new(7)) #=> false
First, what’s elsewhere. Class Range:
Inherits from class Object.
Includes module Enumerable, which provides dozens of additional methods.
Here, class Range provides methods that are useful for:
::new: Returns a new range.
begin: Returns the begin value given for self.
bsearch: Returns an element from self selected by a binary search.
count: Returns a count of elements in self.
end: Returns the end value given for self.
exclude_end?: Returns whether the end object is excluded.
first: Returns the first elements of self.
hash: Returns the integer hash code.
last: Returns the last elements of self.
max: Returns the maximum values in self.
min: Returns the minimum values in self.
minmax: Returns the minimum and maximum values in self.
size: Returns the count of elements in self.
==: Returns whether a given object is equal to self (uses ==).
===: Returns whether the given object is between the begin and end values.
cover?: Returns whether a given object is within self.
eql?: Returns whether a given object is equal to self (uses eql?).
include? (aliased as member?): Returns whether a given object is an element of self.
%: Requires argument n; calls the block with each n-th element of self.
each: Calls the block with each element of self.
step: Takes optional argument n (defaults to 1); calls the block with each n-th element of self.
Ripper is a Ruby script parser.
You can get information from the parser with event-based style. Information such as abstract syntax trees or simple lexical analysis of the Ruby program.
Ripper provides an easy interface for parsing your program into a symbolic expression tree (or S-expression).
Understanding the output of the parser may come as a challenge, it’s recommended you use PP to format the output for legibility.
require 'ripper'
require 'pp'
pp Ripper.sexp('def hello(world) "Hello, #{world}!"; end')
#=> [:program,
[[:def,
[:@ident, "hello", [1, 4]],
[:paren,
[:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil, nil, nil]],
[:bodystmt,
[[:string_literal,
[:string_content,
[:@tstring_content, "Hello, ", [1, 18]],
[:string_embexpr, [[:var_ref, [:@ident, "world", [1, 27]]]]],
[:@tstring_content, "!", [1, 33]]]]],
nil,
nil,
nil]]]]
You can see in the example above, the expression starts with :program.
From here, a method definition at :def, followed by the method’s identifier :@ident. After the method’s identifier comes the parentheses :paren and the method parameters under :params.
Next is the method body, starting at :bodystmt (stmt meaning statement), which contains the full definition of the method.
In our case, we’re simply returning a String, so next we have the :string_literal expression.
Within our :string_literal you’ll notice two @tstring_content, this is the literal part for Hello, and !. Between the two @tstring_content statements is a :string_embexpr, where embexpr is an embedded expression. Our expression consists of a local variable, or var_ref, with the identifier (@ident) of world.
ruby 1.9 (support CVS HEAD only)
bison 1.28 or later (Other yaccs do not work)
Ruby License.
Minero Aoki
aamine@loveruby.net
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.
Raised when OLE processing failed.
EX:
obj = WIN32OLE.new("NonExistProgID")
raises the exception:
WIN32OLERuntimeError: unknown OLE server: `NonExistProgID'
HRESULT error code:0x800401f3
Invalid class string
Class GetoptLong provides parsing both for options and for regular arguments.
Using GetoptLong, you can define options for your program. The program can then capture and respond to whatever options are included in the command that executes the program.
A simple example: file simple.rb:
require 'getoptlong' options = GetoptLong.new( ['--number', '-n', GetoptLong::REQUIRED_ARGUMENT], ['--verbose', '-v', GetoptLong::OPTIONAL_ARGUMENT], ['--help', '-h', GetoptLong::NO_ARGUMENT] )
If you are somewhat familiar with options, you may want to skip to this full example.
A GetoptLong option has:
A string option name.
Zero or more string aliases for the name.
An option type.
Options may be defined by calling singleton method GetoptLong.new, which returns a new GetoptLong object. Options may then be processed by calling other methods such as GetoptLong#each.
In the array that defines an option, the first element is the string option name. Often the name takes the ‘long’ form, beginning with two hyphens.
The option name may have any number of aliases, which are defined by additional string elements.
The name and each alias must be of one of two forms:
Two hyphens, followed by one or more letters.
One hyphen, followed by a single letter.
File aliases.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', '-x', '--aaa', '-a', '-p', GetoptLong::NO_ARGUMENT] ) options.each do |option, argument| p [option, argument] end
An option may be cited by its name, or by any of its aliases; the parsed option always reports the name, not an alias:
$ ruby aliases.rb -a -p --xxx --aaa -x
Output:
["--xxx", ""] ["--xxx", ""] ["--xxx", ""] ["--xxx", ""] ["--xxx", ""]
An option may also be cited by an abbreviation of its name or any alias, as long as that abbreviation is unique among the options.
File abbrev.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', GetoptLong::NO_ARGUMENT], ['--xyz', GetoptLong::NO_ARGUMENT] ) options.each do |option, argument| p [option, argument] end
Command line:
$ ruby abbrev.rb --xxx --xx --xyz --xy
Output:
["--xxx", ""] ["--xxx", ""] ["--xyz", ""] ["--xyz", ""]
This command line raises GetoptLong::AmbiguousOption:
$ ruby abbrev.rb --x
An option may be cited more than once:
$ ruby abbrev.rb --xxx --xyz --xxx --xyz
Output:
["--xxx", ""] ["--xyz", ""] ["--xxx", ""] ["--xyz", ""]
A option-like token that appears anywhere after the token -- is treated as an ordinary argument, and is not processed as an option:
$ ruby abbrev.rb --xxx --xyz -- --xxx --xyz
Output:
["--xxx", ""] ["--xyz", ""]
Each option definition includes an option type, which controls whether the option takes an argument.
File types.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', GetoptLong::REQUIRED_ARGUMENT], ['--yyy', GetoptLong::OPTIONAL_ARGUMENT], ['--zzz', GetoptLong::NO_ARGUMENT] ) options.each do |option, argument| p [option, argument] end
Note that an option type has to do with the option argument (whether it is required, optional, or forbidden), not with whether the option itself is required.
An option of type GetoptLong::REQUIRED_ARGUMENT must be followed by an argument, which is associated with that option:
$ ruby types.rb --xxx foo
Output:
["--xxx", "foo"]
If the option is not last, its argument is whatever follows it (even if the argument looks like another option):
$ ruby types.rb --xxx --yyy
Output:
["--xxx", "--yyy"]
If the option is last, an exception is raised:
$ ruby types.rb # Raises GetoptLong::MissingArgument
An option of type GetoptLong::OPTIONAL_ARGUMENT may be followed by an argument, which if given is associated with that option.
If the option is last, it does not have an argument:
$ ruby types.rb --yyy
Output:
["--yyy", ""]
If the option is followed by another option, it does not have an argument:
$ ruby types.rb --yyy --zzz
Output:
["--yyy", ""] ["--zzz", ""]
Otherwise the option is followed by its argument, which is associated with that option:
$ ruby types.rb --yyy foo
Output:
["--yyy", "foo"]
An option of type GetoptLong::NO_ARGUMENT takes no argument:
ruby types.rb --zzz foo
Output:
["--zzz", ""]
You can process options either with method each and a block, or with method get.
During processing, each found option is removed, along with its argument if there is one. After processing, each remaining element was neither an option nor the argument for an option.
File argv.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', GetoptLong::REQUIRED_ARGUMENT], ['--yyy', GetoptLong::OPTIONAL_ARGUMENT], ['--zzz', GetoptLong::NO_ARGUMENT] ) puts "Original ARGV: #{ARGV}" options.each do |option, argument| p [option, argument] end puts "Remaining ARGV: #{ARGV}"
Command line:
$ ruby argv.rb --xxx Foo --yyy Bar Baz --zzz Bat Bam
Output:
Original ARGV: ["--xxx", "Foo", "--yyy", "Bar", "Baz", "--zzz", "Bat", "Bam"] ["--xxx", "Foo"] ["--yyy", "Bar"] ["--zzz", ""] Remaining ARGV: ["Baz", "Bat", "Bam"]
There are three settings that control the way the options are interpreted:
PERMUTE.
REQUIRE_ORDER.
RETURN_IN_ORDER.
The initial setting for a new GetoptLong object is REQUIRE_ORDER if environment variable POSIXLY_CORRECT is defined, PERMUTE otherwise.
In the PERMUTE ordering, options and other, non-option, arguments may appear in any order and any mixture.
File permute.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', GetoptLong::REQUIRED_ARGUMENT], ['--yyy', GetoptLong::OPTIONAL_ARGUMENT], ['--zzz', GetoptLong::NO_ARGUMENT] ) puts "Original ARGV: #{ARGV}" options.each do |option, argument| p [option, argument] end puts "Remaining ARGV: #{ARGV}"
Command line:
$ ruby permute.rb Foo --zzz Bar --xxx Baz --yyy Bat Bam --xxx Bag Bah
Output:
Original ARGV: ["Foo", "--zzz", "Bar", "--xxx", "Baz", "--yyy", "Bat", "Bam", "--xxx", "Bag", "Bah"] ["--zzz", ""] ["--xxx", "Baz"] ["--yyy", "Bat"] ["--xxx", "Bag"] Remaining ARGV: ["Foo", "Bar", "Bam", "Bah"]
In the REQUIRE_ORDER ordering, all options precede all non-options; that is, each word after the first non-option word is treated as a non-option word (even if it begins with a hyphen).
File require_order.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', GetoptLong::REQUIRED_ARGUMENT], ['--yyy', GetoptLong::OPTIONAL_ARGUMENT], ['--zzz', GetoptLong::NO_ARGUMENT] ) options.ordering = GetoptLong::REQUIRE_ORDER puts "Original ARGV: #{ARGV}" options.each do |option, argument| p [option, argument] end puts "Remaining ARGV: #{ARGV}"
Command line:
$ ruby require_order.rb --xxx Foo Bar --xxx Baz --yyy Bat -zzz
Output:
Original ARGV: ["--xxx", "Foo", "Bar", "--xxx", "Baz", "--yyy", "Bat", "-zzz"] ["--xxx", "Foo"] Remaining ARGV: ["Bar", "--xxx", "Baz", "--yyy", "Bat", "-zzz"]
In the RETURN_IN_ORDER ordering, every word is treated as an option. A word that begins with a hyphen (or two) is treated in the usual way; a word word that does not so begin is treated as an option whose name is an empty string, and whose value is word.
File return_in_order.rb:
require 'getoptlong' options = GetoptLong.new( ['--xxx', GetoptLong::REQUIRED_ARGUMENT], ['--yyy', GetoptLong::OPTIONAL_ARGUMENT], ['--zzz', GetoptLong::NO_ARGUMENT] ) options.ordering = GetoptLong::RETURN_IN_ORDER puts "Original ARGV: #{ARGV}" options.each do |option, argument| p [option, argument] end puts "Remaining ARGV: #{ARGV}"
Command line:
$ ruby return_in_order.rb Foo --xxx Bar Baz --zzz Bat Bam
Output:
Original ARGV: ["Foo", "--xxx", "Bar", "Baz", "--zzz", "Bat", "Bam"] ["", "Foo"] ["--xxx", "Bar"] ["", "Baz"] ["--zzz", ""] ["", "Bat"] ["", "Bam"] Remaining ARGV: []
File fibonacci.rb:
require 'getoptlong' options = GetoptLong.new( ['--number', '-n', GetoptLong::REQUIRED_ARGUMENT], ['--verbose', '-v', GetoptLong::OPTIONAL_ARGUMENT], ['--help', '-h', GetoptLong::NO_ARGUMENT] ) def help(status = 0) puts <<~HELP Usage: -n n, --number n: Compute Fibonacci number for n. -v [boolean], --verbose [boolean]: Show intermediate results; default is 'false'. -h, --help: Show this help. HELP exit(status) end def print_fibonacci (number) return 0 if number == 0 return 1 if number == 1 or number == 2 i = 0 j = 1 (2..number).each do k = i + j i = j j = k puts j if @verbose end puts j unless @verbose end options.each do |option, argument| case option when '--number' @number = argument.to_i when '--verbose' @verbose = if argument.empty? true elsif argument.match(/true/i) true elsif argument.match(/false/i) false else puts '--verbose argument must be true or false' help(255) end when '--help' help end end unless @number puts 'Option --number is required.' help(255) end print_fibonacci(@number)
Command line:
$ ruby fibonacci.rb
Output:
Option --number is required.
Usage:
-n n, --number n:
Compute Fibonacci number for n.
-v [boolean], --verbose [boolean]:
Show intermediate results; default is 'false'.
-h, --help:
Show this help.
Command line:
$ ruby fibonacci.rb --number
Raises GetoptLong::MissingArgument:
fibonacci.rb: option `--number' requires an argument
Command line:
$ ruby fibonacci.rb --number 6
Output:
8
Command line:
$ ruby fibonacci.rb --number 6 --verbose
Output:
1 2 3 5 8
Command line:
$ ruby fibonacci.rb –number 6 –verbose yes
Output:
--verbose argument must be true or false
Usage:
-n n, --number n:
Compute Fibonacci number for n.
-v [boolean], --verbose [boolean]:
Show intermediate results; default is 'false'.
-h, --help:
Show this help.
PStore implements a file based persistence mechanism based on a Hash. User code can store hierarchies of Ruby objects (values) into the data store by name (keys). An object hierarchy may be just a single object. User code may later read values back from the data store or even update data, as needed.
The transactional behavior ensures that any changes succeed or fail together. This can be used to ensure that the data store is not left in a transitory state, where some values were updated but others were not.
Behind the scenes, Ruby objects are stored to the data store file with Marshal. That carries the usual limitations. Proc objects cannot be marshalled, for example.
There are three important concepts here (details at the links):
Store: a store is an instance of PStore.
Entries: the store is hash-like; each entry is the key for a stored object.
Transactions: each transaction is a collection of prospective changes to the store; a transaction is defined in the block given with a call to PStore#transaction.
Examples on this page need a store that has known properties. They can get a new (and populated) store by calling thus:
example_store do |store| # Example code using store goes here. end
All we really need to know about example_store is that it yields a fresh store with a known population of entries; its implementation:
require 'pstore' require 'tempfile' # Yield a pristine store for use in examples. def example_store # Create the store in a temporary file. Tempfile.create do |file| store = PStore.new(file) # Populate the store. store.transaction do store[:foo] = 0 store[:bar] = 1 store[:baz] = 2 end yield store end end
The contents of the store are maintained in a file whose path is specified when the store is created (see PStore.new). The objects are stored and retrieved using module Marshal, which means that certain objects cannot be added to the store; see Marshal::dump.
A store may have any number of entries. Each entry has a key and a value, just as in a hash:
Key: as in a hash, the key can be (almost) any object; see Hash Keys. You may find it convenient to keep it simple by using only symbols or strings as keys.
Value: the value may be any object that can be marshalled by Marshal (see Marshal::dump) and in fact may be a collection (e.g., an array, a hash, a set, a range, etc). That collection may in turn contain nested objects, including collections, to any depth; those objects must also be Marshal-able. See Hierarchical Values.
The block given with a call to method transaction# contains a transaction, which consists of calls to PStore methods that read from or write to the store (that is, all PStore methods except transaction itself, path, and Pstore.new):
example_store do |store| store.transaction do store.keys # => [:foo, :bar, :baz] store[:bat] = 3 store.keys # => [:foo, :bar, :baz, :bat] end end
Execution of the transaction is deferred until the block exits, and is executed atomically (all-or-nothing): either all transaction calls are executed, or none are. This maintains the integrity of the store.
Other code in the block (including even calls to path and PStore.new) is executed immediately, not deferred.
The transaction block:
May not contain a nested call to transaction.
Is the only context where methods that read from or write to the store are allowed.
As seen above, changes in a transaction are made automatically when the block exits. The block may be exited early by calling method commit or abort.
Method commit triggers the update to the store and exits the block:
example_store do |store| store.transaction do store.keys # => [:foo, :bar, :baz] store[:bat] = 3 store.commit fail 'Cannot get here' end store.transaction do # Update was completed. store.keys # => [:foo, :bar, :baz, :bat] end end
Method abort discards the update to the store and exits the block:
example_store do |store| store.transaction do store.keys # => [:foo, :bar, :baz] store[:bat] = 3 store.abort fail 'Cannot get here' end store.transaction do # Update was not completed. store.keys # => [:foo, :bar, :baz] end end
By default, a transaction allows both reading from and writing to the store:
store.transaction do # Read-write transaction. # Any code except a call to #transaction is allowed here. end
If argument read_only is passed as true, only reading is allowed:
store.transaction(true) do # Read-only transaction: # Calls to #transaction, #[]=, and #delete are not allowed here. end
The value for an entry may be a simple object (as seen above). It may also be a hierarchy of objects nested to any depth:
deep_store = PStore.new('deep.store') deep_store.transaction do array_of_hashes = [{}, {}, {}] deep_store[:array_of_hashes] = array_of_hashes deep_store[:array_of_hashes] # => [{}, {}, {}] hash_of_arrays = {foo: [], bar: [], baz: []} deep_store[:hash_of_arrays] = hash_of_arrays deep_store[:hash_of_arrays] # => {:foo=>[], :bar=>[], :baz=>[]} deep_store[:hash_of_arrays][:foo].push(:bat) deep_store[:hash_of_arrays] # => {:foo=>[:bat], :bar=>[], :baz=>[]} end
And recall that you can use dig methods in a returned hierarchy of objects.
Use method PStore.new to create a store. The new store creates or opens its containing file:
store = PStore.new('t.store')
Use method []= to update or create an entry:
example_store do |store| store.transaction do store[:foo] = 1 # Update. store[:bam] = 1 # Create. end end
Use method delete to remove an entry:
example_store do |store| store.transaction do store.delete(:foo) store[:foo] # => nil end end
Use method fetch (allows default) or [] (defaults to nil) to retrieve an entry:
example_store do |store| store.transaction do store[:foo] # => 0 store[:nope] # => nil store.fetch(:baz) # => 2 store.fetch(:nope, nil) # => nil store.fetch(:nope) # Raises exception. end end
Use method key? to determine whether a given key exists:
example_store do |store| store.transaction do store.key?(:foo) # => true end end
Use method keys to retrieve keys:
example_store do |store| store.transaction do store.keys # => [:foo, :bar, :baz] end end
Use method path to retrieve the path to the store’s underlying file; this method may be called from outside a transaction block:
store = PStore.new('t.store') store.path # => "t.store"
For transaction safety, see:
Optional argument thread_safe at method PStore.new.
Attribute ultra_safe.
Needless to say, if you’re storing valuable data with PStore, then you should backup the PStore file from time to time.
require "pstore" # A mock wiki object. class WikiPage attr_reader :page_name def initialize(page_name, author, contents) @page_name = page_name @revisions = Array.new add_revision(author, contents) end def add_revision(author, contents) @revisions << {created: Time.now, author: author, contents: contents} end def wiki_page_references [@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/) end end # Create a new wiki page. home_page = WikiPage.new("HomePage", "James Edward Gray II", "A page about the JoysOfDocumentation..." ) wiki = PStore.new("wiki_pages.pstore") # Update page data and the index together, or not at all. wiki.transaction do # Store page. wiki[home_page.page_name] = home_page # Create page index. wiki[:wiki_index] ||= Array.new # Update wiki index. wiki[:wiki_index].push(*home_page.wiki_page_references) end # Read wiki data, setting argument read_only to true. wiki.transaction(true) do wiki.keys.each do |key| puts key puts wiki[key] end end
Raised when attempting to convert special float values (in particular Infinity or NaN) to numerical classes which don’t support them.
Float::INFINITY.to_r #=> FloatDomainError: Infinity
The global value true is the only instance of class TrueClass and represents a logically true value in boolean expressions. The class provides operators allowing true to be used in logical expressions.
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.
SHA2 family
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.
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).
Include the English library file in a Ruby script, and you can reference the global variables such as $_ using less cryptic names, listed below.
Without ‘English’:
$\ = ' -- ' "waterbuffalo" =~ /buff/ print $', $$, "\n"
With English:
require "English" $OUTPUT_FIELD_SEPARATOR = ' -- ' "waterbuffalo" =~ /buff/ print $POSTMATCH, $PID, "\n"
Below is a full list of descriptive aliases and their associated global variable:
$!
$@
$;
$;
$,
$,
$/
$/
$\
$\
$.
$.
$_
$>
$<
$$
$$
$?
$~
$=
$*
$&
$‘
$‘
$+
The Find module supports the top-down traversal of a set of file paths.
For example, to total the size of all files under your home directory, ignoring anything in a “dot” directory (e.g. $HOME/.ssh):
require 'find' total_size = 0 Find.find(ENV["HOME"]) do |path| if FileTest.directory?(path) if File.basename(path).start_with?('.') Find.prune # Don't look any further into this directory. else next end else total_size += FileTest.size(path) end end
URI is a module providing classes to handle Uniform Resource Identifiers (RFC2396).
Uniform way of handling URIs.
Flexibility to introduce custom URI schemes.
Flexibility to have an alternate URI::Parser (or just different patterns and regexp’s).
require 'uri' uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413") #=> #<URI::HTTP http://foo.com/posts?id=30&limit=5#time=1305298413> uri.scheme #=> "http" uri.host #=> "foo.com" uri.path #=> "/posts" uri.query #=> "id=30&limit=5" uri.fragment #=> "time=1305298413" uri.to_s #=> "http://foo.com/posts?id=30&limit=5#time=1305298413"
module URI class RSYNC < Generic DEFAULT_PORT = 873 end register_scheme 'RSYNC', RSYNC end #=> URI::RSYNC URI.scheme_list #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP, # "HTTPS"=>URI::HTTPS, "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, # "MAILTO"=>URI::MailTo, "RSYNC"=>URI::RSYNC} uri = URI("rsync://rsync.foo.com") #=> #<URI::RSYNC rsync://rsync.foo.com>
A good place to view an RFC spec is www.ietf.org/rfc.html.
Here is a list of all related RFC’s:
Class tree URI::Generic (in uri/generic.rb)
URI::File - (in uri/file.rb)
URI::FTP - (in uri/ftp.rb)
URI::HTTP - (in uri/http.rb)
URI::HTTPS - (in uri/https.rb)
URI::LDAP - (in uri/ldap.rb)
URI::LDAPS - (in uri/ldaps.rb)
URI::MailTo - (in uri/mailto.rb)
URI::Parser - (in uri/common.rb)
URI::REGEXP - (in uri/common.rb)
URI::REGEXP::PATTERN - (in uri/common.rb)
URI::Util - (in uri/common.rb)
URI::Error - (in uri/common.rb)
URI::InvalidURIError - (in uri/common.rb)
URI::InvalidComponentError - (in uri/common.rb)
URI::BadURIError - (in uri/common.rb)
Akira Yamada <akira@ruby-lang.org>
Akira Yamada <akira@ruby-lang.org> Dmitry V. Sabanin <sdmitry@lrn.ru> Vincent Batts <vbatts@hashbangbash.com>
Copyright © 2001 akira yamada <akira@ruby-lang.org> You can redistribute it and/or modify it under the same term as Ruby.