Results for: "pstore"

SecurityError

No longer used by internal code.

EncodingError

EncodingError is the base class for encoding errors.

NoMatchingPatternError

No documentation available

NoMatchingPatternKeyError

No documentation available

OpenStruct

An OpenStruct is a data structure, similar to a Hash, that allows the definition of arbitrary attributes with their accompanying values. This is accomplished by using Ruby’s metaprogramming to define methods on the class itself.

Examples 

require "ostruct"

person = OpenStruct.new
person.name = "John Smith"
person.age  = 70

person.name      # => "John Smith"
person.age       # => 70
person.address   # => nil

An OpenStruct employs a Hash internally to store the attributes and values and can even be initialized with one:

australia = OpenStruct.new(:country => "Australia", :capital => "Canberra")
  # => #<OpenStruct country="Australia", capital="Canberra">

Hash keys with spaces or characters that could normally not be used for method calls (e.g. ()[]*) will not be immediately available on the OpenStruct object as a method for retrieval or assignment, but can still be reached through the Object#send method or using [].

measurements = OpenStruct.new("length (in inches)" => 24)
measurements[:"length (in inches)"]       # => 24
measurements.send("length (in inches)")   # => 24

message = OpenStruct.new(:queued? => true)
message.queued?                           # => true
message.send("queued?=", false)
message.queued?                           # => false

Removing the presence of an attribute requires the execution of the delete_field method as setting the property value to nil will not remove the attribute.

first_pet  = OpenStruct.new(:name => "Rowdy", :owner => "John Smith")
second_pet = OpenStruct.new(:name => "Rowdy")

first_pet.owner = nil
first_pet                 # => #<OpenStruct name="Rowdy", owner=nil>
first_pet == second_pet   # => false

first_pet.delete_field(:owner)
first_pet                 # => #<OpenStruct name="Rowdy">
first_pet == second_pet   # => true

Ractor compatibility: A frozen OpenStruct with shareable values is itself shareable.

Caveats

An OpenStruct utilizes Ruby’s method lookup structure to find and define the necessary methods for properties. This is accomplished through the methods method_missing and define_singleton_method.

This should be a consideration if there is a concern about the performance of the objects that are created, as there is much more overhead in the setting of these properties compared to using a Hash or a Struct. Creating an open struct from a small Hash and accessing a few of the entries can be 200 times slower than accessing the hash directly.

This is a potential security issue; building OpenStruct from untrusted user data (e.g. JSON web request) may be susceptible to a “symbol denial of service” attack since the keys create methods and names of methods are never garbage collected.

This may also be the source of incompatibilities between Ruby versions:

o = OpenStruct.new
o.then # => nil in Ruby < 2.6, enumerator for Ruby >= 2.6

Builtin methods may be overwritten this way, which may be a source of bugs or security issues:

o = OpenStruct.new
o.methods # => [:to_h, :marshal_load, :marshal_dump, :each_pair, ...
o.methods = [:foo, :bar]
o.methods # => [:foo, :bar]

To help remedy clashes, OpenStruct uses only protected/private methods ending with ! and defines aliases for builtin public methods by adding a !:

o = OpenStruct.new(make: 'Bentley', class: :luxury)
o.class # => :luxury
o.class! # => OpenStruct

It is recommended (but not enforced) to not use fields ending in !; Note that a subclass’ methods may not be overwritten, nor can OpenStruct’s own methods ending with !.

For all these reasons, consider not using OpenStruct at all.

Regexp

A regular expression (also called a regexp) is a match pattern (also simply called a pattern).

A common notation for a regexp uses enclosing slash characters:

/foo/

A regexp may be applied to a target string; The part of the string (if any) that matches the pattern is called a match, and may be said to match:

re = /red/
re.match?('redirect') # => true   # Match at beginning of target.
re.match?('bored')    # => true   # Match at end of target.
re.match?('credit')   # => true   # Match within target.
re.match?('foo')      # => false  # No match.

Regexp Uses

A regexp may be used:

Regexp Objects

A regexp object has:

Creating a Regexp

A regular expression may be created with:

Method match

Each of the methods Regexp#match, String#match, and Symbol#match returns a MatchData object if a match was found, nil otherwise; each also sets global variables:

'food'.match(/foo/) # => #<MatchData "foo">
'food'.match(/bar/) # => nil

Operator =~

Each of the operators Regexp#=~, String#=~, and Symbol#=~ returns an integer offset if a match was found, nil otherwise; each also sets global variables:

/bar/ =~ 'foo bar' # => 4
'foo bar' =~ /bar/ # => 4
/baz/ =~ 'foo bar' # => nil

Method match?

Each of the methods Regexp#match?, String#match?, and Symbol#match? returns true if a match was found, false otherwise; none sets global variables:

'food'.match?(/foo/) # => true
'food'.match?(/bar/) # => false

Global Variables

Certain regexp-oriented methods assign values to global variables:

The affected global variables are:

Examples:

# Matched string, but no matched groups.
'foo bar bar baz'.match('bar')
$~ # => #<MatchData "bar">
$& # => "bar"
$` # => "foo "
$' # => " bar baz"
$+ # => nil
$1 # => nil

# Matched groups.
/s(\w{2}).*(c)/.match('haystack')
$~ # => #<MatchData "stac" 1:"ta" 2:"c">
$& # => "stac"
$` # => "hay"
$' # => "k"
$+ # => "c"
$1 # => "ta"
$2 # => "c"
$3 # => nil

# No match.
'foo'.match('bar')
$~ # => nil
$& # => nil
$` # => nil
$' # => nil
$+ # => nil
$1 # => nil

Note that Regexp#match?, String#match?, and Symbol#match? do not set global variables.

Sources

As seen above, the simplest regexp uses a literal expression as its source:

re = /foo/              # => /foo/
re.match('food')        # => #<MatchData "foo">
re.match('good')        # => nil

A rich collection of available subexpressions gives the regexp great power and flexibility:

Special Characters

Regexp special characters, called metacharacters, have special meanings in certain contexts; depending on the context, these are sometimes metacharacters:

. ? - + * ^ \ | $ ( ) [ ] { }

To match a metacharacter literally, backslash-escape it:

# Matches one or more 'o' characters.
/o+/.match('foo')  # => #<MatchData "oo">
# Would match 'o+'.
/o\+/.match('foo') # => nil

To match a backslash literally, backslash-escape it:

/\./.match('\.')  # => #<MatchData ".">
/\\./.match('\.') # => #<MatchData "\\.">

Method Regexp.escape returns an escaped string:

Regexp.escape('.?-+*^\|$()[]{}')
# => "\\.\\?\\-\\+\\*\\^\\\\\\|\\$\\(\\)\\[\\]\\{\\}"

Source Literals

The source literal largely behaves like a double-quoted string; see Regexp Literals.

In particular, a source literal may contain interpolated expressions:

s = 'foo'         # => "foo"
/#{s}/            # => /foo/
/#{s.capitalize}/ # => /Foo/
/#{2 + 2}/        # => /4/

There are differences between an ordinary string literal and a source literal; see Shorthand Character Classes.

Character Classes

A character class is delimited by square brackets; it specifies that certain characters match at a given point in the target string:

# This character class will match any vowel.
re = /B[aeiou]rd/
re.match('Bird') # => #<MatchData "Bird">
re.match('Bard') # => #<MatchData "Bard">
re.match('Byrd') # => nil

A character class may contain hyphen characters to specify ranges of characters:

# These regexps have the same effect.
/[abcdef]/.match('foo') # => #<MatchData "f">
/[a-f]/.match('foo')    # => #<MatchData "f">
/[a-cd-f]/.match('foo') # => #<MatchData "f">

When the first character of a character class is a caret (^), the sense of the class is inverted: it matches any character except those specified.

/[^a-eg-z]/.match('f') # => #<MatchData "f">

A character class may contain another character class. By itself this isn’t useful because [a-z[0-9]] describes the same set as [a-z0-9].

However, character classes also support the && operator, which performs set intersection on its arguments. The two can be combined as follows:

/[a-w&&[^c-g]z]/ # ([a-w] AND ([^c-g] OR z))

This is equivalent to:

/[abh-w]/

Shorthand Character Classes

Each of the following metacharacters serves as a shorthand for a character class:

Anchors

An anchor is a metasequence that matches a zero-width position between characters in the target string.

For a subexpression with no anchor, matching may begin anywhere in the target string:

/real/.match('surrealist') # => #<MatchData "real">

For a subexpression with an anchor, matching must begin at the matched anchor.

Boundary Anchors

Each of these anchors matches a boundary:

Lookaround Anchors

Lookahead anchors:

Lookbehind anchors:

The pattern below uses positive lookahead and positive lookbehind to match text appearing in … tags without including the tags in the match:

/(?<=<b>)\w+(?=<\/b>)/.match("Fortune favors the <b>bold</b>.")
# => #<MatchData "bold">

Match-Reset Anchor

Alternation

The vertical bar metacharacter (|) may be used within parentheses to express alternation: two or more subexpressions any of which may match the target string.

Two alternatives:

re = /(a|b)/
re.match('foo') # => nil
re.match('bar') # => #<MatchData "b" 1:"b">

Four alternatives:

re = /(a|b|c|d)/
re.match('shazam') # => #<MatchData "a" 1:"a">
re.match('cold')   # => #<MatchData "c" 1:"c">

Each alternative is a subexpression, and may be composed of other subexpressions:

re = /([a-c]|[x-z])/
re.match('bar') # => #<MatchData "b" 1:"b">
re.match('ooz') # => #<MatchData "z" 1:"z">

Method Regexp.union provides a convenient way to construct a regexp with alternatives.

Quantifiers

A simple regexp matches one character:

/\w/.match('Hello')  # => #<MatchData "H">

An added quantifier specifies how many matches are required or allowed:

Greedy, Lazy, or Possessive Matching

Quantifier matching may be greedy, lazy, or possessive:

More:

Groups and Captures

A simple regexp has (at most) one match:

re = /\d\d\d\d-\d\d-\d\d/
re.match('1943-02-04')      # => #<MatchData "1943-02-04">
re.match('1943-02-04').size # => 1
re.match('foo')             # => nil

Adding one or more pairs of parentheses, (subexpression), defines groups, which may result in multiple matched substrings, called captures:

re = /(\d\d\d\d)-(\d\d)-(\d\d)/
re.match('1943-02-04')      # => #<MatchData "1943-02-04" 1:"1943" 2:"02" 3:"04">
re.match('1943-02-04').size # => 4

The first capture is the entire matched string; the other captures are the matched substrings from the groups.

A group may have a quantifier:

re = /July 4(th)?/
re.match('July 4')   # => #<MatchData "July 4" 1:nil>
re.match('July 4th') # => #<MatchData "July 4th" 1:"th">

re = /(foo)*/
re.match('')       # => #<MatchData "" 1:nil>
re.match('foo')    # => #<MatchData "foo" 1:"foo">
re.match('foofoo') # => #<MatchData "foofoo" 1:"foo">

re = /(foo)+/
re.match('')       # => nil
re.match('foo')    # => #<MatchData "foo" 1:"foo">
re.match('foofoo') # => #<MatchData "foofoo" 1:"foo">

The returned MatchData object gives access to the matched substrings:

re = /(\d\d\d\d)-(\d\d)-(\d\d)/
md = re.match('1943-02-04')
# => #<MatchData "1943-02-04" 1:"1943" 2:"02" 3:"04">
md[0] # => "1943-02-04"
md[1] # => "1943"
md[2] # => "02"
md[3] # => "04"

Non-Capturing Groups

A group may be made non-capturing; it is still a group (and, for example, can have a quantifier), but its matching substring is not included among the captures.

A non-capturing group begins with ?: (inside the parentheses):

# Don't capture the year.
re = /(?:\d\d\d\d)-(\d\d)-(\d\d)/
md = re.match('1943-02-04') # => #<MatchData "1943-02-04" 1:"02" 2:"04">

Backreferences

A group match may also be referenced within the regexp itself; such a reference is called a backreference:

/[csh](..) [csh]\1 in/.match('The cat sat in the hat')
# => #<MatchData "cat sat in" 1:"at">

This table shows how each subexpression in the regexp above matches a substring in the target string:

| Subexpression in Regexp   | Matching Substring in Target String |
|---------------------------|-------------------------------------|
|       First '[csh]'       |            Character 'c'            |
|          '(..)'           |        First substring 'at'         |
|      First space ' '      |      First space character ' '      |
|       Second '[csh]'      |            Character 's'            |
| '\1' (backreference 'at') |        Second substring 'at'        |
|           ' in'           |            Substring ' in'          |

A regexp may contain any number of groups:

Named Captures

As seen above, a capture can be referred to by its number. A capture can also have a name, prefixed as ?<name> or ?'name', and the name (symbolized) may be used as an index in MatchData[]:

md = /\$(?<dollars>\d+)\.(?'cents'\d+)/.match("$3.67")
# => #<MatchData "$3.67" dollars:"3" cents:"67">
md[:dollars]  # => "3"
md[:cents]    # => "67"
# The capture numbers are still valid.
md[2]         # => "67"

When a regexp contains a named capture, there are no unnamed captures:

/\$(?<dollars>\d+)\.(\d+)/.match("$3.67")
# => #<MatchData "$3.67" dollars:"3">

A named group may be backreferenced as \k<name>:

/(?<vowel>[aeiou]).\k<vowel>.\k<vowel>/.match('ototomy')
# => #<MatchData "ototo" vowel:"o">

When (and only when) a regexp contains named capture groups and appears before the =~ operator, the captured substrings are assigned to local variables with corresponding names:

/\$(?<dollars>\d+)\.(?<cents>\d+)/ =~ '$3.67'
dollars # => "3"
cents   # => "67"

Method Regexp#named_captures returns a hash of the capture names and substrings; method Regexp#names returns an array of the capture names.

Atomic Grouping

A group may be made atomic with (?>subexpression).

This causes the subexpression to be matched independently of the rest of the expression, so that the matched substring becomes fixed for the remainder of the match, unless the entire subexpression must be abandoned and subsequently revisited.

In this way subexpression is treated as a non-divisible whole. Atomic grouping is typically used to optimise patterns to prevent needless backtracking .

Example (without atomic grouping):

/".*"/.match('"Quote"') # => #<MatchData "\"Quote\"">

Analysis:

  1. The leading subexpression " in the pattern matches the first character " in the target string.

  2. The next subexpression .* matches the next substring Quote“ (including the trailing double-quote).

  3. Now there is nothing left in the target string to match the trailing subexpression " in the pattern; this would cause the overall match to fail.

  4. The matched substring is backtracked by one position: Quote.

  5. The final subexpression " now matches the final substring ", and the overall match succeeds.

If subexpression .* is grouped atomically, the backtracking is disabled, and the overall match fails:

/"(?>.*)"/.match('"Quote"') # => nil

Atomic grouping can affect performance; see Atomic Group.

Subexpression Calls

As seen above, a backreference number (\n) or name (\k<name>) gives access to a captured substring; the corresponding regexp subexpression may also be accessed, via the number (\gn) or name (\g<name>):

/\A(?<paren>\(\g<paren>*\))*\z/.match('(())')
# ^1
#      ^2
#           ^3
#                 ^4
#      ^5
#           ^6
#                      ^7
#                       ^8
#                       ^9
#                           ^10

The pattern:

  1. Matches at the beginning of the string, i.e. before the first character.

  2. Enters a named group paren.

  3. Matches the first character in the string, '('.

  4. Calls the paren group again, i.e. recurses back to the second step.

  5. Re-enters the paren group.

  6. Matches the second character in the string, '('.

  7. Attempts to call paren a third time, but fails because doing so would prevent an overall successful match.

  8. Matches the third character in the string, ')'; marks the end of the second recursive call

  9. Matches the fourth character in the string, ')'.

  10. Matches the end of the string.

See Subexpression calls.

Conditionals

The conditional construct takes the form (?(cond)yes|no), where:

Examples:

re = /\A(foo)?(?(1)(T)|(F))\z/
re.match('fooT') # => #<MatchData "fooT" 1:"foo" 2:"T" 3:nil>
re.match('F')    # => #<MatchData "F" 1:nil 2:nil 3:"F">
re.match('fooF') # => nil
re.match('T')    # => nil

re = /\A(?<xyzzy>foo)?(?(<xyzzy>)(T)|(F))\z/
re.match('fooT') # => #<MatchData "fooT" xyzzy:"foo">
re.match('F')    # => #<MatchData "F" xyzzy:nil>
re.match('fooF') # => nil
re.match('T')    # => nil

Absence Operator

The absence operator is a special group that matches anything which does not match the contained subexpressions.

/(?~real)/.match('surrealist') # => #<MatchData "surrea">
/(?~real)ist/.match('surrealist') # => #<MatchData "ealist">
/sur(?~real)ist/.match('surrealist') # => nil

Unicode

Unicode Properties

The /\p{property_name}/ construct (with lowercase p) matches characters using a Unicode property name, much like a character class; property Alpha specifies alphabetic characters:

/\p{Alpha}/.match('a') # => #<MatchData "a">
/\p{Alpha}/.match('1') # => nil

A property can be inverted by prefixing the name with a caret character (^):

/\p{^Alpha}/.match('1') # => #<MatchData "1">
/\p{^Alpha}/.match('a') # => nil

Or by using \P (uppercase P):

/\P{Alpha}/.match('1') # => #<MatchData "1">
/\P{Alpha}/.match('a') # => nil

See Unicode Properties for regexps based on the numerous properties.

Some commonly-used properties correspond to POSIX bracket expressions:

These are also commonly used:

Unicode Character Categories

A Unicode character category name:

Examples:

/\p{lu}/                # => /\p{lu}/
/\p{LU}/                # => /\p{LU}/
/\p{Uppercase Letter}/  # => /\p{Uppercase Letter}/
/\p{Uppercase_Letter}/  # => /\p{Uppercase_Letter}/
/\p{UPPERCASE-LETTER}/  # => /\p{UPPERCASE-LETTER}/

Below are the Unicode character category abbreviations and names. Enumerations of characters in each category are at the links.

Letters:

Marks:

Numbers:

Punctuation:

Unicode Scripts and Blocks

Among the Unicode properties are:

POSIX Bracket Expressions

A POSIX bracket expression is also similar to a character class. These expressions provide a portable alternative to the above, with the added benefit of encompassing non-ASCII characters:

The POSIX bracket expressions:

Ruby also supports these (non-POSIX) bracket expressions:

Comments

A comment may be included in a regexp pattern using the (?#comment) construct, where comment is a substring that is to be ignored. arbitrary text ignored by the regexp engine:

/foo(?#Ignore me)bar/.match('foobar') # => #<MatchData "foobar">

The comment may not include an unescaped terminator character.

See also Extended Mode.

Modes

Each of these modifiers sets a mode for the regexp:

Any, all, or none of these may be applied.

Modifiers i, m, and x may be applied to subexpressions:

Example:

re = /(?i)te(?-i)st/
re.match('test') # => #<MatchData "test">
re.match('TEst') # => #<MatchData "TEst">
re.match('TEST') # => nil
re.match('teST') # => nil

re = /t(?i:e)st/
re.match('test') # => #<MatchData "test">
re.match('tEst') # => #<MatchData "tEst">
re.match('tEST') # => nil

Method Regexp#options returns an integer whose value showing the settings for case-insensitivity mode, multiline mode, and extended mode.

Case-Insensitive Mode

By default, a regexp is case-sensitive:

/foo/.match('FOO')  # => nil

Modifier i enables case-insensitive mode:

/foo/i.match('FOO')
# => #<MatchData "FOO">

Method Regexp#casefold? returns whether the mode is case-insensitive.

Multiline Mode

The multiline-mode in Ruby is what is commonly called a “dot-all mode”:

Unlike other languages, the modifier m does not affect the anchors ^ and $. These anchors always match at line-boundaries in Ruby.

Extended Mode

Modifier x enables extended mode, which means that:

In extended mode, whitespace and comments may be used to form a self-documented regexp.

Regexp not in extended mode (matches some Roman numerals):

pattern = '^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$'
re = /#{pattern}/
re.match('MCMXLIII') # => #<MatchData "MCMXLIII" 1:"CM" 2:"XL" 3:"III">

Regexp in extended mode:

pattern = <<-EOT
  ^                   # beginning of string
  M{0,3}              # thousands - 0 to 3 Ms
  (CM|CD|D?C{0,3})    # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 Cs),
                      #            or 500-800 (D, followed by 0 to 3 Cs)
  (XC|XL|L?X{0,3})    # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 Xs),
                      #        or 50-80 (L, followed by 0 to 3 Xs)
  (IX|IV|V?I{0,3})    # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 Is),
                      #        or 5-8 (V, followed by 0 to 3 Is)
  $                   # end of string
EOT
re = /#{pattern}/x
re.match('MCMXLIII') # => #<MatchData "MCMXLIII" 1:"CM" 2:"XL" 3:"III">

Interpolation Mode

Modifier o means that the first time a literal regexp with interpolations is encountered, the generated Regexp object is saved and used for all future evaluations of that literal regexp. Without modifier o, the generated Regexp is not saved, so each evaluation of the literal regexp generates a new Regexp object.

Without modifier o:

def letters; sleep 5; /[A-Z][a-z]/; end
words = %w[abc def xyz]
start = Time.now
words.each {|word| word.match(/\A[#{letters}]+\z/) }
Time.now - start # => 15.0174892

With modifier o:

start = Time.now
words.each {|word| word.match(/\A[#{letters}]+\z/o) }
Time.now - start # => 5.0010866

Note that if the literal regexp does not have interpolations, the o behavior is the default.

Encodings

By default, a regexp with only US-ASCII characters has US-ASCII encoding:

re = /foo/
re.source.encoding # => #<Encoding:US-ASCII>
re.encoding        # => #<Encoding:US-ASCII>

A regular expression containing non-US-ASCII characters is assumed to use the source encoding. This can be overridden with one of the following modifiers.

A regexp can be matched against a target string when either:

If a match between incompatible encodings is attempted an Encoding::CompatibilityError exception is raised.

Example:

re = eval("# encoding: ISO-8859-1\n/foo\\xff?/")
re.encoding                 # => #<Encoding:ISO-8859-1>
re =~ "foo".encode("UTF-8") # => 0
re =~ "foo\u0100"           # Raises Encoding::CompatibilityError

The encoding may be explicitly fixed by including Regexp::FIXEDENCODING in the second argument for Regexp.new:

# Regexp with encoding ISO-8859-1.
re = Regexp.new("a".force_encoding('iso-8859-1'), Regexp::FIXEDENCODING)
re.encoding  # => #<Encoding:ISO-8859-1>
# Target string with encoding UTF-8.
s = "a\u3042"
s.encoding   # => #<Encoding:UTF-8>
re.match(s)  # Raises Encoding::CompatibilityError.

Timeouts

When either a regexp source or a target string comes from untrusted input, malicious values could become a denial-of-service attack; to prevent such an attack, it is wise to set a timeout.

Regexp has two timeout values:

When regexp.timeout is nil, the timeout “falls through” to Regexp.timeout; when regexp.timeout is non-nil, that value controls timing out:

| regexp.timeout Value | Regexp.timeout Value |            Result           |
|----------------------|----------------------|-----------------------------|
|         nil          |          nil         |       Never times out.      |
|         nil          |         Float        | Times out in Float seconds. |
|        Float         |          Any         | Times out in Float seconds. |

Optimization

For certain values of the pattern and target string, matching time can grow polynomially or exponentially in relation to the input size; the potential vulnerability arising from this is the regular expression denial-of-service (ReDoS) attack.

Regexp matching can apply an optimization to prevent ReDoS attacks. When the optimization is applied, matching time increases linearly (not polynomially or exponentially) in relation to the input size, and a ReDoS attach is not possible.

This optimization is applied if the pattern meets these criteria:

You can use method Regexp.linear_time? to determine whether a pattern meets these criteria:

Regexp.linear_time?(/a*/)     # => true
Regexp.linear_time?('a*')     # => true
Regexp.linear_time?(/(a*)\1/) # => false

However, an untrusted source may not be safe even if the method returns true, because the optimization uses memoization (which may invoke large memory consumption).

References

Read (online PDF books):

Explore, test (interactive online editor):

Struct

Class Struct provides a convenient way to create a simple class that can store and fetch values.

This example creates a subclass of Struct, Struct::Customer; the first argument, a string, is the name of the subclass; the other arguments, symbols, determine the members of the new subclass.

Customer = Struct.new('Customer', :name, :address, :zip)
Customer.name       # => "Struct::Customer"
Customer.class      # => Class
Customer.superclass # => Struct

Corresponding to each member are two methods, a writer and a reader, that store and fetch values:

methods = Customer.instance_methods false
methods # => [:zip, :address=, :zip=, :address, :name, :name=]

An instance of the subclass may be created, and its members assigned values, via method ::new:

joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe # => #<struct Struct::Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=12345>

The member values may be managed thus:

joe.name    # => "Joe Smith"
joe.name = 'Joseph Smith'
joe.name    # => "Joseph Smith"

And thus; note that member name may be expressed as either a string or a symbol:

joe[:name]  # => "Joseph Smith"
joe[:name] = 'Joseph Smith, Jr.'
joe['name'] # => "Joseph Smith, Jr."

See Struct::new.

What’s Here

First, what’s elsewhere. Class Struct:

See also Data, which is a somewhat similar, but stricter concept for defining immutable value objects.

Here, class Struct provides methods that are useful for:

Methods for Creating a Struct Subclass

Methods for Querying

Methods for Comparing

Methods for Fetching

Methods for Assigning

Methods for Iterating

Methods for Converting

SocketError

SocketError is the error class for socket.

IPSocket

IPSocket is the super class of TCPSocket and UDPSocket.

UDPSocket

UDPSocket represents a UDP/IP socket.

TCPServer

TCPServer represents a TCP/IP server socket.

A simple TCP server may look like:

require 'socket'

server = TCPServer.new 2000 # Server bind to port 2000
loop do
  client = server.accept    # Wait for a client to connect
  client.puts "Hello !"
  client.puts "Time is #{Time.now}"
  client.close
end

A more usable server (serving multiple clients):

require 'socket'

server = TCPServer.new 2000
loop do
  Thread.start(server.accept) do |client|
    client.puts "Hello !"
    client.puts "Time is #{Time.now}"
    client.close
  end
end

TCPSocket

TCPSocket represents a TCP/IP client socket.

A simple client may look like:

require 'socket'

s = TCPSocket.new 'localhost', 2000

while line = s.gets # Read lines from socket
  puts line         # and print them
end

s.close             # close socket when done

StringIO

IO streams for strings, with access similar to IO; see IO.

About the Examples

Examples on this page assume that StringIO has been required:

require 'stringio'

StringScanner

No documentation available

Resolv 

Windows NT

IOError

Raised when an IO operation fails.

File.open("/etc/hosts") {|f| f << "example"}
  #=> IOError: not opened for writing

File.open("/etc/hosts") {|f| f.close; f.read }
  #=> IOError: closed stream

Note that some IO failures raise SystemCallErrors and these are not subclasses of IOError:

File.open("does/not/exist")
  #=> Errno::ENOENT: No such file or directory - does/not/exist

EOFError

Raised by some IO operations when reaching the end of file. Many IO methods exist in two forms,

one that returns nil when the end of file is reached, the other raises EOFError.

EOFError is a subclass of IOError.

file = File.open("/etc/hosts")
file.read
file.gets     #=> nil
file.readline #=> EOFError: end of file reached
file.close

PrettyPrint

This class implements a pretty printing algorithm. It finds line breaks and nice indentations for grouped structure.

By default, the class assumes that primitive elements are strings and each byte in the strings have single column in width. But it can be used for other situations by giving suitable arguments for some methods:

There are several candidate uses:

Bugs

Report any bugs at bugs.ruby-lang.org

References

Christian Lindig, Strictly Pretty, March 2000, lindig.github.io/papers/strictly-pretty-2000.pdf

Philip Wadler, A prettier printer, March 1998, homepages.inf.ed.ac.uk/wadler/topics/language-design.html#prettier

Author

Tanaka Akira <akr@fsij.org>

Resolv

Resolv is a thread-aware DNS resolver library written in Ruby. Resolv can handle multiple DNS requests concurrently without blocking the entire Ruby interpreter.

See also resolv-replace.rb to replace the libc resolver with Resolv.

Resolv can look up various DNS resources using the DNS module directly.

Examples:

p Resolv.getaddress "www.ruby-lang.org"
p Resolv.getname "210.251.121.214"

Resolv::DNS.open do |dns|
  ress = dns.getresources "www.ruby-lang.org", Resolv::DNS::Resource::IN::A
  p ress.map(&:address)
  ress = dns.getresources "ruby-lang.org", Resolv::DNS::Resource::IN::MX
  p ress.map { |r| [r.exchange.to_s, r.preference] }
end

Bugs

WeakRef

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)

ZeroDivisionError

Raised when attempting to divide an integer by 0.

42 / 0   #=> ZeroDivisionError: divided by 0

Note that only division by an exact 0 will raise the exception:

42 /  0.0   #=> Float::INFINITY
42 / -0.0   #=> -Float::INFINITY
0  /  0.0   #=> NaN

FloatDomainError

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

LocalJumpError

Raised when Ruby can’t yield as requested.

A typical scenario is attempting to yield when no block is given:

def call_block
  yield 42
end
call_block

raises the exception:

LocalJumpError: no block given (yield)

A more subtle example:

def get_me_a_return
  Proc.new { return 42 }
end
get_me_a_return.call

raises the exception:

LocalJumpError: unexpected return

ThreadGroup

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.

Thread

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 "What's 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 #=> "What's 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 "What's 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 }

To retrieve the last value of a thread, use value

thr = Thread.new { sleep 1; "Useful value" }
thr.value #=> "Useful value"

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 { sleep }
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.

Fiber-local vs. Thread-local

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

When an unhandled exception is raised inside a thread, it will terminate. By default, this exception will not propagate to other threads. The exception is stored and when another thread calls value or join, the exception will be re-raised in that thread.

t = Thread.new{ raise 'something went wrong' }
t.value #=> RuntimeError: something went wrong

An exception can be raised from outside the thread using the Thread#raise instance method, which takes the same parameters as Kernel#raise.

Setting Thread.abort_on_exception = true, Thread#abort_on_exception = true, or $DEBUG = true will cause a subsequent unhandled exception raised in a thread to be automatically re-raised in the main thread.

With the addition of the class method ::handle_interrupt, you can now handle exceptions asynchronously with threads.

Scheduling

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.

Previous Next
Search took: 8ms  ·  Total Results: 4418