Returns a copy of the receiver with leading and trailing whitespace removed; see Whitespace in Strings:
whitespace = "\x00\t\n\v\f\r " s = whitespace + 'abc' + whitespace s # => "\u0000\t\n\v\f\r abc\u0000\t\n\v\f\r " s.strip # => "abc"
Related: String#lstrip
, String#rstrip
.
This method verifies that there are no (obvious) ambiguities with the provided col_sep
and strip
parsing options. For example, if col_sep
and strip
were both equal to \t
, then there would be no clear way to parse the input.
A String object has an arbitrary sequence of bytes, typically representing text or binary data. A String object may be created using String::new
or as literals.
String
objects differ from Symbol
objects in that Symbol
objects are designed to be used as identifiers, instead of text or data.
You can create a String object explicitly with:
A string literal.
A string literal.
You can convert certain objects to Strings with:
Method String
.
Some String methods modify self
. Typically, a method whose name ends with !
modifies self
and returns self
; often a similarly named method (without the !
) returns a new string.
In general, if there exist both bang and non-bang version of method, the bang! mutates and the non-bang! does not. However, a method without a bang can also mutate, such as String#replace
.
These methods perform substitutions:
String#sub
: One substitution (or none); returns a new string.
String#sub!
: One substitution (or none); returns self
.
String#gsub
: Zero or more substitutions; returns a new string.
String#gsub!
: Zero or more substitutions; returns self
.
Each of these methods takes:
A first argument, pattern
(string or regexp), that specifies the substring(s) to be replaced.
Either of these:
A second argument, replacement
(string or hash), that determines the replacing string.
A block that will determine the replacing string.
The examples in this section mostly use methods String#sub
and String#gsub
; the principles illustrated apply to all four substitution methods.
Argument pattern
Argument pattern
is commonly a regular expression:
s = 'hello' s.sub(/[aeiou]/, '*')# => "h*llo" s.gsub(/[aeiou]/, '*') # => "h*ll*" s.gsub(/[aeiou]/, '')# => "hll" s.sub(/ell/, 'al') # => "halo" s.gsub(/xyzzy/, '*') # => "hello" 'THX1138'.gsub(/\d+/, '00') # => "THX00"
When pattern
is a string, all its characters are treated as ordinary characters (not as regexp special characters):
'THX1138'.gsub('\d+', '00') # => "THX1138"
String replacement
If replacement
is a string, that string will determine the replacing string that is to be substituted for the matched text.
Each of the examples above uses a simple string as the replacing string.
String replacement
may contain back-references to the pattern’s captures:
\n
(n a non-negative integer) refers to $n
.
\k<name>
refers to the named capture name
.
See regexp.rdoc for details.
Note that within the string replacement
, a character combination such as $&
is treated as ordinary text, and not as a special match variable. However, you may refer to some special match variables using these combinations:
\&
and \0
correspond to $&
, which contains the complete matched text.
\'
corresponds to $'
, which contains string after match.
\`
corresponds to $`
, which contains string before match.
+
corresponds to $+
, which contains last capture group.
See regexp.rdoc for details.
Note that \\
is interpreted as an escape, i.e., a single backslash.
Note also that a string literal consumes backslashes. See string literal for details about string literals.
A back-reference is typically preceded by an additional backslash. For example, if you want to write a back-reference \&
in replacement
with a double-quoted string literal, you need to write "..\\&.."
.
If you want to write a non-back-reference string \&
in replacement
, you need first to escape the backslash to prevent this method from interpreting it as a back-reference, and then you need to escape the backslashes again to prevent a string literal from consuming them: "..\\\\&.."
.
You may want to use the block form to avoid a lot of backslashes.
Hash replacement
If argument replacement
is a hash, and pattern
matches one of its keys, the replacing string is the value for that key:
h = {'foo' => 'bar', 'baz' => 'bat'} 'food'.sub('foo', h) # => "bard"
Note that a symbol key does not match:
h = {foo: 'bar', baz: 'bat'} 'food'.sub('foo', h) # => "d"
Block
In the block form, the current match string is passed to the block; the block’s return value becomes the replacing string:
s = '@' '1234'.gsub(/\d/) {|match| s.succ! } # => "ABCD"
Special match variables such as $1
, $2
, $`
, $&
, and $'
are set appropriately.
In class String, whitespace is defined as a contiguous sequence of characters consisting of any mixture of the following:
NL (null): "\x00"
, "\u0000"
.
HT (horizontal tab): "\x09"
, "\t"
.
LF (line feed): "\x0a"
, "\n"
.
VT (vertical tab): "\x0b"
, "\v"
.
FF (form feed): "\x0c"
, "\f"
.
CR (carriage return): "\x0d"
, "\r"
.
SP (space): "\x20"
, " "
.
Whitespace is relevant for these methods:
A slice of a string is a substring that is selected by certain criteria.
These instance methods make use of slicing:
String#[]
(also aliased as String#slice
) returns a slice copied from self
.
String#[]=
returns a copy of self
with a slice replaced.
String#slice!
returns self
with a slice removed.
Each of the above methods takes arguments that determine the slice to be copied or replaced.
The arguments have several forms. For string string
, the forms are:
string[index]
.
string[start, length]
.
string[range]
.
string[regexp, capture = 0]
.
string[substring]
.
string[index]
When non-negative integer argument index
is given, the slice is the 1-character substring found in self
at character offset index
:
'bar'[0] # => "b" 'bar'[2] # => "r" 'bar'[20] # => nil 'тест'[2] # => "с" 'こんにちは'[4] # => "は"
When negative integer index
is given, the slice begins at the offset given by counting backward from the end of self
:
'bar'[-3] # => "b" 'bar'[-1] # => "r" 'bar'[-20] # => nil
string[start, length]
When non-negative integer arguments start
and length
are given, the slice begins at character offset start
, if it exists, and continues for length
characters, if available:
'foo'[0, 2] # => "fo" 'тест'[1, 2] # => "ес" 'こんにちは'[2, 2] # => "にち" # Zero length. 'foo'[2, 0] # => "" # Length not entirely available. 'foo'[1, 200] # => "oo" # Start out of range. 'foo'[4, 2] # => nil
Special case: if start
is equal to the length of self
, the slice is a new empty string:
'foo'[3, 2] # => "" 'foo'[3, 200] # => ""
When negative start
and non-negative length
are given, the slice beginning is determined by counting backward from the end of self
, and the slice continues for length
characters, if available:
'foo'[-2, 2] # => "oo" 'foo'[-2, 200] # => "oo" # Start out of range. 'foo'[-4, 2] # => nil
When negative length
is given, there is no slice:
'foo'[1, -1] # => nil 'foo'[-2, -1] # => nil
string[range]
When Range
argument range
is given, creates a substring of string
using the indices in range
. The slice is then determined as above:
'foo'[0..1] # => "fo" 'foo'[0, 2] # => "fo" 'foo'[2...2] # => "" 'foo'[2, 0] # => "" 'foo'[1..200] # => "oo" 'foo'[1, 200] # => "oo" 'foo'[4..5] # => nil 'foo'[4, 2] # => nil 'foo'[-4..-3] # => nil 'foo'[-4, 2] # => nil 'foo'[3..4] # => "" 'foo'[3, 2] # => "" 'foo'[-2..-1] # => "oo" 'foo'[-2, 2] # => "oo" 'foo'[-2..197] # => "oo" 'foo'[-2, 200] # => "oo"
string[regexp, capture = 0]
When the Regexp argument regexp
is given, and the capture
argument is 0
, the slice is the first matching substring found in self
:
'foo'[/o/] # => "o" 'foo'[/x/] # => nil s = 'hello there' s[/[aeiou](.)\1/] # => "ell" s[/[aeiou](.)\1/, 0] # => "ell"
If argument capture
is given and not 0
, it should be either an capture group index (integer) or a capture group name (string or symbol); the slice is the specified capture (see Capturing at Regexp
):
s = 'hello there' s[/[aeiou](.)\1/, 1] # => "l" s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] # => "l" s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, :vowel] # => "e"
If an invalid capture group index is given, there is no slice. If an invalid capture group name is given, IndexError
is raised.
string[substring]
When the single String argument substring
is given, returns the substring from self
if found, otherwise nil
:
'foo'['oo'] # => "oo" 'foo'['xx'] # => nil
First, what’s elsewhere. Class String:
Inherits from class Object.
Includes module Comparable.
Here, class String provides methods that are useful for:
::new
: Returns a new string.
::try_convert
: Returns a new string created from a given object.
String
+@
: Returns a string that is not frozen: self
, if not frozen; self.dup
otherwise.
-@
: Returns a string that is frozen: self
, if already frozen; self.freeze
otherwise.
freeze
: Freezes self
, if not already frozen; returns self
.
Counts
empty?
: Returns true
if self.length
is zero; false
otherwise.
bytesize
: Returns the count of bytes.
count
: Returns the count of substrings matching given strings.
Substrings
=~
: Returns the index of the first substring that matches a given Regexp
or other object; returns nil
if no match is found.
index
: Returns the index of the first occurrence of a given substring; returns nil
if none found.
rindex
: Returns the index of the last occurrence of a given substring; returns nil
if none found.
include?
: Returns true
if the string contains a given substring; false
otherwise.
match
: Returns a MatchData
object if the string matches a given Regexp
; nil
otherwise.
match?
: Returns true
if the string matches a given Regexp
; false
otherwise.
start_with?
: Returns true
if the string begins with any of the given substrings.
end_with?
: Returns true
if the string ends with any of the given substrings.
Encodings
encoding
: Returns the Encoding
object that represents the encoding of the string.
unicode_normalized?
: Returns true
if the string is in Unicode normalized form; false
otherwise.
valid_encoding?
: Returns true
if the string contains only characters that are valid for its encoding.
ascii_only?
: Returns true
if the string has only ASCII characters; false
otherwise.
Other
sum
: Returns a basic checksum for the string: the sum of each byte.
hash
: Returns the integer hash code.
==
, ===
: Returns true
if a given other string has the same content as self
.
eql?
: Returns true
if the content is the same as the given other string.
<=>
: Returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than self
.
casecmp
: Ignoring case, returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than self
.
casecmp?
: Returns true
if the string is equal to a given string after Unicode case folding; false
otherwise.
Each of these methods modifies self
.
Insertion
insert
: Returns self
with a given string inserted at a given offset.
<<
: Returns self
concatenated with a given string or integer.
Substitution
sub!
: Replaces the first substring that matches a given pattern with a given replacement string; returns self
if any changes, nil
otherwise.
gsub!
: Replaces each substring that matches a given pattern with a given replacement string; returns self
if any changes, nil
otherwise.
succ!
, next!
: Returns self
modified to become its own successor.
replace
: Returns self
with its entire content replaced by a given string.
reverse!
: Returns self
with its characters in reverse order.
setbyte
: Sets the byte at a given integer offset to a given value; returns the argument.
tr!
: Replaces specified characters in self
with specified replacement characters; returns self
if any changes, nil
otherwise.
tr_s!
: Replaces specified characters in self
with specified replacement characters, removing duplicates from the substrings that were modified; returns self
if any changes, nil
otherwise.
Casing
capitalize!
: Upcases the initial character and downcases all others; returns self
if any changes, nil
otherwise.
downcase!
: Downcases all characters; returns self
if any changes, nil
otherwise.
upcase!
: Upcases all characters; returns self
if any changes, nil
otherwise.
swapcase!
: Upcases each downcase character and downcases each upcase character; returns self
if any changes, nil
otherwise.
Encoding
encode!
: Returns self
with all characters transcoded from one given encoding into another.
unicode_normalize!
: Unicode-normalizes self
; returns self
.
scrub!
: Replaces each invalid byte with a given character; returns self
.
force_encoding
: Changes the encoding to a given encoding; returns self
.
Deletion
clear
: Removes all content, so that self
is empty; returns self
.
slice!
, []=
: Removes a substring determined by a given index, start/length, range, regexp, or substring.
squeeze!
: Removes contiguous duplicate characters; returns self
.
delete!
: Removes characters as determined by the intersection of substring arguments.
lstrip!
: Removes leading whitespace; returns self
if any changes, nil
otherwise.
rstrip!
: Removes trailing whitespace; returns self
if any changes, nil
otherwise.
strip!
: Removes leading and trailing whitespace; returns self
if any changes, nil
otherwise.
chomp!
: Removes trailing record separator, if found; returns self
if any changes, nil
otherwise.
chop!
: Removes trailing newline characters if found; otherwise removes the last character; returns self
if any changes, nil
otherwise.
Each of these methods returns a new String based on self
, often just a modified copy of self
.
Extension
*
: Returns the concatenation of multiple copies of self
,
+
: Returns the concatenation of self
and a given other string.
center
: Returns a copy of self
centered between pad substring.
concat
: Returns the concatenation of self
with given other strings.
prepend
: Returns the concatenation of a given other string with self
.
ljust
: Returns a copy of self
of a given length, right-padded with a given other string.
rjust
: Returns a copy of self
of a given length, left-padded with a given other string.
Encoding
b
: Returns a copy of self
with ASCII-8BIT encoding.
scrub
: Returns a copy of self
with each invalid byte replaced with a given character.
unicode_normalize
: Returns a copy of self
with each character Unicode-normalized.
encode
: Returns a copy of self
with all characters transcoded from one given encoding into another.
Substitution
dump
: Returns a copy of self
with all non-printing characters replaced by xHH notation and all special characters escaped.
undump
: Returns a copy of self
with all \xNN
notation replace by \uNNNN
notation and all escaped characters unescaped.
sub
: Returns a copy of self
with the first substring matching a given pattern replaced with a given replacement string;.
gsub
: Returns a copy of self
with each substring that matches a given pattern replaced with a given replacement string.
succ
, next
: Returns the string that is the successor to self
.
reverse
: Returns a copy of self
with its characters in reverse order.
tr
: Returns a copy of self
with specified characters replaced with specified replacement characters.
tr_s
: Returns a copy of self
with specified characters replaced with specified replacement characters, removing duplicates from the substrings that were modified.
%
: Returns the string resulting from formatting a given object into self
Casing
capitalize
: Returns a copy of self
with the first character upcased and all other characters downcased.
downcase
: Returns a copy of self
with all characters downcased.
upcase
: Returns a copy of self
with all characters upcased.
swapcase
: Returns a copy of self
with all upcase characters downcased and all downcase characters upcased.
Deletion
delete
: Returns a copy of self
with characters removed
delete_prefix
: Returns a copy of self
with a given prefix removed.
delete_suffix
: Returns a copy of self
with a given suffix removed.
lstrip
: Returns a copy of self
with leading whitespace removed.
rstrip
: Returns a copy of self
with trailing whitespace removed.
strip
: Returns a copy of self
with leading and trailing whitespace removed.
chomp
: Returns a copy of self
with a trailing record separator removed, if found.
chop
: Returns a copy of self
with trailing newline characters or the last character removed.
squeeze
: Returns a copy of self
with contiguous duplicate characters removed.
[]
, slice
: Returns a substring determined by a given index, start/length, or range, or string.
byteslice
: Returns a substring determined by a given index, start/length, or range.
chr
: Returns the first character.
Duplication
to_s
, $to_str: If self
is a subclass of String, returns self
copied into a String; otherwise, returns self
.
Each of these methods converts the contents of self
to a non-String.
Characters, Bytes, and Clusters
bytes
: Returns an array of the bytes in self
.
chars
: Returns an array of the characters in self
.
codepoints
: Returns an array of the integer ordinals in self
.
getbyte
: Returns an integer byte as determined by a given index.
grapheme_clusters
: Returns an array of the grapheme clusters in self
.
Splitting
lines
: Returns an array of the lines in self
, as determined by a given record separator.
partition
: Returns a 3-element array determined by the first substring that matches a given substring or regexp,
rpartition
: Returns a 3-element array determined by the last substring that matches a given substring or regexp,
split
: Returns an array of substrings determined by a given delimiter – regexp or string – or, if a block given, passes those substrings to the block.
Matching
scan
: Returns an array of substrings matching a given regexp or string, or, if a block given, passes each matching substring to the block.
unpack
: Returns an array of substrings extracted from self
according to a given format.
unpack1
: Returns the first substring extracted from self
according to a given format.
Numerics
hex
: Returns the integer value of the leading characters, interpreted as hexadecimal digits.
oct
: Returns the integer value of the leading characters, interpreted as octal digits.
ord
: Returns the integer ordinal of the first character in self
.
to_i
: Returns the integer value of leading characters, interpreted as an integer.
to_f
: Returns the floating-point value of leading characters, interpreted as a floating-point number.
Strings and Symbols
inspect
: Returns copy of self
, enclosed in double-quotes, with special characters escaped.
each_byte
: Calls the given block with each successive byte in self
.
each_char
: Calls the given block with each successive character in self
.
each_codepoint
: Calls the given block with each successive integer codepoint in self
.
each_grapheme_cluster
: Calls the given block with each successive grapheme cluster in self
.
each_line
: Calls the given block with each successive line in self
, as determined by a given record separator.
upto
: Calls the given block with each string value returned by successive calls to succ
.
IO streams for strings, with access similar to IO
; see IO
.
Examples on this page assume that StringIO has been required:
require 'stringio'
StringScanner
provides for lexical scanning operations on a String
. Here is an example of its usage:
require 'strscan' s = StringScanner.new('This is an example string') s.eos? # -> false p s.scan(/\w+/) # -> "This" p s.scan(/\w+/) # -> nil p s.scan(/\s+/) # -> " " p s.scan(/\s+/) # -> nil p s.scan(/\w+/) # -> "is" s.eos? # -> false p s.scan(/\s+/) # -> " " p s.scan(/\w+/) # -> "an" p s.scan(/\s+/) # -> " " p s.scan(/\w+/) # -> "example" p s.scan(/\s+/) # -> " " p s.scan(/\w+/) # -> "string" s.eos? # -> true p s.scan(/\s+/) # -> nil p s.scan(/\w+/) # -> nil
Scanning a string means remembering the position of a scan pointer, which is just an index. The point of scanning is to move forward a bit at a time, so matches are sought after the scan pointer; usually immediately after it.
Given the string “test string”, here are the pertinent scan pointer positions:
t e s t s t r i n g 0 1 2 ... 1 0
When you scan
for a pattern (a regular expression), the match must occur at the character after the scan pointer. If you use scan_until
, then the match can occur anywhere after the scan pointer. In both cases, the scan pointer moves just beyond the last character of the match, ready to scan again from the next character onwards. This is demonstrated by the example above.
Method
Categories There are other methods besides the plain scanners. You can look ahead in the string without actually scanning. You can access the most recent match. You can modify the string being scanned, reset or terminate the scanner, find out or change the position of the scan pointer, skip ahead, and so on.
beginning_of_line?
(#bol?
)
Data
There are aliases to several of the methods.
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
).
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.
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.
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.
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
.
First, what’s elsewhere. Class Struct:
Inherits from class Object.
Includes module Enumerable, which provides dozens of additional methods.
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:
Struct
Subclass ::new
: Returns a new subclass of Struct.
==
: Returns whether a given object is equal to self
, using ==
to compare member values.
eql?
: Returns whether a given object is equal to self
, using eql?
to compare member values.
[]
: Returns the value associated with a given member name.
to_a
, values
, deconstruct
: Returns the member values in self
as an array.
deconstruct_keys
: Returns a hash of the name/value pairs for given member names.
dig
: Returns the object in nested objects that is specified by a given member name and additional arguments.
members
: Returns an array of the member names.
select
, filter
: Returns an array of member values from self
, as selected by the given block.
values_at
: Returns an array containing values for given member names.
[]=
: Assigns a given value to a given member name.
each
: Calls a given block with each member name.
each_pair
: Calls a given block with each member name/value pair.
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
Raised in case of a stack overflow.
def me_myself_and_i me_myself_and_i end me_myself_and_i
raises the exception:
SystemStackError: stack level too deep
A custom InputMethod class used by XMP
for evaluating string io.
Acts like a StringIO
with reduced API, but without having to require that class.
AbstractSyntaxTree
provides methods to parse Ruby code into abstract syntax trees. The nodes in the tree are instances of RubyVM::AbstractSyntaxTree::Node
.
This module is MRI specific as it exposes implementation details of the MRI abstract syntax tree.
This module is experimental and its API is not stable, therefore it might change without notice. As examples, the order of children nodes is not guaranteed, the number of children nodes might change, there is no way to access children nodes by name, etc.
If you are looking for a stable API or an API working under multiple Ruby implementations, consider using the parser gem or Ripper
. If you would like to make RubyVM::AbstractSyntaxTree
stable, please join the discussion at bugs.ruby-lang.org/issues/14844.
A base class for objects representing a C structure
Wrapper for arrays within a struct
A pointer to a C structure
Psych::Stream
is a streaming YAML
emitter. It will not buffer your YAML
, but send it straight to an IO
.
Here is an example use:
stream = Psych::Stream.new($stdout) stream.start stream.push({:foo => 'bar'}) stream.finish
YAML
will be immediately emitted to $stdout with no buffering.
Psych::Stream#start
will take a block and ensure that Psych::Stream#finish
is called, so you can do this form:
stream = Psych::Stream.new($stdout) stream.start do |em| em.push(:foo => 'bar') end
Subclass of Zlib::Error
When zlib returns a Z_STREAM_END is return if the end of the compressed data has been reached and all uncompressed out put has been produced.
Subclass of Zlib::Error
When zlib returns a Z_STREAM_ERROR, usually if the stream state was inconsistent.
Zlib::ZStream
is the abstract class for the stream which handles the compressed data. The operations are defined in the subclasses: Zlib::Deflate
for compression, and Zlib::Inflate
for decompression.
An instance of Zlib::ZStream
has one stream (struct zstream in the source) and two variable-length buffers which associated to the input (next_in) of the stream and the output (next_out) of the stream. In this document, “input buffer” means the buffer for input, and “output buffer” means the buffer for output.
Data
input into an instance of Zlib::ZStream
are temporally stored into the end of input buffer, and then data in input buffer are processed from the beginning of the buffer until no more output from the stream is produced (i.e. until avail_out
> 0 after processing). During processing, output buffer is allocated and expanded automatically to hold all output data.
Some particular instance methods consume the data in output buffer and return them as a String
.
Here is an ascii art for describing above:
+================ an instance of Zlib::ZStream ================+ || || || +--------+ +-------+ +--------+ || || +--| output |<---------|zstream|<---------| input |<--+ || || | | buffer | next_out+-------+next_in | buffer | | || || | +--------+ +--------+ | || || | | || +===|======================================================|===+ | | v | "output data" "input data"
If an error occurs during processing input buffer, an exception which is a subclass of Zlib::Error
is raised. At that time, both input and output buffer keep their conditions at the time when the error occurs.
Method
Catalogue Many of the methods in this class are fairly low-level and unlikely to be of interest to users. In fact, users are unlikely to use this class directly; rather they will be interested in Zlib::Inflate
and Zlib::Deflate
.
The higher level methods are listed below.
Zlib::GzipWriter
is a class for writing gzipped files. GzipWriter
should be used with an instance of IO
, or IO-like, object.
Following two example generate the same result.
Zlib::GzipWriter.open('hoge.gz') do |gz| gz.write 'jugemu jugemu gokou no surikire...' end File.open('hoge.gz', 'w') do |f| gz = Zlib::GzipWriter.new(f) gz.write 'jugemu jugemu gokou no surikire...' gz.close end
To make like gzip(1) does, run following:
orig = 'hoge.txt' Zlib::GzipWriter.open('hoge.gz') do |gz| gz.mtime = File.mtime(orig) gz.orig_name = orig gz.write IO.binread(orig) end
NOTE: Due to the limitation of Ruby’s finalizer, you must explicitly close GzipWriter
objects by Zlib::GzipWriter#close
etc. Otherwise, GzipWriter
will be not able to write the gzip footer and will generate a broken gzip file.