class RubyVM::InstructionSequence

The InstructionSequence class represents a compiled sequence of instructions for the Virtual Machine used in MRI. Not all implementations of Ruby may implement this class, and for the implementations that implement it, the methods defined and behavior of the methods can change in any version.

With it, you can get a handle to the instructions that make up a method or a proc, compile strings of Ruby code down to VM instructions, and disassemble instruction sequences to strings for easy inspection. It is mostly useful if you want to learn how YARV works, but it also lets you control various settings for the Ruby iseq compiler.

You can find the source for the VM instructions in insns.def in the Ruby source.

The instruction sequence results will almost certainly change as Ruby changes, so example output in this documentation may be different from what you see.

Of course, this class is MRI specific.

Public Instance Methods

absolute_path

() → String?

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 72
def absolute_path: () -> String?

Returns the absolute path of this instruction sequence.

nil if the iseq was evaluated from a string.

For example, using ::compile_file:

# /tmp/method.rb
def hello
  puts "hello, world"
end

# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.absolute_path #=> /tmp/method.rb

base_label

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 98
def base_label: () -> String

Returns the base label of this instruction sequence.

For example, using irb:

iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.base_label
#=> "<compiled>"

Using ::compile_file:

# /tmp/method.rb
def hello
  puts "hello, world"
end

# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.base_label #=> <main>

disasm

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 118
def disasm: () -> String

Returns the instruction sequence as a String in human readable form.

puts RubyVM::InstructionSequence.compile('1 + 2').disasm

Produces:

== disasm: <RubyVM::InstructionSequence:<compiled>@<compiled>>==========
0000 trace            1                                               (   1)
0002 putobject        1
0004 putobject        2
0006 opt_plus         <ic:1>
0008 leave

disassemble

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 134
def disassemble: () -> String

Returns the instruction sequence as a String in human readable form.

puts RubyVM::InstructionSequence.compile('1 + 2').disasm

Produces:

== disasm: <RubyVM::InstructionSequence:<compiled>@<compiled>>==========
0000 trace            1                                               (   1)
0002 putobject        1
0004 putobject        2
0006 opt_plus         <ic:1>
0008 leave

each_child

() → RubyVM::InstructionSequence

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 143
def each_child: () -> RubyVM::InstructionSequence

Iterate all direct child instruction sequences. Iteration order is implementation/version defined so that people should not rely on the order.

eval

() → untyped

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 153
def eval: () -> untyped

Evaluates the instruction sequence and returns the result.

RubyVM::InstructionSequence.compile("1 + 2").eval #=> 3

first_lineno

() → Integer

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 169
def first_lineno: () -> Integer

Returns the number of the first source line where the instruction sequence was loaded from.

For example, using irb:

iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.first_lineno
#=> 1

inspect

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 178
def inspect: () -> String

Returns a human-readable string representation of this instruction sequence, including the label and path.

label

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 207
def label: () -> String

Returns the label of this instruction sequence.

<main> if it’s at the top level, <compiled> if it was evaluated from a string.

For example, using irb:

iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.label
#=> "<compiled>"

Using ::compile_file:

# /tmp/method.rb
def hello
  puts "hello, world"
end

# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.label #=> <main>

path

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 235
def path: () -> String

Returns the path of this instruction sequence.

<compiled> if the iseq was evaluated from a string.

For example, using irb:

iseq = RubyVM::InstructionSequence.compile('num = 1 + 2')
#=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
iseq.path
#=> "<compiled>"

Using ::compile_file:

# /tmp/method.rb
def hello
  puts "hello, world"
end

# in irb
> iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb')
> iseq.path #=> /tmp/method.rb

script_lines

() → Array[String]?

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 247
def script_lines: () -> Array[String]?

It returns recorded script lines if it is available. The script lines are not limited to the iseq range, but are entire lines of the source file.

Note that this is an API for ruby internal use, debugging, and research. Do not use this for any other purpose. The compatibility is not guaranteed.

to_a

() → Array[untyped]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 347
def to_a: () -> Array[untyped]

Returns an Array with 14 elements representing the instruction sequence with the following data:

magic: A string identifying the data format. <strong>Always YARVInstructionSequence/SimpleDataFormat.</strong>
major_version: The major version of the instruction sequence.
minor_version: The minor version of the instruction sequence.
format_type: A number identifying the data format. Always 1.
misc: A hash containing:

<code>:arg_size</code>

: the total number of arguments taken by the method or the block (0 if iseq doesn’t represent a method or block)

<code>:local_size</code>

: the number of local variables + 1

<code>:stack_max</code>

: used in calculating the stack depth at which a SystemStackError is thrown.

label : The name of the context (block, method, class, module, etc.) that this instruction sequence belongs to.

<code><main></code> if it's at the top level, <code><compiled></code> if
it was evaluated from a string.

path : The relative path to the Ruby file where the instruction sequence was loaded from.

<code><compiled></code> if the iseq was evaluated from a string.

absolute_path : The absolute path to the Ruby file where the instruction sequence was loaded from.

`nil` if the iseq was evaluated from a string.

first_lineno : The number of the first source line where the instruction sequence was loaded from.

type: The type of the instruction sequence.

Valid values are <code>:top</code>, <code>:method</code>,
<code>:block</code>, <code>:class</code>, <code>:rescue</code>,
<code>:ensure</code>, <code>:eval</code>, <code>:main</code>, and `plain`.

locals: An array containing the names of all arguments and local variables as symbols.
params: An Hash object containing parameter information.

More info about these values can be found in <code>vm_core.h</code>.

catch_table: A list of exceptions and control flow operators (rescue, next, redo, break, etc.).
bytecode: An array of arrays containing the instruction names and operands that make up the body of the instruction sequence.

Note that this format is MRI specific and version dependent.

to_binary

() → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 364
def to_binary: () -> String

Returns serialized iseq binary format data as a String object. A corresponding iseq object is created by RubyVM::InstructionSequence.load_from_binary() method.

String extra_data will be saved with binary data. You can access this data with RubyVM::InstructionSequence.load_from_binary_extra_data(binary).

Note that the translated binary data is not portable. You can not move this binary data to another machine. You can not use the binary data which is created by another version/another architecture of Ruby.

trace_points

() → Array[untyped]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/core/ruby_vm.rbs, line 373
def trace_points: () -> Array[untyped]

Return trace points in the instruction sequence. Return an array of [line, event_symbol] pair.