[ci skip] More docs for InstructionSequence.compile

This commit documents that you can also pass a `File` object to
`RubyVM::InstructionSequence.compile`, instead of a string, and this
will behave in a similar way to
`RubyVM::InstructionSequence.compile_file`

e.g.

```
❯ ./ruby -e "puts RubyVM::InstructionSequence.compile(File.open('test.rb')).disasm"
== disasm: #<ISeq:<compiled>@<compiled>:1 (1,0)-(2,21)>
local table (size: 1, argc: 0 [opts: 0, rest: -1, post: 0, block: -1, kw: -1@-1, kwrest: -1])
[ 1] name@0
0000 putstring                              "Ruby"                    (   1)[Li]
0002 setlocal_WC_0                          name@0
0004 putself                                                          (   2)[Li]
0005 putobject                              "Hello, "
0007 getlocal_WC_0                          name@0
0009 dup
0010 objtostring                            <calldata!mid:to_s, argc:0, FCALL|ARGS_SIMPLE>
0012 anytostring
0013 concatstrings                          2
0015 opt_send_without_block                 <calldata!mid:puts, argc:1, FCALL|ARGS_SIMPLE>
0017 leave

~/git/ruby master* ≡ ⇡
❯ ./ruby -e "puts RubyVM::InstructionSequence.compile(File.open('test.rb').read).disasm"
== disasm: #<ISeq:<compiled>@<compiled>:1 (1,0)-(2,21)>
local table (size: 1, argc: 0 [opts: 0, rest: -1, post: 0, block: -1, kw: -1@-1, kwrest: -1])
[ 1] name@0
0000 putstring                              "Ruby"                    (   1)[Li]
0002 setlocal_WC_0                          name@0
0004 putself                                                          (   2)[Li]
0005 putobject                              "Hello, "
0007 getlocal_WC_0                          name@0
0009 dup
0010 objtostring                            <calldata!mid:to_s, argc:0, FCALL|ARGS_SIMPLE>
0012 anytostring
0013 concatstrings                          2
0015 opt_send_without_block                 <calldata!mid:puts, argc:1, FCALL|ARGS_SIMPLE>
0017 leave
```

This is explicitly allowed by this code path in
`rb_iseq_compile_with_option` so we should document it.

```
    if (RB_TYPE_P(src, T_FILE)) {
        parse = rb_parser_compile_file_path;
    }
    else {
        parse = rb_parser_compile_string_path;
        StringValue(src);
    }
```
This commit is contained in:
Matt Valentine-House committed 2023-10-02 12:31:34 +01:00
1 parent 4da04d5f43
commit b6390a21eb
1 file changed
+6 -2
+6 -2
View File
@@ -1334,8 +1334,8 @@ rb_iseqw_new(const rb_iseq_t *iseq)
* InstructionSequence.compile(source[, file[, path[, line[, options]]]]) -> iseq
* InstructionSequence.new(source[, file[, path[, line[, options]]]]) -> iseq
*
* Takes +source+, a String of Ruby code and compiles it to an
* InstructionSequence.
* Takes +source+, which can be a string of Ruby code, or an open +File+ object.
* that contains Ruby source code.
*
* Optionally takes +file+, +path+, and +line+ which describe the file path,
* real path and first line number of the ruby code in +source+ which are
@@ -1357,6 +1357,10 @@ rb_iseqw_new(const rb_iseq_t *iseq)
* RubyVM::InstructionSequence.compile(File.read(path), path, File.expand_path(path))
* #=> <RubyVM::InstructionSequence:<compiled>@test.rb:1>
*
* file = File.open("test.rb")
* RubyVM::InstructionSequence.compile(file)
* #=> <RubyVM::InstructionSequence:<compiled>@<compiled>:1>
*
* path = File.expand_path("test.rb")
* RubyVM::InstructionSequence.compile(File.read(path), path, path)
* #=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>