file:line or file:line: in
`method'.
The optional _start_ parameter determines the number of initial stack
entries to omit from the top of the stack.
A second optional +length+ parameter can be used to limit how many entries
are returned from the stack.
Returns +nil+ if _start_ is greater than the size of
current execution stack.
Optionally you can pass a range, which will return an array containing the
entries within the specified range.
def a(skip)
caller(skip)
end
def b(skip)
a(skip)
end
def c(skip)
b(skip)
end
c(0) #=> ["prog:2:in `a'", "prog:5:in `b'", "prog:8:in `c'", "prog:10:in `true if yield would execute a
block in the current context. The iterator? form
is mildly deprecated.
def try
if block_given?
yield
else
"no block"
end
end
try #=> "no block"
try { "hello" } #=> "hello"
try do "hello" end #=> "hello";T; [o;=
;>I"
overload;F;?0;;;@0;:I"block_given?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@;![ ;"I"@return [Boolean];T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"Returns true if yield would execute a
block in the current context. The iterator? form
is mildly deprecated.
def try
if block_given?
yield
else
"no block"
end
end
try #=> "no block"
try { "hello" } #=> "hello"
try do "hello" end #=> "hello"
@overload block_given?
@return [Boolean];T;#0;$@;.F;/o;0;1T;2i ;3i ;Bi ;%@h;9I"$static VALUE
rb_f_block_given_p(VALUE _)
{
rb_execution_context_t *ec = GET_EC();
rb_control_frame_t *cfp = ec->cfp;
cfp = vm_get_ruby_level_caller_cfp(ec, RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp));
return RBOOL(cfp != NULL && VM_CF_BLOCK_HANDLER(cfp) != VM_BLOCK_HANDLER_NONE);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#catch;F;7[[@90;[[@Ci/ ;T;:
catch;0; [ ; { ; IC; "+catch+ executes its block. If +throw+ is not called, the block executes
normally, and +catch+ returns the value of the last expression evaluated.
catch(1) { 123 } # => 123
If throw(tag2, val) is called, Ruby searches up its stack for
a +catch+ block whose +tag+ has the same +object_id+ as _tag2_. When found,
the block stops executing and returns _val_ (or +nil+ if no second argument
was given to +throw+).
catch(1) { throw(1, 456) } # => 456
catch(1) { throw(1) } # => nil
When +tag+ is passed as the first argument, +catch+ yields it as the
parameter of the block.
catch(1) {|x| x + 2 } # => 3
When no +tag+ is given, +catch+ yields a new unique object (as from
+Object.new+) as the block parameter. This object can then be used as the
argument to +throw+, and will match the correct +catch+ block.
catch do |obj_A|
catch do |obj_B|
throw(obj_B, 123)
puts "This puts is not reached"
end
puts "This puts is displayed"
456
end
# => 456
catch do |obj_A|
catch do |obj_B|
throw(obj_A, 123)
puts "This puts is still not reached"
end
puts "Now this puts is also not reached"
456
end
# => 123
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"catch([tag]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"tag;T;$@o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@;![ ;"I""@yield [tag]
@return [Object];T;#0;$@;.F;Bi ;C0;7[[I"
[tag];T0;$@;![ ;"I"+catch+ executes its block. If +throw+ is not called, the block executes
normally, and +catch+ returns the value of the last expression evaluated.
catch(1) { 123 } # => 123
If throw(tag2, val) is called, Ruby searches up its stack for
a +catch+ block whose +tag+ has the same +object_id+ as _tag2_. When found,
the block stops executing and returns _val_ (or +nil+ if no second argument
was given to +throw+).
catch(1) { throw(1, 456) } # => 456
catch(1) { throw(1) } # => nil
When +tag+ is passed as the first argument, +catch+ yields it as the
parameter of the block.
catch(1) {|x| x + 2 } # => 3
When no +tag+ is given, +catch+ yields a new unique object (as from
+Object.new+) as the block parameter. This object can then be used as the
argument to +throw+, and will match the correct +catch+ block.
catch do |obj_A|
catch do |obj_B|
throw(obj_B, 123)
puts "This puts is not reached"
end
puts "This puts is displayed"
456
end
# => 456
catch do |obj_A|
catch do |obj_B|
throw(obj_A, 123)
puts "This puts is still not reached"
end
puts "Now this puts is also not reached"
456
end
# => 123
@overload catch([tag])
@yield [tag]
@return [Object];T;#0;$@;.F;/o;0;1T;2i;3i- ;%@h;9I"static VALUE
rb_f_catch(int argc, VALUE *argv, VALUE self)
{
VALUE tag = rb_check_arity(argc, 0, 1) ? argv[0] : rb_obj_alloc(rb_cObject);
return rb_catch_obj(tag, catch_i, 0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#throw;F;7[[@90;[[@Ci;T;:
throw;0; [ ; { ; IC; "$Transfers control to the end of the active +catch+ block
waiting for _tag_. Raises +UncaughtThrowError+ if there
is no +catch+ block for the _tag_. The optional second
parameter supplies a return value for the +catch+ block,
which otherwise defaults to +nil+. For examples, see
Kernel::catch.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"throw(tag [, obj]);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@2;.F;Bi ;C0;7[[I"tag[, obj];T0;$@2;![ ;"I"CTransfers control to the end of the active +catch+ block
waiting for _tag_. Raises +UncaughtThrowError+ if there
is no +catch+ block for the _tag_. The optional second
parameter supplies a return value for the +catch+ block,
which otherwise defaults to +nil+. For examples, see
Kernel::catch.
@overload throw(tag [, obj]);T;#0;$@2;.F;/o;0;1T;2i;3i;%@h;9I"static VALUE
rb_f_throw(int argc, VALUE *argv, VALUE _)
{
VALUE tag, value;
rb_scan_args(argc, argv, "11", &tag, &value);
rb_throw_obj(tag, value);
UNREACHABLE_RETURN(Qnil);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#loop;F;7[ ;[[@Ci;T;: loop;0; [ ; { ; IC; "Repeatedly executes the block.
If no block is given, an enumerator is returned instead.
loop do
print "Input: "
line = gets
break if !line or line =~ /^qQ/
# ...
end
StopIteration raised in the block breaks the loop. In this case,
loop returns the "result" value stored in the exception.
enum = Enumerator.new { |y|
y << "one"
y << "two"
:ok
}
result = loop {
puts enum.next
} #=> :ok
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" loop;T; IC; " ;T; [o;A
;>I"
yield;F;?I"[];T;0;@0;$@K;![ ;"I"@yield [];T;#0;$@K;.F;Bi ;C0;7[ ;$@Ko;=
;>I"
overload;F;?0;;;@0;:I" loop;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@K;.F;Bi ;C0;7[ ;$@K;![ ;"I"Repeatedly executes the block.
If no block is given, an enumerator is returned instead.
loop do
print "Input: "
line = gets
break if !line or line =~ /^qQ/
# ...
end
StopIteration raised in the block breaks the loop. In this case,
loop returns the "result" value stored in the exception.
enum = Enumerator.new { |y|
y << "one"
y << "two"
:ok
}
result = loop {
puts enum.next
} #=> :ok
@overload loop
@yield []
@overload loop;T;#0;$@K;.F;/o;0;1T;2i;3i;%@h;9I"static VALUE
rb_f_loop(VALUE self)
{
RETURN_SIZED_ENUMERATOR(self, 0, 0, rb_f_loop_size);
return rb_rescue2(loop_i, (VALUE)0, loop_stop, (VALUE)0, rb_eStopIteration, (VALUE)0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#Rational;F;7[[@90;[[I"rational.c;Ti";T;:
Rational;0; [ ; { ; IC; "Returns +x/y+ or +arg+ as a Rational.
Rational(2, 3) #=> (2/3)
Rational(5) #=> (5/1)
Rational(0.5) #=> (1/2)
Rational(0.3) #=> (5404319552844595/18014398509481984)
Rational("2/3") #=> (2/3)
Rational("0.3") #=> (3/10)
Rational("10 cents") #=> ArgumentError
Rational(nil) #=> TypeError
Rational(1, nil) #=> TypeError
Rational("10 cents", exception: false) #=> nil
Syntax of the string form:
string form = extra spaces , rational , extra spaces ;
rational = [ sign ] , unsigned rational ;
unsigned rational = numerator | numerator , "/" , denominator ;
numerator = integer part | fractional part | integer part , fractional part ;
denominator = digits ;
integer part = digits ;
fractional part = "." , digits , [ ( "e" | "E" ) , [ sign ] , digits ] ;
sign = "-" | "+" ;
digits = digit , { digit | "_" , digit } ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
extra spaces = ? \s* ? ;
See also String#to_r.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"$Rational(x, y, exception: true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@l;![ ;"I"@return [nil];T;#0;$@l;.F;Bi ;C0;7[[I"x;T0[I"y;T0[I"exception:;TI" true;T;$@lo;=
;>I"
overload;F;?0;;;@0;:I"#Rational(arg, exception: true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@l;![ ;"I"@return [nil];T;#0;$@l;.F;Bi ;C0;7[[I"arg;T0[I"exception:;TI" true;T;$@l;![ ;"I"jReturns +x/y+ or +arg+ as a Rational.
Rational(2, 3) #=> (2/3)
Rational(5) #=> (5/1)
Rational(0.5) #=> (1/2)
Rational(0.3) #=> (5404319552844595/18014398509481984)
Rational("2/3") #=> (2/3)
Rational("0.3") #=> (3/10)
Rational("10 cents") #=> ArgumentError
Rational(nil) #=> TypeError
Rational(1, nil) #=> TypeError
Rational("10 cents", exception: false) #=> nil
Syntax of the string form:
string form = extra spaces , rational , extra spaces ;
rational = [ sign ] , unsigned rational ;
unsigned rational = numerator | numerator , "/" , denominator ;
numerator = integer part | fractional part | integer part , fractional part ;
denominator = digits ;
integer part = digits ;
fractional part = "." , digits , [ ( "e" | "E" ) , [ sign ] , digits ] ;
sign = "-" | "+" ;
digits = digit , { digit | "_" , digit } ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
extra spaces = ? \s* ? ;
See also String#to_r.
@overload Rational(x, y, exception: true)
@return [nil]
@overload Rational(arg, exception: true)
@return [nil];T;#0;$@l;.F;/o;0;1T;2i;3i!;%@h;9I"^static VALUE
nurat_f_rational(int argc, VALUE *argv, VALUE klass)
{
VALUE a1, a2, opts = Qnil;
int raise = TRUE;
if (rb_scan_args(argc, argv, "11:", &a1, &a2, &opts) == 1) {
a2 = Qundef;
}
if (!NIL_P(opts)) {
raise = rb_opts_exception_p(opts, raise);
}
return nurat_convert(rb_cRational, a1, a2, raise);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#proc;F;7[ ;[[@iX;T;: proc;0; [ ; { ; IC; " Equivalent to Proc.new.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" proc;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"...;T;$@o;A
;>I" return;F;?I" ;T;0;@[I" Proc;T;$@;![ ;"I" @yield [...]
@return [Proc];T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"MEquivalent to Proc.new.
@overload proc
@yield [...]
@return [Proc];T;#0;$@;.F;/o;0;1T;2iQ;3iV;%@h;9I"Qstatic VALUE
f_proc(VALUE _)
{
return proc_new(rb_cProc, FALSE, TRUE);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#lambda;F;7[ ;[[@i;T;: lambda;0; [ ; { ; IC; "qEquivalent to Proc.new, except the resulting Proc objects check the
number of parameters passed when called.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" lambda;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"...;T;$@o;A
;>I" return;F;?I" ;T;0;@[I" Proc;T;$@;![ ;"I" @yield [...]
@return [Proc];T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"Equivalent to Proc.new, except the resulting Proc objects check the
number of parameters passed when called.
@overload lambda
@yield [...]
@return [Proc];T;#0;$@;.F;/o;0;1T;2i;3i;%@h;9I"Zstatic VALUE
f_lambda(VALUE _)
{
f_lambda_warn();
return rb_block_lambda();
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#binding;F;7[ ;[[@i;T;: binding;0; [ ; { ; IC; "YReturns a +Binding+ object, describing the variable and
method bindings at the point of call. This object can be used when
calling +eval+ to execute the evaluated command in this
environment. See also the description of class +Binding+.
def get_binding(param)
binding
end
b = get_binding("hello")
eval("param", b) #=> "hello"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" binding;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Binding;T;$@;![ ;"I"@return [Binding];T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"Returns a +Binding+ object, describing the variable and
method bindings at the point of call. This object can be used when
calling +eval+ to execute the evaluated command in this
environment. See also the description of class +Binding+.
def get_binding(param)
binding
end
b = get_binding("hello")
eval("param", b) #=> "hello"
@overload binding
@return [Binding];T;#0;$@;.F;/o;0;1T;2i;3i;%@h;9I"Kstatic VALUE
rb_f_binding(VALUE self)
{
return rb_binding_new();
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#trap;F;7[[@90;[[I"
signal.c;Tio;T;: trap;0; [ ; { ; IC; "Specifies the handling of signals. The first parameter is a signal
name (a string such as ``SIGALRM'', ``SIGUSR1'', and so on) or a
signal number. The characters ``SIG'' may be omitted from the
signal name. The command or block specifies code to be run when the
signal is raised.
If the command is the string ``IGNORE'' or ``SIG_IGN'', the signal
will be ignored.
If the command is ``DEFAULT'' or ``SIG_DFL'', the Ruby's default handler
will be invoked.
If the command is ``EXIT'', the script will be terminated by the signal.
If the command is ``SYSTEM_DEFAULT'', the operating system's default
handler will be invoked.
Otherwise, the given command or block will be run.
The special signal name ``EXIT'' or signal number zero will be
invoked just prior to program termination.
trap returns the previous handler for the given signal.
Signal.trap(0, proc { puts "Terminating: #{$$}" })
Signal.trap("CLD") { puts "Child died" }
fork && Process.wait
produces:
Terminating: 27461
Child died
Terminating: 27460
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" trap( signal, command );T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@;![ ;"I"@return [Object];T;#0;$@;.F;Bi ;C0;7[[I" signal;T0[I" command;T0;$@o;=
;>I"
overload;F;?0;;;@0;:I"trap( signal );T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" ;T;$@o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@;![ ;"I" @yield [ ]
@return [Object];T;#0;$@;.F;Bi ;C0;7[[I" signal;T0;$@;![ ;"I"xSpecifies the handling of signals. The first parameter is a signal
name (a string such as ``SIGALRM'', ``SIGUSR1'', and so on) or a
signal number. The characters ``SIG'' may be omitted from the
signal name. The command or block specifies code to be run when the
signal is raised.
If the command is the string ``IGNORE'' or ``SIG_IGN'', the signal
will be ignored.
If the command is ``DEFAULT'' or ``SIG_DFL'', the Ruby's default handler
will be invoked.
If the command is ``EXIT'', the script will be terminated by the signal.
If the command is ``SYSTEM_DEFAULT'', the operating system's default
handler will be invoked.
Otherwise, the given command or block will be run.
The special signal name ``EXIT'' or signal number zero will be
invoked just prior to program termination.
trap returns the previous handler for the given signal.
Signal.trap(0, proc { puts "Terminating: #{$$}" })
Signal.trap("CLD") { puts "Child died" }
fork && Process.wait
produces:
Terminating: 27461
Child died
Terminating: 27460
@overload trap( signal, command )
@return [Object]
@overload trap( signal )
@yield [ ]
@return [Object];T;#0;$@;.F;/o;0;1T;2iP;3io;%@h;9I"static VALUE
sig_trap(int argc, VALUE *argv, VALUE _)
{
int sig;
sighandler_t func;
VALUE cmd;
rb_check_arity(argc, 1, 2);
sig = trap_signm(argv[0]);
if (reserved_signal_p(sig)) {
const char *name = signo2signm(sig);
if (name)
rb_raise(rb_eArgError, "can't trap reserved signal: SIG%s", name);
else
rb_raise(rb_eArgError, "can't trap reserved signal: %d", sig);
}
if (argc == 1) {
cmd = rb_block_proc();
func = sighandler;
}
else {
cmd = argv[1];
func = trap_handler(&cmd, sig);
}
if (rb_obj_is_proc(cmd) &&
!rb_ractor_main_p() && !rb_ractor_shareable_p(cmd)) {
cmd = rb_proc_isolate(cmd);
}
return trap(sig, func, cmd);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#test;F;7[[@90;[[I" file.c;Ti ;T;: test;0; [ ; { ; IC; " Uses the character +cmd+ to perform various tests on +file1+ (first
table below) or on +file1+ and +file2+ (second table).
File tests on a single file:
Cmd Returns Meaning
"A" | Time | Last access time for file1
"b" | boolean | True if file1 is a block device
"c" | boolean | True if file1 is a character device
"C" | Time | Last change time for file1
"d" | boolean | True if file1 exists and is a directory
"e" | boolean | True if file1 exists
"f" | boolean | True if file1 exists and is a regular file
"g" | boolean | True if file1 has the \CF{setgid} bit
| | set (false under NT)
"G" | boolean | True if file1 exists and has a group
| | ownership equal to the caller's group
"k" | boolean | True if file1 exists and has the sticky bit set
"l" | boolean | True if file1 exists and is a symbolic link
"M" | Time | Last modification time for file1
"o" | boolean | True if file1 exists and is owned by
| | the caller's effective uid
"O" | boolean | True if file1 exists and is owned by
| | the caller's real uid
"p" | boolean | True if file1 exists and is a fifo
"r" | boolean | True if file1 is readable by the effective
| | uid/gid of the caller
"R" | boolean | True if file is readable by the real
| | uid/gid of the caller
"s" | int/nil | If file1 has nonzero size, return the size,
| | otherwise return nil
"S" | boolean | True if file1 exists and is a socket
"u" | boolean | True if file1 has the setuid bit set
"w" | boolean | True if file1 exists and is writable by
| | the effective uid/gid
"W" | boolean | True if file1 exists and is writable by
| | the real uid/gid
"x" | boolean | True if file1 exists and is executable by
| | the effective uid/gid
"X" | boolean | True if file1 exists and is executable by
| | the real uid/gid
"z" | boolean | True if file1 exists and has a zero length
Tests that take two files:
"-" | boolean | True if file1 and file2 are identical
"=" | boolean | True if the modification times of file1
| | and file2 are equal
"<" | boolean | True if the modification time of file1
| | is prior to that of file2
">" | boolean | True if the modification time of file1
| | is after that of file2
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" test(cmd, file1 [, file2] );T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@2;![ ;"I"@return [Object];T;#0;$@2;.F;Bi ;C0;7[[I"cmd;T0[I"file1[, file2];T0;$@2;![ ;"I" Uses the character +cmd+ to perform various tests on +file1+ (first
table below) or on +file1+ and +file2+ (second table).
File tests on a single file:
Cmd Returns Meaning
"A" | Time | Last access time for file1
"b" | boolean | True if file1 is a block device
"c" | boolean | True if file1 is a character device
"C" | Time | Last change time for file1
"d" | boolean | True if file1 exists and is a directory
"e" | boolean | True if file1 exists
"f" | boolean | True if file1 exists and is a regular file
"g" | boolean | True if file1 has the \CF{setgid} bit
| | set (false under NT)
"G" | boolean | True if file1 exists and has a group
| | ownership equal to the caller's group
"k" | boolean | True if file1 exists and has the sticky bit set
"l" | boolean | True if file1 exists and is a symbolic link
"M" | Time | Last modification time for file1
"o" | boolean | True if file1 exists and is owned by
| | the caller's effective uid
"O" | boolean | True if file1 exists and is owned by
| | the caller's real uid
"p" | boolean | True if file1 exists and is a fifo
"r" | boolean | True if file1 is readable by the effective
| | uid/gid of the caller
"R" | boolean | True if file is readable by the real
| | uid/gid of the caller
"s" | int/nil | If file1 has nonzero size, return the size,
| | otherwise return nil
"S" | boolean | True if file1 exists and is a socket
"u" | boolean | True if file1 has the setuid bit set
"w" | boolean | True if file1 exists and is writable by
| | the effective uid/gid
"W" | boolean | True if file1 exists and is writable by
| | the real uid/gid
"x" | boolean | True if file1 exists and is executable by
| | the effective uid/gid
"X" | boolean | True if file1 exists and is executable by
| | the real uid/gid
"z" | boolean | True if file1 exists and has a zero length
Tests that take two files:
"-" | boolean | True if file1 and file2 are identical
"=" | boolean | True if the modification times of file1
| | and file2 are equal
"<" | boolean | True if the modification time of file1
| | is prior to that of file2
">" | boolean | True if the modification time of file1
| | is after that of file2
@overload test(cmd, file1 [, file2] )
@return [Object];T;#0;$@2;.F;/o;0;1T;2i;3i;%@h;9I" static VALUE
rb_f_test(int argc, VALUE *argv, VALUE _)
{
int cmd;
if (argc == 0) rb_check_arity(argc, 2, 3);
cmd = NUM2CHR(argv[0]);
if (cmd == 0) {
goto unknown;
}
if (strchr("bcdefgGkloOprRsSuwWxXz", cmd)) {
CHECK(1);
switch (cmd) {
case 'b':
return rb_file_blockdev_p(0, argv[1]);
case 'c':
return rb_file_chardev_p(0, argv[1]);
case 'd':
return rb_file_directory_p(0, argv[1]);
case 'e':
return rb_file_exist_p(0, argv[1]);
case 'f':
return rb_file_file_p(0, argv[1]);
case 'g':
return rb_file_sgid_p(0, argv[1]);
case 'G':
return rb_file_grpowned_p(0, argv[1]);
case 'k':
return rb_file_sticky_p(0, argv[1]);
case 'l':
return rb_file_symlink_p(0, argv[1]);
case 'o':
return rb_file_owned_p(0, argv[1]);
case 'O':
return rb_file_rowned_p(0, argv[1]);
case 'p':
return rb_file_pipe_p(0, argv[1]);
case 'r':
return rb_file_readable_p(0, argv[1]);
case 'R':
return rb_file_readable_real_p(0, argv[1]);
case 's':
return rb_file_size_p(0, argv[1]);
case 'S':
return rb_file_socket_p(0, argv[1]);
case 'u':
return rb_file_suid_p(0, argv[1]);
case 'w':
return rb_file_writable_p(0, argv[1]);
case 'W':
return rb_file_writable_real_p(0, argv[1]);
case 'x':
return rb_file_executable_p(0, argv[1]);
case 'X':
return rb_file_executable_real_p(0, argv[1]);
case 'z':
return rb_file_zero_p(0, argv[1]);
}
}
if (strchr("MAC", cmd)) {
struct stat st;
VALUE fname = argv[1];
CHECK(1);
if (rb_stat(fname, &st) == -1) {
int e = errno;
FilePathValue(fname);
rb_syserr_fail_path(e, fname);
}
switch (cmd) {
case 'A':
return stat_atime(&st);
case 'M':
return stat_mtime(&st);
case 'C':
return stat_ctime(&st);
}
}
if (cmd == '-') {
CHECK(2);
return rb_file_identical_p(0, argv[1], argv[2]);
}
if (strchr("=<>", cmd)) {
struct stat st1, st2;
struct timespec t1, t2;
CHECK(2);
if (rb_stat(argv[1], &st1) < 0) return Qfalse;
if (rb_stat(argv[2], &st2) < 0) return Qfalse;
t1 = stat_mtimespec(&st1);
t2 = stat_mtimespec(&st2);
switch (cmd) {
case '=':
if (t1.tv_sec == t2.tv_sec && t1.tv_nsec == t2.tv_nsec) return Qtrue;
return Qfalse;
case '>':
if (t1.tv_sec > t2.tv_sec) return Qtrue;
if (t1.tv_sec == t2.tv_sec && t1.tv_nsec > t2.tv_nsec) return Qtrue;
return Qfalse;
case '<':
if (t1.tv_sec < t2.tv_sec) return Qtrue;
if (t1.tv_sec == t2.tv_sec && t1.tv_nsec < t2.tv_nsec) return Qtrue;
return Qfalse;
}
}
unknown:
/* unknown command */
if (ISPRINT(cmd)) {
rb_raise(rb_eArgError, "unknown command '%s%c'", cmd == '\'' || cmd == '\\' ? "\\" : "", cmd);
}
else {
rb_raise(rb_eArgError, "unknown command \"\\x%02X\"", cmd);
}
UNREACHABLE_RETURN(Qundef);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#load;F;7[[@90;[[I" load.c;Ti;T;: load;0; [ ; { ; IC; "Loads and executes the Ruby program in the file _filename_.
If the filename is an absolute path (e.g. starts with '/'), the file
will be loaded directly using the absolute path.
If the filename is an explicit relative path (e.g. starts with './' or
'../'), the file will be loaded using the relative path from the current
directory.
Otherwise, the file will be searched for in the library
directories listed in $LOAD_PATH ($:).
If the file is found in a directory, it will attempt to load the file
relative to that directory. If the file is not found in any of the
directories in $LOAD_PATH, the file will be loaded using
the relative path from the current directory.
If the file doesn't exist when there is an attempt to load it, a
LoadError will be raised.
If the optional _wrap_ parameter is +true+, the loaded script will
be executed under an anonymous module, protecting the calling
program's global namespace. If the optional _wrap_ parameter is a
module, the loaded script will be executed under the given module.
In no circumstance will any local variables in the loaded file be
propagated to the loading environment.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" load(filename, wrap=false);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" true;T;$@S;![ ;"I"@return [true];T;#0;$@S;.F;Bi ;C0;7[[I"
filename;T0[I" wrap;TI"
false;T;$@S;![ ;"I"Loads and executes the Ruby program in the file _filename_.
If the filename is an absolute path (e.g. starts with '/'), the file
will be loaded directly using the absolute path.
If the filename is an explicit relative path (e.g. starts with './' or
'../'), the file will be loaded using the relative path from the current
directory.
Otherwise, the file will be searched for in the library
directories listed in $LOAD_PATH ($:).
If the file is found in a directory, it will attempt to load the file
relative to that directory. If the file is not found in any of the
directories in $LOAD_PATH, the file will be loaded using
the relative path from the current directory.
If the file doesn't exist when there is an attempt to load it, a
LoadError will be raised.
If the optional _wrap_ parameter is +true+, the loaded script will
be executed under an anonymous module, protecting the calling
program's global namespace. If the optional _wrap_ parameter is a
module, the loaded script will be executed under the given module.
In no circumstance will any local variables in the loaded file be
propagated to the loading environment.
@overload load(filename, wrap=false)
@return [true];T;#0;$@S;.F;/o;0;1T;2i;3i;%@h;9I"8static VALUE
rb_f_load(int argc, VALUE *argv, VALUE _)
{
VALUE fname, wrap, path, orig_fname;
rb_scan_args(argc, argv, "11", &fname, &wrap);
orig_fname = rb_get_path_check_to_string(fname);
fname = rb_str_encode_ospath(orig_fname);
RUBY_DTRACE_HOOK(LOAD_ENTRY, RSTRING_PTR(orig_fname));
path = rb_find_file(fname);
if (!path) {
if (!rb_file_load_ok(RSTRING_PTR(fname)))
load_failed(orig_fname);
path = fname;
}
rb_load_internal(path, wrap);
RUBY_DTRACE_HOOK(LOAD_RETURN, RSTRING_PTR(orig_fname));
return Qtrue;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#require;F;7[[I"
fname;T0;[[@Yi;T;: require;0; [ ; { ; IC; "Loads the given +name+, returning +true+ if successful and +false+ if the
feature is already loaded.
If the filename neither resolves to an absolute path nor starts with
'./' or '../', the file will be searched for in the library
directories listed in $LOAD_PATH ($:).
If the filename starts with './' or '../', resolution is based on Dir.pwd.
If the filename has the extension ".rb", it is loaded as a source file; if
the extension is ".so", ".o", or ".dll", or the default shared library
extension on the current platform, Ruby loads the shared library as a
Ruby extension. Otherwise, Ruby tries adding ".rb", ".so", and so on
to the name until found. If the file named cannot be found, a LoadError
will be raised.
For Ruby extensions the filename given may use any shared library
extension. For example, on Linux the socket extension is "socket.so" and
require 'socket.dll' will load the socket extension.
The absolute path of the loaded file is added to
$LOADED_FEATURES ($"). A file will not be
loaded again if its path already appears in $". For example,
require 'a'; require './a' will not load a.rb
again.
require "my-library.rb"
require "db-driver"
Any constants or globals within the loaded source file will be available
in the calling program's global namespace. However, local variables will
not be propagated to the loading environment.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"require(name);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@u;![ ;"I"@return [Boolean];T;#0;$@u;.F;Bi ;C0;7[[I" name;T0;$@u;![ ;"I"Loads the given +name+, returning +true+ if successful and +false+ if the
feature is already loaded.
If the filename neither resolves to an absolute path nor starts with
'./' or '../', the file will be searched for in the library
directories listed in $LOAD_PATH ($:).
If the filename starts with './' or '../', resolution is based on Dir.pwd.
If the filename has the extension ".rb", it is loaded as a source file; if
the extension is ".so", ".o", or ".dll", or the default shared library
extension on the current platform, Ruby loads the shared library as a
Ruby extension. Otherwise, Ruby tries adding ".rb", ".so", and so on
to the name until found. If the file named cannot be found, a LoadError
will be raised.
For Ruby extensions the filename given may use any shared library
extension. For example, on Linux the socket extension is "socket.so" and
require 'socket.dll' will load the socket extension.
The absolute path of the loaded file is added to
$LOADED_FEATURES ($"). A file will not be
loaded again if its path already appears in $". For example,
require 'a'; require './a' will not load a.rb
again.
require "my-library.rb"
require "db-driver"
Any constants or globals within the loaded source file will be available
in the calling program's global namespace. However, local variables will
not be propagated to the loading environment.
@overload require(name)
@return [Boolean];T;#0;$@u;.F;/o;0;1T;2i_;3i;%@h;9I"XVALUE
rb_f_require(VALUE obj, VALUE fname)
{
return rb_require_string(fname);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" Kernel#require_relative;F;7[[I"
fname;T0;[[@Yi;T;:require_relative;0; [ ; { ; IC; "Ruby tries to load the library named _string_ relative to the requiring
file's path. If the file's path cannot be determined a LoadError is raised.
If a file is loaded +true+ is returned and false otherwise.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" require_relative(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@;![ ;"I"@return [Boolean];T;#0;$@;.F;Bi ;C0;7[[I" string;T0;$@;![ ;"I" Ruby tries to load the library named _string_ relative to the requiring
file's path. If the file's path cannot be determined a LoadError is raised.
If a file is loaded +true+ is returned and false otherwise.
@overload require_relative(string)
@return [Boolean];T;#0;$@;.F;/o;0;1T;2i;3i;%@h;9I" VALUE
rb_f_require_relative(VALUE obj, VALUE fname)
{
VALUE base = rb_current_realfilepath();
if (NIL_P(base)) {
rb_loaderror("cannot infer basepath");
}
base = rb_file_dirname(base);
return rb_require_string(rb_file_absolute_path(fname, base));
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Kernel#autoload;F;7[[I"sym;T0[I" file;T0;[[@Yi=;T;:
autoload;0; [ ; { ; IC; "Registers _filename_ to be loaded (using Kernel::require)
the first time that _module_ (which may be a String or
a symbol) is accessed.
autoload(:MyModule, "/usr/local/lib/modules/my_module.rb")
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" autoload(module, filename);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@;![ ;"I"@return [nil];T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"Registers _filename_ to be loaded (using Kernel::require)
the first time that _module_ (which may be a String or
a symbol) is accessed.
autoload(:MyModule, "/usr/local/lib/modules/my_module.rb")
@overload autoload(module, filename)
@return [nil];T;#0;$@;.F;/o;0;1T;2i2;3i:;%@h;9I"static VALUE
rb_f_autoload(VALUE obj, VALUE sym, VALUE file)
{
VALUE klass = rb_class_real(rb_vm_cbase());
if (!klass) {
rb_raise(rb_eTypeError, "Can not set autoload on singleton class");
}
return rb_mod_autoload(klass, sym, file);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#autoload?;F;7[[@90;[[@YiR;T;:autoload?;0; [ ; { ; IC; "Returns _filename_ to be loaded if _name_ is registered as
+autoload+.
autoload(:B, "b")
autoload?(:B) #=> "b";T; [o;=
;>I"
overload;F;?0;;;@0;:I""autoload?(name, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;TI"nil;T;$@;![ ;"I"@return [String, nil];T;#0;$@;.F;Bi ;C0;7[[I" name;T0[I" inherit;TI" true;T;$@;![ ;"I"Returns _filename_ to be loaded if _name_ is registered as
+autoload+.
autoload(:B, "b")
autoload?(:B) #=> "b"
@overload autoload?(name, inherit=true)
@return [String, nil];T;#0;$@;.F;/o;0;1T;2iG;3iO;Bi ;%@h;9I"static VALUE
rb_f_autoload_p(int argc, VALUE *argv, VALUE obj)
{
/* use rb_vm_cbase() as same as rb_f_autoload. */
VALUE klass = rb_vm_cbase();
if (NIL_P(klass)) {
return Qnil;
}
return rb_mod_autoload_p(argc, argv, klass);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#set_trace_func;F;7[[I"
trace;T0;[[I"vm_trace.c;Ti+;T;:set_trace_func;0; [ ; { ; IC; "Establishes _proc_ as the handler for tracing, or disables
tracing if the parameter is +nil+.
*Note:* this method is obsolete, please use TracePoint instead.
_proc_ takes up to six parameters:
* an event name
* a filename
* a line number
* an object id
* a binding
* the name of a class
_proc_ is invoked whenever an event occurs.
Events are:
+c-call+:: call a C-language routine
+c-return+:: return from a C-language routine
+call+:: call a Ruby method
+class+:: start a class or module definition
+end+:: finish a class or module definition
+line+:: execute code on a new line
+raise+:: raise an exception
+return+:: return from a Ruby method
Tracing is disabled within the context of _proc_.
class Test
def test
a = 1
b = 2
end
end
set_trace_func proc { |event, file, line, id, binding, classname|
printf "%8s %s:%-2d %10s %8s\n", event, file, line, id, classname
}
t = Test.new
t.test
line prog.rb:11 false
c-call prog.rb:11 new Class
c-call prog.rb:11 initialize Object
c-return prog.rb:11 initialize Object
c-return prog.rb:11 new Class
line prog.rb:12 false
call prog.rb:2 test Test
line prog.rb:3 test Test
line prog.rb:4 test Test
return prog.rb:4 test Test
Note that for +c-call+ and +c-return+ events, the binding returned is the
binding of the nearest Ruby method calling the C method, since C methods
themselves do not have bindings.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"set_trace_func(proc);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Proc;T;$@;![ ;"I"@return [Proc];T;#0;$@;.F;Bi ;C0;7[[I" proc;T0;$@o;=
;>I"
overload;F;?0;;;@0;:I"set_trace_func(nil);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@;![ ;"I"@return [nil];T;#0;$@;.F;Bi ;C0;7[[I"nil;T0;$@;![ ;"I"@Establishes _proc_ as the handler for tracing, or disables
tracing if the parameter is +nil+.
*Note:* this method is obsolete, please use TracePoint instead.
_proc_ takes up to six parameters:
* an event name
* a filename
* a line number
* an object id
* a binding
* the name of a class
_proc_ is invoked whenever an event occurs.
Events are:
+c-call+:: call a C-language routine
+c-return+:: return from a C-language routine
+call+:: call a Ruby method
+class+:: start a class or module definition
+end+:: finish a class or module definition
+line+:: execute code on a new line
+raise+:: raise an exception
+return+:: return from a Ruby method
Tracing is disabled within the context of _proc_.
class Test
def test
a = 1
b = 2
end
end
set_trace_func proc { |event, file, line, id, binding, classname|
printf "%8s %s:%-2d %10s %8s\n", event, file, line, id, classname
}
t = Test.new
t.test
line prog.rb:11 false
c-call prog.rb:11 new Class
c-call prog.rb:11 initialize Object
c-return prog.rb:11 initialize Object
c-return prog.rb:11 new Class
line prog.rb:12 false
call prog.rb:2 test Test
line prog.rb:3 test Test
line prog.rb:4 test Test
return prog.rb:4 test Test
Note that for +c-call+ and +c-return+ events, the binding returned is the
binding of the nearest Ruby method calling the C method, since C methods
themselves do not have bindings.
@overload set_trace_func(proc)
@return [Proc]
@overload set_trace_func(nil)
@return [nil];T;#0;$@;.F;/o;0;1T;2i;3i);%@h;9I"Cstatic VALUE
set_trace_func(VALUE obj, VALUE trace)
{
rb_remove_event_hook(call_trace_func);
if (NIL_P(trace)) {
return Qnil;
}
if (!rb_obj_is_proc(trace)) {
rb_raise(rb_eTypeError, "trace_func needs to be Proc");
}
rb_add_event_hook(call_trace_func, RUBY_EVENT_ALL, trace);
return trace;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#callcc;F;7[ ;[[I" cont.c;Ti;T;: callcc;0; [ ; { ; IC; "Generates a Continuation object, which it passes to
the associated block. You need to require
'continuation' before using this method. Performing a
cont.call will cause the #callcc
to return (as will falling through the end of the block). The
value returned by the #callcc is the value of the
block, or the value passed to cont.call. See
class Continuation for more details. Also see
Kernel#throw for an alternative mechanism for
unwinding a call stack.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" callcc;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" cont;T;$@#o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@#;![ ;"I"#@yield [cont]
@return [Object];T;#0;$@#;.F;Bi ;C0;7[ ;$@#;![ ;"I"4Generates a Continuation object, which it passes to
the associated block. You need to require
'continuation' before using this method. Performing a
cont.call will cause the #callcc
to return (as will falling through the end of the block). The
value returned by the #callcc is the value of the
block, or the value passed to cont.call. See
class Continuation for more details. Also see
Kernel#throw for an alternative mechanism for
unwinding a call stack.
@overload callcc
@yield [cont]
@return [Object];T;#0;$@#;.F;/o;0;1T;2i;3i;%@h;9I"static VALUE
rb_callcc(VALUE self)
{
volatile int called;
volatile VALUE val = cont_capture(&called);
if (called) {
return val;
}
else {
return rb_yield(val);
}
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"(Kernel#register_sample_bug_reporter;F;7[[I"obj;T0;[[I"+ext/-test-/bug_reporter/bug_reporter.c;Ti;T;:!register_sample_bug_reporter;0; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@D;%@h;9I"static VALUE
register_sample_bug_reporter(VALUE self, VALUE obj)
{
rb_bug_reporter_add(sample_bug_reporter, (void *)(uintptr_t)NUM2INT(obj));
return Qnil;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Kernel#Pathname;F;7[[I"str;T0;[[I" ext/pathname/pathname.c;Ti*;T;:
Pathname;0; [ ; { ; IC; "Y:call-seq:
Pathname(path) -> pathname
Creates a new Pathname object from the given string, +path+, and returns
pathname object.
In order to use this constructor, you must first require the Pathname
standard library extension.
require 'pathname'
Pathname("/home/zzak")
#=> #:name).
== What's Here
First, what's elsewhere. \Class \Object:
- Inherits from {class BasicObject}[BasicObject.html#class-BasicObject-label-What-27s+Here].
- Includes {module Kernel}[Kernel.html#module-Kernel-label-What-27s+Here].
Here, class \Object provides methods for:
- {Querying}[#class-Object-label-Querying]
- {Instance Variables}[#class-Object-label-Instance+Variables]
- {Other}[#class-Object-label-Other]
=== Querying
- {!~}[#method-i-21~]:: Returns +true+ if +self+ does not match the given object,
otherwise +false+.
- {<=>}[#method-i-3C-3D-3E]:: Returns 0 if +self+ and the given object +object+
are the same object, or if
self == object; otherwise returns +nil+.
- #===:: Implements case equality, effectively the same as calling #==.
- #eql?:: Implements hash equality, effectively the same as calling #==.
- #kind_of? (aliased as #is_a?):: Returns whether given argument is an ancestor
of the singleton class of +self+.
- #instance_of?:: Returns whether +self+ is an instance of the given class.
- #instance_variable_defined?:: Returns whether the given instance variable
is defined in +self+.
- #method:: Returns the Method object for the given method in +self+.
- #methods:: Returns an array of symbol names of public and protected methods
in +self+.
- #nil?:: Returns +false+. (Only +nil+ responds +true+ to method nil?.)
- #object_id:: Returns an integer corresponding to +self+ that is unique
for the current process
- #private_methods:: Returns an array of the symbol names
of the private methods in +self+.
- #protected_methods:: Returns an array of the symbol names
of the protected methods in +self+.
- #public_method:: Returns the Method object for the given public method in +self+.
- #public_methods:: Returns an array of the symbol names
of the public methods in +self+.
- #respond_to?:: Returns whether +self+ responds to the given method.
- #singleton_class:: Returns the singleton class of +self+.
- #singleton_method:: Returns the Method object for the given singleton method
in +self+.
- #singleton_methods:: Returns an array of the symbol names
of the singleton methods in +self+.
- #define_singleton_method:: Defines a singleton method in +self+
for the given symbol method-name and block or proc.
- #extend:: Includes the given modules in the singleton class of +self+.
- #public_send:: Calls the given public method in +self+ with the given argument.
- #send:: Calls the given method in +self+ with the given argument.
=== Instance Variables
- #instance_variable_get:: Returns the value of the given instance variable
in +self+, or +nil+ if the instance variable is not set.
- #instance_variable_set:: Sets the value of the given instance variable in +self+
to the given object.
- #instance_variables:: Returns an array of the symbol names
of the instance variables in +self+.
- #remove_instance_variable:: Removes the named instance variable from +self+.
=== Other
- #clone:: Returns a shallow copy of +self+, including singleton class
and frozen state.
- #define_singleton_method:: Defines a singleton method in +self+
for the given symbol method-name and block or proc.
- #display:: Prints +self+ to the given \IO stream or $stdout.
- #dup:: Returns a shallow unfrozen copy of +self+.
- #enum_for (aliased as #to_enum):: Returns an Enumerator for +self+
using the using the given method,
arguments, and block.
- #extend:: Includes the given modules in the singleton class of +self+.
- #freeze:: Prevents further modifications to +self+.
- #hash:: Returns the integer hash value for +self+.
- #inspect:: Returns a human-readable string representation of +self+.
- #itself:: Returns +self+.
- #public_send:: Calls the given public method in +self+ with the given argument.
- #send:: Calls the given method in +self+ with the given argument.
- #to_s:: Returns a string representation of +self+.;T; [ ;![ ;"I"-
Object is the default root of all Ruby objects. Object inherits from
BasicObject which allows creating alternate object hierarchies. Methods
on Object are available to all classes unless explicitly overridden.
Object mixes in the Kernel module, making the built-in kernel functions
globally accessible. Although the instance methods of Object are defined
by the Kernel module, we have chosen to document them here for clarity.
When referencing constants in classes inheriting from Object you do not
need to use the full namespace. For example, referencing +File+ inside
+YourClass+ will find the top-level File class.
In the descriptions of Object's methods, the parameter symbol refers
to a symbol, which is either a quoted string or a Symbol (such as
:name).
== What's Here
First, what's elsewhere. \Class \Object:
- Inherits from {class BasicObject}[BasicObject.html#class-BasicObject-label-What-27s+Here].
- Includes {module Kernel}[Kernel.html#module-Kernel-label-What-27s+Here].
Here, class \Object provides methods for:
- {Querying}[#class-Object-label-Querying]
- {Instance Variables}[#class-Object-label-Instance+Variables]
- {Other}[#class-Object-label-Other]
=== Querying
- {!~}[#method-i-21~]:: Returns +true+ if +self+ does not match the given object,
otherwise +false+.
- {<=>}[#method-i-3C-3D-3E]:: Returns 0 if +self+ and the given object +object+
are the same object, or if
self == object; otherwise returns +nil+.
- #===:: Implements case equality, effectively the same as calling #==.
- #eql?:: Implements hash equality, effectively the same as calling #==.
- #kind_of? (aliased as #is_a?):: Returns whether given argument is an ancestor
of the singleton class of +self+.
- #instance_of?:: Returns whether +self+ is an instance of the given class.
- #instance_variable_defined?:: Returns whether the given instance variable
is defined in +self+.
- #method:: Returns the Method object for the given method in +self+.
- #methods:: Returns an array of symbol names of public and protected methods
in +self+.
- #nil?:: Returns +false+. (Only +nil+ responds +true+ to method nil?.)
- #object_id:: Returns an integer corresponding to +self+ that is unique
for the current process
- #private_methods:: Returns an array of the symbol names
of the private methods in +self+.
- #protected_methods:: Returns an array of the symbol names
of the protected methods in +self+.
- #public_method:: Returns the Method object for the given public method in +self+.
- #public_methods:: Returns an array of the symbol names
of the public methods in +self+.
- #respond_to?:: Returns whether +self+ responds to the given method.
- #singleton_class:: Returns the singleton class of +self+.
- #singleton_method:: Returns the Method object for the given singleton method
in +self+.
- #singleton_methods:: Returns an array of the symbol names
of the singleton methods in +self+.
- #define_singleton_method:: Defines a singleton method in +self+
for the given symbol method-name and block or proc.
- #extend:: Includes the given modules in the singleton class of +self+.
- #public_send:: Calls the given public method in +self+ with the given argument.
- #send:: Calls the given method in +self+ with the given argument.
=== Instance Variables
- #instance_variable_get:: Returns the value of the given instance variable
in +self+, or +nil+ if the instance variable is not set.
- #instance_variable_set:: Sets the value of the given instance variable in +self+
to the given object.
- #instance_variables:: Returns an array of the symbol names
of the instance variables in +self+.
- #remove_instance_variable:: Removes the named instance variable from +self+.
=== Other
- #clone:: Returns a shallow copy of +self+, including singleton class
and frozen state.
- #define_singleton_method:: Defines a singleton method in +self+
for the given symbol method-name and block or proc.
- #display:: Prints +self+ to the given \IO stream or $stdout.
- #dup:: Returns a shallow unfrozen copy of +self+.
- #enum_for (aliased as #to_enum):: Returns an Enumerator for +self+
using the using the given method,
arguments, and block.
- #extend:: Includes the given modules in the singleton class of +self+.
- #freeze:: Prevents further modifications to +self+.
- #hash:: Returns the integer hash value for +self+.
- #inspect:: Returns a human-readable string representation of +self+.
- #itself:: Returns +self+.
- #public_send:: Calls the given public method in +self+ with the given argument.
- #send:: Calls the given method in +self+ with the given argument.
- #to_s:: Returns a string representation of +self+.
;T;#0;$@;.F;/o;0;1T;2i;3i;Bi ;%@;&I" Object;F;'o; ;IC;[o;4;5F;6;;: private;&I"BasicObject#initialize;F;7[ ;[ ;F;;D;;; [ ; { ; IC; "=call-seq:
BasicObject.new
Returns a new BasicObject.
;T; [ ;![ ;"I"?
call-seq:
BasicObject.new
Returns a new BasicObject.
;T;#0;$@;.F;/o;0;1T;2i/;3i4;%@;;To;4;5F;6;;; ;&I"BasicObject#==;F;7[[I" obj2;T0;[[@true
only if +obj+ and +other+ are the same object. Typically, this
method is overridden in descendant classes to provide
class-specific meaning.
Unlike #==, the #equal? method should never be overridden by
subclasses as it is used to determine object identity (that is,
a.equal?(b) if and only if a is the same
object as b):
obj = "a"
other = obj.dup
obj == other #=> true
obj.equal? other #=> false
obj.equal? obj #=> true
The #eql? method returns true if +obj+ and +other+
refer to the same hash key. This is used by Hash to test members
for equality. For any pair of objects where #eql? returns +true+,
the #hash value of both objects must be equal. So any subclass
that overrides #eql? should also override #hash appropriately.
For objects of class Object, #eql? is synonymous
with #==. Subclasses normally continue this tradition by aliasing
#eql? to their overridden #== method, but there are exceptions.
Numeric types, for example, perform type conversion across #==,
but not across #eql?, so:
1 == 1.0 #=> true
1.eql? 1.0 #=> false
;T; [o;=
;>I"
overload;F;?0;;F;@0;:I"==(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@;![ ;"I"@return [Boolean];T;#0;$@;.F;Bi ;C0;7[[I"
other;T0;$@o;=
;>I"
overload;F;?0;;W;@0;:I"equal?(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@;![ ;"I"@return [Boolean];T;#0;$@;.F;Bi ;C0;7[[I"
other;T0;$@o;=
;>I"
overload;F;?0;;V;@0;:I"eql?(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@;![ ;"I"@return [Boolean];T;#0;$@;.F;Bi ;C0;7[[I"
other;T0;$@;![ ;"@;#0;$@;.F;/o;0;1T;2i;3i;%@;9I"fMJIT_FUNC_EXPORTED VALUE
rb_obj_equal(VALUE obj1, VALUE obj2)
{
return RBOOL(obj1 == obj2);
};T;:I" MJIT_FUNC_EXPORTED VALUE;T;;To;4;5F;6;;; ;&I"BasicObject#equal?;F;7[[I" obj2;T0;[[@true
only if +obj+ and +other+ are the same object. Typically, this
method is overridden in descendant classes to provide
class-specific meaning.
Unlike #==, the #equal? method should never be overridden by
subclasses as it is used to determine object identity (that is,
a.equal?(b) if and only if a is the same
object as b):
obj = "a"
other = obj.dup
obj == other #=> true
obj.equal? other #=> false
obj.equal? obj #=> true
The #eql? method returns true if +obj+ and +other+
refer to the same hash key. This is used by Hash to test members
for equality. For any pair of objects where #eql? returns +true+,
the #hash value of both objects must be equal. So any subclass
that overrides #eql? should also override #hash appropriately.
For objects of class Object, #eql? is synonymous
with #==. Subclasses normally continue this tradition by aliasing
#eql? to their overridden #== method, but there are exceptions.
Numeric types, for example, perform type conversion across #==,
but not across #eql?, so:
1 == 1.0 #=> true
1.eql? 1.0 #=> false;T; [o;=
;>I"
overload;F;?0;;F;@0;:I"==(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@);![ ;"I"@return [Boolean];T;#0;$@);.F;Bi ;C0;7[[I"
other;T0;$@)o;=
;>I"
overload;F;?0;;W;@0;:I"equal?(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@);![ ;"I"@return [Boolean];T;#0;$@);.F;Bi ;C0;7[[I"
other;T0;$@)o;=
;>I"
overload;F;?0;;V;@0;:I"eql?(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@);![ ;"I"@return [Boolean];T;#0;$@);.F;Bi ;C0;7[[I"
other;T0;$@);![ ;"@;#0;$@);.F;/o;0;1T;2i;3i;Bi ;%@;9I"fMJIT_FUNC_EXPORTED VALUE
rb_obj_equal(VALUE obj1, VALUE obj2)
{
return RBOOL(obj1 == obj2);
};T;:I" MJIT_FUNC_EXPORTED VALUE;T;;To;4;5F;6;;; ;&I"BasicObject#!;F;7[ ;[[@I"
overload;F;?0;;;@0;:I" !obj;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@e;![ ;"I"@return [Boolean];T;#0;$@e;.F;Bi ;C0;7[ ;$@e;![ ;"I":Boolean negate.
@overload !obj
@return [Boolean];T;#0;$@e;.F;/o;0;1T;2i;3i;%@;9I"_MJIT_FUNC_EXPORTED VALUE
rb_obj_not(VALUE obj)
{
return RTEST(obj) ? Qfalse : Qtrue;
};T;:I" MJIT_FUNC_EXPORTED VALUE;T;;To;4;5F;6;;; ;&I"BasicObject#!=;F;7[[I" obj2;T0;[[@I"
overload;F;?0;;;@0;:I"!=(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@;![ ;"I"@return [Boolean];T;#0;$@;.F;Bi ;C0;7[[I"
other;T0;$@;![ ;"I"kReturns true if two objects are not-equal, otherwise false.
@overload !=(other)
@return [Boolean];T;#0;$@;.F;/o;0;1T;2i;3i;%@;9I"MJIT_FUNC_EXPORTED VALUE
rb_obj_not_equal(VALUE obj1, VALUE obj2)
{
VALUE result = rb_funcall(obj1, id_eq, 1, obj2);
return RTEST(result) ? Qfalse : Qtrue;
};T;:I" MJIT_FUNC_EXPORTED VALUE;T;;To;4;5F;6;;;;&I"'BasicObject#singleton_method_added;F;7[ ;[ ;F;:singleton_method_added;;; [ ; { ; IC; "call-seq:
singleton_method_added(symbol)
Invoked as a callback whenever a singleton method is added to the
receiver.
module Chatty
def Chatty.singleton_method_added(id)
puts "Adding #{id.id2name}"
end
def self.one() end
def two() end
def Chatty.three() end
end
produces:
Adding singleton_method_added
Adding one
Adding three
;T; [ ;![ ;"I"
call-seq:
singleton_method_added(symbol)
Invoked as a callback whenever a singleton method is added to the
receiver.
module Chatty
def Chatty.singleton_method_added(id)
puts "Adding #{id.id2name}"
end
def self.one() end
def two() end
def Chatty.three() end
end
produces:
Adding singleton_method_added
Adding one
Adding three
;T;#0;$@;.F;/o;0;1T;2i;3i;%@;;To;4;5F;6;;;;&I")BasicObject#singleton_method_removed;F;7[ ;[ ;F;: singleton_method_removed;;; [ ; { ; IC; "call-seq:
singleton_method_removed(symbol)
Invoked as a callback whenever a singleton method is removed from
the receiver.
module Chatty
def Chatty.singleton_method_removed(id)
puts "Removing #{id.id2name}"
end
def self.one() end
def two() end
def Chatty.three() end
class << self
remove_method :three
remove_method :one
end
end
produces:
Removing three
Removing one
;T; [ ;![ ;"I"
call-seq:
singleton_method_removed(symbol)
Invoked as a callback whenever a singleton method is removed from
the receiver.
module Chatty
def Chatty.singleton_method_removed(id)
puts "Removing #{id.id2name}"
end
def self.one() end
def two() end
def Chatty.three() end
class << self
remove_method :three
remove_method :one
end
end
produces:
Removing three
Removing one
;T;#0;$@;.F;/o;0;1T;2i;3i;%@;;To;4;5F;6;;;;&I"+BasicObject#singleton_method_undefined;F;7[ ;[ ;F;: singleton_method_undefined;;; [ ; { ; IC; "call-seq:
singleton_method_undefined(symbol)
Invoked as a callback whenever a singleton method is undefined in
the receiver.
module Chatty
def Chatty.singleton_method_undefined(id)
puts "Undefining #{id.id2name}"
end
def Chatty.one() end
class << self
undef_method(:one)
end
end
produces:
Undefining one
;T; [ ;![ ;"I"
call-seq:
singleton_method_undefined(symbol)
Invoked as a callback whenever a singleton method is undefined in
the receiver.
module Chatty
def Chatty.singleton_method_undefined(id)
puts "Undefining #{id.id2name}"
end
def Chatty.one() end
class << self
undef_method(:one)
end
end
produces:
Undefining one
;T;#0;$@;.F;/o;0;1T;2i;3i;%@;;To;4;5F;6;;; ;&I" BasicObject#instance_eval;F;7[[@90;[[@Ci;T;:instance_eval;0; [ ; { ; IC; "Evaluates a string containing Ruby source code, or the given block,
within the context of the receiver (_obj_). In order to set the
context, the variable +self+ is set to _obj_ while
the code is executing, giving the code access to _obj_'s
instance variables and private methods.
When instance_eval is given a block, _obj_ is also
passed in as the block's only argument.
When instance_eval is given a +String+, the optional
second and third parameters supply a filename and starting line number
that are used when reporting compilation errors.
class KlassWithSecret
def initialize
@secret = 99
end
private
def the_secret
"Ssssh! The secret is #{@secret}."
end
end
k = KlassWithSecret.new
k.instance_eval { @secret } #=> 99
k.instance_eval { the_secret } #=> "Ssssh! The secret is 99."
k.instance_eval {|obj| obj == self } #=> true
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"3instance_eval(string [, filename [, lineno]] );T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@;![ ;"I"@return [Object];T;#0;$@;.F;Bi ;C0;7[[I""string[, filename [, lineno]];T0;$@o;=
;>I"
overload;F;?0;;;@0;:I"instance_eval;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"obj;T;$@o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@;![ ;"I""@yield [obj]
@return [Object];T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"+Evaluates a string containing Ruby source code, or the given block,
within the context of the receiver (_obj_). In order to set the
context, the variable +self+ is set to _obj_ while
the code is executing, giving the code access to _obj_'s
instance variables and private methods.
When instance_eval is given a block, _obj_ is also
passed in as the block's only argument.
When instance_eval is given a +String+, the optional
second and third parameters supply a filename and starting line number
that are used when reporting compilation errors.
class KlassWithSecret
def initialize
@secret = 99
end
private
def the_secret
"Ssssh! The secret is #{@secret}."
end
end
k = KlassWithSecret.new
k.instance_eval { @secret } #=> 99
k.instance_eval { the_secret } #=> "Ssssh! The secret is 99."
k.instance_eval {|obj| obj == self } #=> true
@overload instance_eval(string [, filename [, lineno]] )
@return [Object]
@overload instance_eval
@yield [obj]
@return [Object];T;#0;$@;.F;/o;0;1T;2i;3i
;%@;9I"static VALUE
rb_obj_instance_eval_internal(int argc, const VALUE *argv, VALUE self)
{
return specific_eval(argc, argv, self, TRUE, RB_PASS_CALLED_KEYWORDS);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" BasicObject#instance_exec;F;7[[@90;[[@Ci,;T;:instance_exec;0; [ ; { ; IC; "Executes the given block within the context of the receiver
(_obj_). In order to set the context, the variable +self+ is set
to _obj_ while the code is executing, giving the code access to
_obj_'s instance variables. Arguments are passed as block parameters.
class KlassWithSecret
def initialize
@secret = 99
end
end
k = KlassWithSecret.new
k.instance_exec(5) {|x| @secret+x } #=> 104
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"instance_exec(arg...);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" var...;T;$@o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@;![ ;"I"%@yield [var...]
@return [Object];T;#0;$@;.F;Bi ;C0;7[[I" arg...;T0;$@;![ ;"I"Executes the given block within the context of the receiver
(_obj_). In order to set the context, the variable +self+ is set
to _obj_ while the code is executing, giving the code access to
_obj_'s instance variables. Arguments are passed as block parameters.
class KlassWithSecret
def initialize
@secret = 99
end
end
k = KlassWithSecret.new
k.instance_exec(5) {|x| @secret+x } #=> 104
@overload instance_exec(arg...)
@yield [var...]
@return [Object];T;#0;$@;.F;/o;0;1T;2i;3i*;%@;9I"static VALUE
rb_obj_instance_exec_internal(int argc, const VALUE *argv, VALUE self)
{
return yield_under(self, TRUE, argc, argv, RB_PASS_CALLED_KEYWORDS);
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I" BasicObject#method_missing;F;7[[@90;[[@Ci;T;:method_missing;0; [ ; { ; IC; "Invoked by Ruby when obj is sent a message it cannot handle.
symbol is the symbol for the method called, and args
are any arguments that were passed to it. By default, the interpreter
raises an error when this method is called. However, it is possible
to override the method to provide more dynamic behavior.
If it is decided that a particular method should not be handled, then
super should be called, so that ancestors can pick up the
missing method.
The example below creates
a class Roman, which responds to methods with names
consisting of roman numerals, returning the corresponding integer
values.
class Roman
def roman_to_int(str)
# ...
end
def method_missing(symbol, *args)
str = symbol.id2name
begin
roman_to_int(str)
rescue
super(symbol, *args)
end
end
end
r = Roman.new
r.iv #=> 4
r.xxiii #=> 23
r.mm #=> 2000
r.foo #=> NoMethodError
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"&method_missing(symbol [, *args] );T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[[I"symbol[, *args];T0;$@;![ ;"I"Invoked by Ruby when obj is sent a message it cannot handle.
symbol is the symbol for the method called, and args
are any arguments that were passed to it. By default, the interpreter
raises an error when this method is called. However, it is possible
to override the method to provide more dynamic behavior.
If it is decided that a particular method should not be handled, then
super should be called, so that ancestors can pick up the
missing method.
The example below creates
a class Roman, which responds to methods with names
consisting of roman numerals, returning the corresponding integer
values.
class Roman
def roman_to_int(str)
# ...
end
def method_missing(symbol, *args)
str = symbol.id2name
begin
roman_to_int(str)
rescue
super(symbol, *args)
end
end
end
r = Roman.new
r.iv #=> 4
r.xxiii #=> 23
r.mm #=> 2000
r.foo #=> NoMethodError
@overload method_missing(symbol [, *args] );T;#0;$@;.F;/o;0;1T;2ir;3i;%@;9I"static VALUE
rb_method_missing(int argc, const VALUE *argv, VALUE obj)
{
rb_execution_context_t *ec = GET_EC();
raise_method_missing(ec, argc, argv, obj, ec->method_missing_reason);
UNREACHABLE_RETURN(Qnil);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"BasicObject#__send__;F;7[[@90;[[@Ci ;T;;|;0; [ ; { ; IC; "!Invokes the method identified by _symbol_, passing it any
arguments specified.
When the method is identified by a string, the string is converted
to a symbol.
BasicObject implements +__send__+, Kernel implements +send+.
__send__ is safer than +send+
when _obj_ has the same method name like Socket.
See also public_send.
class Klass
def hello(*args)
"Hello " + args.join(' ')
end
end
k = Klass.new
k.send :hello, "gentle", "readers" #=> "Hello gentle readers"
;T; [ o;=
;>I"
overload;F;?0;;{;@0;:I" send(symbol [, args...]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@,;![ ;"I"@return [Object];T;#0;$@,;.F;Bi ;C0;7[[I"symbol[, args...];T0;$@,o;=
;>I"
overload;F;?0;;|;@0;:I"!__send__(symbol [, args...]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@,;![ ;"I"@return [Object];T;#0;$@,;.F;Bi ;C0;7[[I"symbol[, args...];T0;$@,o;=
;>I"
overload;F;?0;;{;@0;:I" send(string [, args...]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@,;![ ;"I"@return [Object];T;#0;$@,;.F;Bi ;C0;7[[I"string[, args...];T0;$@,o;=
;>I"
overload;F;?0;;|;@0;:I"!__send__(string [, args...]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@,;![ ;"I"@return [Object];T;#0;$@,;.F;Bi ;C0;7[[I"string[, args...];T0;$@,;![ ;"@;#0;$@,;.F;/o;0;1T;2i;3i ;%@;9I"vVALUE
rb_f_send(int argc, VALUE *argv, VALUE recv)
{
return send_internal_kw(argc, argv, recv, CALL_FCALL);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"BasicObject#__id__;F;7[ ;[[@?iU;T;: __id__;0; [ ; { ; IC; "4call-seq:
obj.__id__ -> integer
obj.object_id -> integer
Returns an integer identifier for +obj+.
The same number will be returned on all calls to +object_id+ for a given
object, and no two active objects will share an id.
Note: that some objects of builtin classes are reused for optimization.
This is the case for immediate values and frozen string literals.
BasicObject implements +__id__+, Kernel implements +object_id+.
Immediate values are not passed by reference but are passed by value:
+nil+, +true+, +false+, Fixnums, Symbols, and some Floats.
Object.new.object_id == Object.new.object_id # => false
(21 * 2).object_id == (21 * 2).object_id # => true
"hello".object_id == "hello".object_id # => false
"hi".freeze.object_id == "hi".freeze.object_id # => true
;T; [ ;![ ;"@E;#0;$@v;.F;/o;0;1T;2i:;3iP;%@;9I"VALUE
rb_obj_id(VALUE obj)
{
/*
* 32-bit VALUE space
* MSB ------------------------ LSB
* false 00000000000000000000000000000000
* true 00000000000000000000000000000010
* nil 00000000000000000000000000000100
* undef 00000000000000000000000000000110
* symbol ssssssssssssssssssssssss00001110
* object oooooooooooooooooooooooooooooo00 = 0 (mod sizeof(RVALUE))
* fixnum fffffffffffffffffffffffffffffff1
*
* object_id space
* LSB
* false 00000000000000000000000000000000
* true 00000000000000000000000000000010
* nil 00000000000000000000000000000100
* undef 00000000000000000000000000000110
* symbol 000SSSSSSSSSSSSSSSSSSSSSSSSSSS0 S...S % A = 4 (S...S = s...s * A + 4)
* object oooooooooooooooooooooooooooooo0 o...o % A = 0
* fixnum fffffffffffffffffffffffffffffff1 bignum if required
*
* where A = sizeof(RVALUE)/4
*
* sizeof(RVALUE) is
* 20 if 32-bit, double is 4-byte aligned
* 24 if 32-bit, double is 8-byte aligned
* 40 if 64-bit
*/
return rb_find_object_id(obj, cached_object_id);
};T;:I"
VALUE;T;;T;
@; IC;[ ;
@; IC;[ ;
@;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[@include Kernel to obtain +puts+, +exit+, etc. A custom
Kernel-like module could be created and included or delegation can be used
via #method_missing:
class MyObjectSystem < BasicObject
DELEGATE = [:puts, :p]
def method_missing(name, *args, &block)
return super unless DELEGATE.include? name
::Kernel.send(name, *args, &block)
end
def respond_to_missing?(name, include_private = false)
DELEGATE.include?(name) or super
end
end
Access to classes and modules from the Ruby standard library can be
obtained in a BasicObject subclass by referencing the desired constant
from the root like ::File or ::Enumerator.
Like #method_missing, #const_missing can be used to delegate constant
lookup to +Object+:
class MyObjectSystem < BasicObject
def self.const_missing(name)
::Object.const_get(name)
end
end
=== What's Here
These are the methods defined for \BasicObject:
- ::new:: Returns a new \BasicObject instance.
- {!}[#method-i-21]:: Returns the boolean negation of +self+: +true+ or +false+.
- {!=}[#method-i-21-3D]:: Returns whether +self+ and the given object
are _not_ equal.
- {==}[#method-i-3D-3D]:: Returns whether +self+ and the given object
are equivalent.
- {__id__}[#method-i-__id__]:: Returns the integer object identifier for +self+.
- {__send__}[#method-i-__send__]:: Calls the method identified by the given symbol.
- #equal?:: Returns whether +self+ and the given object are the same object.
- #instance_eval:: Evaluates the given string or block in the context of +self+.
- #instance_exec:: Executes the given block in the context of +self+,
passing the given arguments.
- #method_missing:: Method called when an undefined method is called on +self+.
- #singleton_method_added:: Method called when a singleton method
is added to +self+.
- #singleton_method_removed:: Method called when a singleton method
is added removed from +self+.
- #singleton_method_undefined:: Method called when a singleton method
is undefined in +self+.;T; [ ;![ ;"I"
BasicObject is the parent class of all classes in Ruby. It's an explicit
blank class.
BasicObject can be used for creating object hierarchies independent of
Ruby's object hierarchy, proxy objects like the Delegator class, or other
uses where namespace pollution from Ruby's methods and classes must be
avoided.
To avoid polluting BasicObject for other users an appropriately named
subclass of BasicObject should be created instead of directly modifying
BasicObject:
class MyObjectSystem < BasicObject
end
BasicObject does not include Kernel (for methods like +puts+) and
BasicObject is outside of the namespace of the standard library so common
classes will not be found without using a full class path.
A variety of strategies can be used to provide useful portions of the
standard library to subclasses of BasicObject. A subclass could
include Kernel to obtain +puts+, +exit+, etc. A custom
Kernel-like module could be created and included or delegation can be used
via #method_missing:
class MyObjectSystem < BasicObject
DELEGATE = [:puts, :p]
def method_missing(name, *args, &block)
return super unless DELEGATE.include? name
::Kernel.send(name, *args, &block)
end
def respond_to_missing?(name, include_private = false)
DELEGATE.include?(name) or super
end
end
Access to classes and modules from the Ruby standard library can be
obtained in a BasicObject subclass by referencing the desired constant
from the root like ::File or ::Enumerator.
Like #method_missing, #const_missing can be used to delegate constant
lookup to +Object+:
class MyObjectSystem < BasicObject
def self.const_missing(name)
::Object.const_get(name)
end
end
=== What's Here
These are the methods defined for \BasicObject:
- ::new:: Returns a new \BasicObject instance.
- {!}[#method-i-21]:: Returns the boolean negation of +self+: +true+ or +false+.
- {!=}[#method-i-21-3D]:: Returns whether +self+ and the given object
are _not_ equal.
- {==}[#method-i-3D-3D]:: Returns whether +self+ and the given object
are equivalent.
- {__id__}[#method-i-__id__]:: Returns the integer object identifier for +self+.
- {__send__}[#method-i-__send__]:: Calls the method identified by the given symbol.
- #equal?:: Returns whether +self+ and the given object are the same object.
- #instance_eval:: Evaluates the given string or block in the context of +self+.
- #instance_exec:: Executes the given block in the context of +self+,
passing the given arguments.
- #method_missing:: Method called when an undefined method is called on +self+.
- #singleton_method_added:: Method called when a singleton method
is added to +self+.
- #singleton_method_removed:: Method called when a singleton method
is added removed from +self+.
- #singleton_method_undefined:: Method called when a singleton method
is undefined in +self+.
;T;#0;$@;.F;/o;0;1T;2i;;3i;Bi ;%@;&I"BasicObject;F;'o;( ;)0;*0;+0;: Qnil;%@;-0:
@type;;;o;4;5F;6;;;;&I" StringScanner#initialize;F;7[[@90;[[@i;T;;D;0; [ ; { ; IC; "Creates a new StringScanner object to scan over the given +string+.
If +fixed_anchor+ is +true+, +\A+ always matches the beginning of
the string. Otherwise, +\A+ always matches the current position.
+dup+ argument is obsolete and not used now.
;T; [o;=
;>I"
overload;F;?0;;E;@0;:I"%new(string, fixed_anchor: false);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[[I" string;T0[I"fixed_anchor:;TI"
false;T;$@o;=
;>I"
overload;F;?0;;E;@0;:I" new(string, dup = false);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[[I" string;T0[I"dup;TI"
false;T;$@;![ ;"I"ECreates a new StringScanner object to scan over the given +string+.
If +fixed_anchor+ is +true+, +\A+ always matches the beginning of
the string. Otherwise, +\A+ always matches the current position.
+dup+ argument is obsolete and not used now.
@overload new(string, fixed_anchor: false)
@overload new(string, dup = false);T;#0;$@;.F;/o;0;1T;2i;3i;%@;9I"static VALUE
strscan_initialize(int argc, VALUE *argv, VALUE self)
{
struct strscanner *p;
VALUE str, options;
p = check_strscan(self);
rb_scan_args(argc, argv, "11", &str, &options);
options = rb_check_hash_type(options);
if (!NIL_P(options)) {
VALUE fixed_anchor;
ID keyword_ids[1];
keyword_ids[0] = rb_intern("fixed_anchor");
rb_get_kwargs(options, keyword_ids, 0, 1, &fixed_anchor);
if (fixed_anchor == Qundef) {
p->fixed_anchor_p = false;
}
else {
p->fixed_anchor_p = RTEST(fixed_anchor);
}
}
else {
p->fixed_anchor_p = false;
}
StringValue(str);
p->str = str;
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I""StringScanner#initialize_copy;F;7[[I"
vorig;T0;[[@i;T;;];0; [ ; { ; IC; "'Duplicates a StringScanner object.
;T; [o;=
;>I"
overload;F;?0;;[;@0;:I"dup;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[ ;$@o;=
;>I"
overload;F;?0;:
clone;@0;:I"
clone;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"GDuplicates a StringScanner object.
@overload dup
@overload clone;T;#0;$@;.F;/o;0;1T;2i ;3i;%@;9I"static VALUE
strscan_init_copy(VALUE vself, VALUE vorig)
{
struct strscanner *self, *orig;
self = check_strscan(vself);
orig = check_strscan(vorig);
if (self != orig) {
self->flags = orig->flags;
self->str = orig->str;
self->prev = orig->prev;
self->curr = orig->curr;
if (rb_reg_region_copy(&self->regs, &orig->regs))
rb_memerror();
RB_GC_GUARD(vorig);
}
return vself;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"!StringScanner.must_C_version;F;7[ ;[[@i0;T;:must_C_version;0; [ ; { ; IC; "7This method is defined for backward compatibility.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"must_C_version;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"RThis method is defined for backward compatibility.
@overload must_C_version;T;#0;$@;.F;/o;0;1T;2i+;3i.;%@;9I"Bstatic VALUE
strscan_s_mustc(VALUE self)
{
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#reset;F;7[ ;[[@i9;T;:
reset;0; [ ; { ; IC; ">Reset the scan pointer (index 0) and clear matching data.
;T; [ ;![ ;"I"?Reset the scan pointer (index 0) and clear matching data.
;T;#0;$@;.F;/o;0;1T;2i6;3i7;%@;9I"static VALUE
strscan_reset(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
p->curr = 0;
CLEAR_MATCH_STATUS(p);
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" StringScanner#terminate;F;7[ ;[[@iK;T;:terminate;0; [ ; { ; IC; "LSets the scan pointer to the end of the string and clear matching data.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"terminate;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[ ;$@o;=
;>I"
overload;F;?0;:
clear;@0;:I"
clear;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@;.F;Bi ;C0;7[ ;$@;![ ;"I"rSets the scan pointer to the end of the string and clear matching data.
@overload terminate
@overload clear;T;#0;$@;.F;/o;0;1T;2iD;3iH;%@;9I"static VALUE
strscan_terminate(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
p->curr = S_LEN(p);
CLEAR_MATCH_STATUS(p);
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#clear;F;7[ ;[[@iZ;T;;;0; [ ; { ; IC; "OEquivalent to #terminate.
This method is obsolete; use #terminate instead.
;T; [ ;![ ;"I"PEquivalent to #terminate.
This method is obsolete; use #terminate instead.
;T;#0;$@";.F;/o;0;1T;2iV;3iX;%@;9I"static VALUE
strscan_clear(VALUE self)
{
rb_warning("StringScanner#clear is obsolete; use #terminate instead");
return strscan_terminate(self);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#string;F;7[ ;[[@id;T;: string;0; [ ; { ; IC; "&Returns the string being scanned.
;T; [ ;![ ;"I"'Returns the string being scanned.
;T;#0;$@0;.F;/o;0;1T;2ia;3ib;%@;9I"|static VALUE
strscan_get_string(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return p->str;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#string=;F;7[[I"str;T0;[[@is;T;: string=;0; [ ; { ; IC; "UChanges the string being scanned to +str+ and resets the scanner.
Returns +str+.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"string=(str);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@>;.F;Bi ;C0;7[[I"str;T0;$@>;![ ;"I"nChanges the string being scanned to +str+ and resets the scanner.
Returns +str+.
@overload string=(str);T;#0;$@>;.F;/o;0;1T;2im;3iq;%@;9I"static VALUE
strscan_set_string(VALUE self, VALUE str)
{
struct strscanner *p = check_strscan(self);
StringValue(str);
p->str = str;
p->curr = 0;
CLEAR_MATCH_STATUS(p);
return str;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#concat;F;7[[I"str;T0;[[@i;T;: concat;0; [ ; { ; IC; " Appends +str+ to the string being scanned.
This method does not affect scan pointer.
s = StringScanner.new("Fri Dec 12 1975 14:39")
s.scan(/Fri /)
s << " +1000 GMT"
s.string # -> "Fri Dec 12 1975 14:39 +1000 GMT"
s.scan(/Dec/) # -> "Dec"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"concat(str);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@X;.F;Bi ;C0;7[[I"str;T0;$@Xo;=
;>I"
overload;F;?0;:<<;@0;:I" <<(str);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@X;.F;Bi ;C0;7[[I"str;T0;$@X;![ ;"I"3Appends +str+ to the string being scanned.
This method does not affect scan pointer.
s = StringScanner.new("Fri Dec 12 1975 14:39")
s.scan(/Fri /)
s << " +1000 GMT"
s.string # -> "Fri Dec 12 1975 14:39 +1000 GMT"
s.scan(/Dec/) # -> "Dec"
@overload concat(str)
@overload <<(str);T;#0;$@X;.F;/o;0;1T;2i;3i;%@;9I"static VALUE
strscan_concat(VALUE self, VALUE str)
{
struct strscanner *p;
GET_SCANNER(self, p);
StringValue(str);
rb_str_append(p->str, str);
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#<<;F;7[[I"str;T0;[[@i;T;;;0; [ ; { ; IC; " Appends +str+ to the string being scanned.
This method does not affect scan pointer.
s = StringScanner.new("Fri Dec 12 1975 14:39")
s.scan(/Fri /)
s << " +1000 GMT"
s.string # -> "Fri Dec 12 1975 14:39 +1000 GMT"
s.scan(/Dec/) # -> "Dec"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"concat(str);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@|;.F;Bi ;C0;7[[I"str;T0;$@|o;=
;>I"
overload;F;?0;;;@0;:I" <<(str);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@|;.F;Bi ;C0;7[[I"str;T0;$@|;![ ;"@x;#0;$@|;.F;/o;0;1T;2i;3i;%@;9I"static VALUE
strscan_concat(VALUE self, VALUE str)
{
struct strscanner *p;
GET_SCANNER(self, p);
StringValue(str);
rb_str_append(p->str, str);
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"StringScanner#pos;F;7[ ;[[@i;T;:pos;0; [ ; { ; IC; "Returns the byte position of the scan pointer. In the 'reset' position, this
value is zero. In the 'terminated' position (i.e. the string is exhausted),
this value is the bytesize of the string.
In short, it's a 0-based index into bytes of the string.
s = StringScanner.new('test string')
s.pos # -> 0
s.scan_until /str/ # -> "test str"
s.pos # -> 8
s.terminate # -> #Thread.current.report_on_exception = false
when starting the Thread.
However, this might handle the exception much later, or not at all
if the Thread is never joined due to the parent thread being blocked, etc.
See also ::report_on_exception=.
There is also an instance level method to set this for a specific thread,
see #report_on_exception=.
;T; [o;=
;>I"
overload;F;?0;;,;@0;:I"report_on_exception;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@ ;![ ;"I"@return [Boolean];T;#0;$@ ;.F;Bi ;C0;7[ ;$@ ;![ ;"I"Returns the status of the global ``report on exception'' condition.
The default is +true+ since Ruby 2.5.
All threads created when this flag is true will report
a message on $stderr if an exception kills the thread.
Thread.new { 1.times { raise } }
will produce this output on $stderr:
#Thread.current.report_on_exception = false
when starting the Thread.
However, this might handle the exception much later, or not at all
if the Thread is never joined due to the parent thread being blocked, etc.
See also ::report_on_exception=.
There is also an instance level method to set this for a specific thread,
see #report_on_exception=.
@overload report_on_exception
@return [Boolean];T;#0;$@ ;.F;/o;0;1T;2i ;3i ;%@H;9I"ustatic VALUE
rb_thread_s_report_exc(VALUE _)
{
return RBOOL(GET_THREAD()->vm->thread_report_on_exception);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Thread.report_on_exception=;F;7[[I"val;T0;[[@i4 ;T;:report_on_exception=;0; [ ; { ; IC; "Returns the new state.
When set to +true+, all threads created afterwards will inherit the
condition and report a message on $stderr if an exception kills a thread:
Thread.report_on_exception = true
t1 = Thread.new do
puts "In new thread"
raise "Exception from thread"
end
sleep(1)
puts "In the main thread"
This will produce:
In new thread
#ExceptionClass =>
:TimingSymbol. Where the ExceptionClass is the interrupt handled by
the given block. The TimingSymbol can be one of the following symbols:
[+:immediate+] Invoke interrupts immediately.
[+:on_blocking+] Invoke interrupts while _BlockingOperation_.
[+:never+] Never invoke all interrupts.
_BlockingOperation_ means that the operation will block the calling thread,
such as read and write. On CRuby implementation, _BlockingOperation_ is any
operation executed without GVL.
Masked asynchronous interrupts are delayed until they are enabled.
This method is similar to sigprocmask(3).
=== NOTE
Asynchronous interrupts are difficult to use.
If you need to communicate between threads, please consider to use another way such as Queue.
Or use them with deep understanding about this method.
=== Usage
In this example, we can guard from Thread#raise exceptions.
Using the +:never+ TimingSymbol the RuntimeError exception will always be
ignored in the first block of the main thread. In the second
::handle_interrupt block we can purposefully handle RuntimeError exceptions.
th = Thread.new do
Thread.handle_interrupt(RuntimeError => :never) {
begin
# You can write resource allocation code safely.
Thread.handle_interrupt(RuntimeError => :immediate) {
# ...
}
ensure
# You can write resource deallocation code safely.
end
}
end
Thread.pass
# ...
th.raise "stop"
While we are ignoring the RuntimeError exception, it's safe to write our
resource allocation code. Then, the ensure block is where we can safely
deallocate your resources.
==== Guarding from Timeout::Error
In the next example, we will guard from the Timeout::Error exception. This
will help prevent from leaking resources when Timeout::Error exceptions occur
during normal ensure clause. For this example we use the help of the
standard library Timeout, from lib/timeout.rb
require 'timeout'
Thread.handle_interrupt(Timeout::Error => :never) {
timeout(10){
# Timeout::Error doesn't occur here
Thread.handle_interrupt(Timeout::Error => :on_blocking) {
# possible to be killed by Timeout::Error
# while blocking operation
}
# Timeout::Error doesn't occur here
}
}
In the first part of the +timeout+ block, we can rely on Timeout::Error being
ignored. Then in the Timeout::Error => :on_blocking block, any
operation that will block the calling thread is susceptible to a
Timeout::Error exception being raised.
==== Stack control settings
It's possible to stack multiple levels of ::handle_interrupt blocks in order
to control more than one ExceptionClass and TimingSymbol at a time.
Thread.handle_interrupt(FooError => :never) {
Thread.handle_interrupt(BarError => :never) {
# FooError and BarError are prohibited.
}
}
==== Inheritance with ExceptionClass
All exceptions inherited from the ExceptionClass parameter will be considered.
Thread.handle_interrupt(Exception => :never) {
# all exceptions inherited from Exception are prohibited.
}
For handling all interrupts, use +Object+ and not +Exception+
as the ExceptionClass, as kill/terminate interrupts are not handled by +Exception+.
;T; [o;=
;>I"
overload;F;?0;;2;@0;:I"handle_interrupt(hash);T; IC; " ;T; [o;A
;>I"
yield;F;?I"[];T;0;@0;$@D ;![ ;"I"@yield [];T;#0;$@D ;.F;Bi ;C0;7[[I" hash;T0;$@D ;![ ;"I"Changes asynchronous interrupt timing.
_interrupt_ means asynchronous event and corresponding procedure
by Thread#raise, Thread#kill, signal trap (not supported yet)
and main thread termination (if main thread terminates, then all
other thread will be killed).
The given +hash+ has pairs like ExceptionClass =>
:TimingSymbol. Where the ExceptionClass is the interrupt handled by
the given block. The TimingSymbol can be one of the following symbols:
[+:immediate+] Invoke interrupts immediately.
[+:on_blocking+] Invoke interrupts while _BlockingOperation_.
[+:never+] Never invoke all interrupts.
_BlockingOperation_ means that the operation will block the calling thread,
such as read and write. On CRuby implementation, _BlockingOperation_ is any
operation executed without GVL.
Masked asynchronous interrupts are delayed until they are enabled.
This method is similar to sigprocmask(3).
=== NOTE
Asynchronous interrupts are difficult to use.
If you need to communicate between threads, please consider to use another way such as Queue.
Or use them with deep understanding about this method.
=== Usage
In this example, we can guard from Thread#raise exceptions.
Using the +:never+ TimingSymbol the RuntimeError exception will always be
ignored in the first block of the main thread. In the second
::handle_interrupt block we can purposefully handle RuntimeError exceptions.
th = Thread.new do
Thread.handle_interrupt(RuntimeError => :never) {
begin
# You can write resource allocation code safely.
Thread.handle_interrupt(RuntimeError => :immediate) {
# ...
}
ensure
# You can write resource deallocation code safely.
end
}
end
Thread.pass
# ...
th.raise "stop"
While we are ignoring the RuntimeError exception, it's safe to write our
resource allocation code. Then, the ensure block is where we can safely
deallocate your resources.
==== Guarding from Timeout::Error
In the next example, we will guard from the Timeout::Error exception. This
will help prevent from leaking resources when Timeout::Error exceptions occur
during normal ensure clause. For this example we use the help of the
standard library Timeout, from lib/timeout.rb
require 'timeout'
Thread.handle_interrupt(Timeout::Error => :never) {
timeout(10){
# Timeout::Error doesn't occur here
Thread.handle_interrupt(Timeout::Error => :on_blocking) {
# possible to be killed by Timeout::Error
# while blocking operation
}
# Timeout::Error doesn't occur here
}
}
In the first part of the +timeout+ block, we can rely on Timeout::Error being
ignored. Then in the Timeout::Error => :on_blocking block, any
operation that will block the calling thread is susceptible to a
Timeout::Error exception being raised.
==== Stack control settings
It's possible to stack multiple levels of ::handle_interrupt blocks in order
to control more than one ExceptionClass and TimingSymbol at a time.
Thread.handle_interrupt(FooError => :never) {
Thread.handle_interrupt(BarError => :never) {
# FooError and BarError are prohibited.
}
}
==== Inheritance with ExceptionClass
All exceptions inherited from the ExceptionClass parameter will be considered.
Thread.handle_interrupt(Exception => :never) {
# all exceptions inherited from Exception are prohibited.
}
For handling all interrupts, use +Object+ and not +Exception+
as the ExceptionClass, as kill/terminate interrupts are not handled by +Exception+.
@overload handle_interrupt(hash)
@yield [];T;#0;$@D ;.F;/o;0;1T;2iT;3i;%@H;9I"tstatic VALUE
rb_thread_s_handle_interrupt(VALUE self, VALUE mask_arg)
{
VALUE mask;
rb_execution_context_t * volatile ec = GET_EC();
rb_thread_t * volatile th = rb_ec_thread_ptr(ec);
volatile VALUE r = Qnil;
enum ruby_tag_type state;
if (!rb_block_given_p()) {
rb_raise(rb_eArgError, "block is needed.");
}
mask = 0;
mask_arg = rb_to_hash_type(mask_arg);
rb_hash_foreach(mask_arg, handle_interrupt_arg_check_i, (VALUE)&mask);
if (!mask) {
return rb_yield(Qnil);
}
OBJ_FREEZE_RAW(mask);
rb_ary_push(th->pending_interrupt_mask_stack, mask);
if (!rb_threadptr_pending_interrupt_empty_p(th)) {
th->pending_interrupt_queue_checked = 0;
RUBY_VM_SET_INTERRUPT(th->ec);
}
EC_PUSH_TAG(th->ec);
if ((state = EC_EXEC_TAG()) == TAG_NONE) {
r = rb_yield(Qnil);
}
EC_POP_TAG();
rb_ary_pop(th->pending_interrupt_mask_stack);
if (!rb_threadptr_pending_interrupt_empty_p(th)) {
th->pending_interrupt_queue_checked = 0;
RUBY_VM_SET_INTERRUPT(th->ec);
}
RUBY_VM_CHECK_INTS(th->ec);
if (state) {
EC_JUMP_TAG(th->ec, state);
}
return r;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Thread.pending_interrupt?;F;7[[@90;[[@iI ;T;:pending_interrupt?;0; [ ; { ; IC; "Returns whether or not the asynchronous queue is empty.
Since Thread::handle_interrupt can be used to defer asynchronous events,
this method can be used to determine if there are any deferred events.
If you find this method returns true, then you may finish +:never+ blocks.
For example, the following method processes deferred asynchronous events
immediately.
def Thread.kick_interrupt_immediately
Thread.handle_interrupt(Object => :immediate) {
Thread.pass
}
end
If +error+ is given, then check only for +error+ type deferred events.
=== Usage
th = Thread.new{
Thread.handle_interrupt(RuntimeError => :on_blocking){
while true
...
# reach safe point to invoke interrupt
if Thread.pending_interrupt?
Thread.handle_interrupt(Object => :immediate){}
end
...
end
}
}
...
th.raise # stop thread
This example can also be written as the following, which you should use to
avoid asynchronous interrupts.
flag = true
th = Thread.new{
Thread.handle_interrupt(RuntimeError => :on_blocking){
while true
...
# reach safe point to invoke interrupt
break if flag == false
...
end
}
}
...
flag = false # stop thread;T; [o;=
;>I"
overload;F;?0;;3;@0;:I"$pending_interrupt?(error = nil);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@a ;.F;Bi ;C0;7[[I"
error;TI"nil;T;$@a o;A
;>I" return;F;?@;0;@[@L;$@a ;![ ;"I" Returns whether or not the asynchronous queue is empty.
Since Thread::handle_interrupt can be used to defer asynchronous events,
this method can be used to determine if there are any deferred events.
If you find this method returns true, then you may finish +:never+ blocks.
For example, the following method processes deferred asynchronous events
immediately.
def Thread.kick_interrupt_immediately
Thread.handle_interrupt(Object => :immediate) {
Thread.pass
}
end
If +error+ is given, then check only for +error+ type deferred events.
=== Usage
th = Thread.new{
Thread.handle_interrupt(RuntimeError => :on_blocking){
while true
...
# reach safe point to invoke interrupt
if Thread.pending_interrupt?
Thread.handle_interrupt(Object => :immediate){}
end
...
end
}
}
...
th.raise # stop thread
This example can also be written as the following, which you should use to
avoid asynchronous interrupts.
flag = true
th = Thread.new{
Thread.handle_interrupt(RuntimeError => :on_blocking){
while true
...
# reach safe point to invoke interrupt
break if flag == false
...
end
}
}
...
flag = false # stop thread
@overload pending_interrupt?(error = nil);T;#0;$@a ;.F;/o;0;1T;2i ;3iE ;Bi ;%@H;9I"static VALUE
rb_thread_s_pending_interrupt_p(int argc, VALUE *argv, VALUE self)
{
return rb_thread_pending_interrupt_p(argc, argv, GET_THREAD()->self);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Thread#pending_interrupt?;F;7[[@90;[[@i;T;;3;0; [ ; { ; IC; "Returns whether or not the asynchronous queue is empty for the target thread.
If +error+ is given, then check only for +error+ type deferred events.
See ::pending_interrupt? for more information.;T; [o;=
;>I"
overload;F;?0;;3;@0;:I"$pending_interrupt?(error = nil);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@~ ;.F;Bi ;C0;7[[I"
error;TI"nil;T;$@~ o;A
;>I" return;F;?@;0;@[@L;$@~ ;![ ;"I"Returns whether or not the asynchronous queue is empty for the target thread.
If +error+ is given, then check only for +error+ type deferred events.
See ::pending_interrupt? for more information.
@overload pending_interrupt?(error = nil);T;#0;$@~ ;.F;/o;0;1T;2i;3i;Bi ;%@H;9I"wstatic VALUE
rb_thread_pending_interrupt_p(int argc, VALUE *argv, VALUE target_thread)
{
rb_thread_t *target_th = rb_thread_ptr(target_thread);
if (!target_th->pending_interrupt_queue) {
return Qfalse;
}
if (rb_threadptr_pending_interrupt_empty_p(target_th)) {
return Qfalse;
}
if (rb_check_arity(argc, 0, 1)) {
VALUE err = argv[0];
if (!rb_obj_is_kind_of(err, rb_cModule)) {
rb_raise(rb_eTypeError, "class or module required for rescue clause");
}
return RBOOL(rb_threadptr_pending_interrupt_include_p(target_th, err));
}
else {
return Qtrue;
}
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Thread#initialize;F;7[[I" args;T0;[[@i9;T;;D;0; [ ; { ; IC; " :nodoc:
;T; [ ;![ ;"I" :nodoc:;T;#0;$@ ;.F;/o;0;1T;2i8;3i8;%@H;9I"kstatic VALUE
thread_initialize(VALUE thread, VALUE args)
{
rb_thread_t *th = rb_thread_ptr(thread);
if (!rb_block_given_p()) {
rb_raise(rb_eThreadError, "must be called with a block");
}
else if (th->invoke_type != thread_invoke_type_none) {
VALUE loc = threadptr_invoke_proc_location(th);
if (!NIL_P(loc)) {
rb_raise(rb_eThreadError,
"already initialized thread - %"PRIsVALUE":%"PRIsVALUE,
RARRAY_AREF(loc, 0), RARRAY_AREF(loc, 1));
}
else {
rb_raise(rb_eThreadError, "already initialized thread");
}
}
else {
struct thread_create_params params = {
.type = thread_invoke_type_proc,
.args = args,
.proc = rb_block_proc(),
};
return thread_create_core(thread, ¶ms);
}
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Thread#raise;F;7[[@90;[[@i[
;T;;;0; [ ; { ; IC; "]Raises an exception from the given thread. The caller does not have to be
+thr+. See Kernel#raise for more information.
Thread.abort_on_exception = true
a = Thread.new { sleep(200) }
a.raise("Gotcha")
This will produce:
prog.rb:3: Gotcha (RuntimeError)
from prog.rb:2:in `initialize'
from prog.rb:2:in `new'
from prog.rb:2
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
raise;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ o;=
;>I"
overload;F;?0;;;@0;:I"raise(string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[[I" string;T0;$@ o;=
;>I"
overload;F;?0;;;@0;:I"*raise(exception [, string [, array]]);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[[I""exception[, string [, array]];T0;$@ ;![ ;"I"Raises an exception from the given thread. The caller does not have to be
+thr+. See Kernel#raise for more information.
Thread.abort_on_exception = true
a = Thread.new { sleep(200) }
a.raise("Gotcha")
This will produce:
prog.rb:3: Gotcha (RuntimeError)
from prog.rb:2:in `initialize'
from prog.rb:2:in `new'
from prog.rb:2
@overload raise
@overload raise(string)
@overload raise(exception [, string [, array]]);T;#0;$@ ;.F;/o;0;1T;2iF
;3iW
;%@H;9I"static VALUE
thread_raise_m(int argc, VALUE *argv, VALUE self)
{
rb_thread_t *target_th = rb_thread_ptr(self);
const rb_thread_t *current_th = GET_THREAD();
threadptr_check_pending_interrupt_queue(target_th);
rb_threadptr_raise(target_th, argc, argv);
/* To perform Thread.current.raise as Kernel.raise */
if (current_th == target_th) {
RUBY_VM_CHECK_INTS(target_th->ec);
}
return Qnil;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Thread#join;F;7[[@90;[[@i$;T;: join;0; [ ; { ; IC; "The calling thread will suspend execution and run this +thr+.
Does not return until +thr+ exits or until the given +limit+ seconds have
passed.
If the time limit expires, +nil+ will be returned, otherwise +thr+ is
returned.
Any threads not joined will be killed when the main program exits.
If +thr+ had previously raised an exception and the ::abort_on_exception or
$DEBUG flags are not set, (so the exception has not yet been processed), it
will be processed at this time.
a = Thread.new { print "a"; sleep(10); print "b"; print "c" }
x = Thread.new { print "x"; Thread.pass; print "y"; print "z" }
x.join # Let thread x finish, thread a will be killed on exit.
#=> "axyz"
The following example illustrates the +limit+ parameter.
y = Thread.new { 4.times { sleep 0.1; puts 'tick... ' }}
puts "Waiting" until y.join(0.15)
This will produce:
tick...
Waiting
tick...
Waiting
tick...
tick...
;T; [o;=
;>I"
overload;F;?0;;4;@0;:I" join;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ o;=
;>I"
overload;F;?0;;4;@0;:I"join(limit);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[[I"
limit;T0;$@ ;![ ;"I"The calling thread will suspend execution and run this +thr+.
Does not return until +thr+ exits or until the given +limit+ seconds have
passed.
If the time limit expires, +nil+ will be returned, otherwise +thr+ is
returned.
Any threads not joined will be killed when the main program exits.
If +thr+ had previously raised an exception and the ::abort_on_exception or
$DEBUG flags are not set, (so the exception has not yet been processed), it
will be processed at this time.
a = Thread.new { print "a"; sleep(10); print "b"; print "c" }
x = Thread.new { print "x"; Thread.pass; print "y"; print "z" }
x.join # Let thread x finish, thread a will be killed on exit.
#=> "axyz"
The following example illustrates the +limit+ parameter.
y = Thread.new { 4.times { sleep 0.1; puts 'tick... ' }}
puts "Waiting" until y.join(0.15)
This will produce:
tick...
Waiting
tick...
Waiting
tick...
tick...
@overload join
@overload join(limit);T;#0;$@ ;.F;/o;0;1T;2i;3i ;%@H;9I"static VALUE
thread_join_m(int argc, VALUE *argv, VALUE self)
{
VALUE timeout = Qnil;
rb_hrtime_t rel = 0, *limit = 0;
if (rb_check_arity(argc, 0, 1)) {
timeout = argv[0];
}
// Convert the timeout eagerly, so it's always converted and deterministic
/*
* This supports INFINITY and negative values, so we can't use
* rb_time_interval right now...
*/
if (NIL_P(timeout)) {
/* unlimited */
}
else if (FIXNUM_P(timeout)) {
rel = rb_sec2hrtime(NUM2TIMET(timeout));
limit = &rel;
}
else {
limit = double2hrtime(&rel, rb_num2dbl(timeout));
}
return thread_join(rb_thread_ptr(self), timeout, limit);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Thread#value;F;7[ ;[[@iO;T;:
value;0; [ ; { ; IC; " Waits for +thr+ to complete, using #join, and returns its value or raises
the exception which terminated the thread.
a = Thread.new { 2 + 2 }
a.value #=> 4
b = Thread.new { raise 'something went wrong' }
b.value #=> RuntimeError: something went wrong
;T; [o;=
;>I"
overload;F;?0;;5;@0;:I"
value;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@ ;![ ;"I"@return [Object];T;#0;$@ ;.F;Bi ;C0;7[ ;$@ ;![ ;"I"1Waits for +thr+ to complete, using #join, and returns its value or raises
the exception which terminated the thread.
a = Thread.new { 2 + 2 }
a.value #=> 4
b = Thread.new { raise 'something went wrong' }
b.value #=> RuntimeError: something went wrong
@overload value
@return [Object];T;#0;$@ ;.F;/o;0;1T;2iA;3iL;%@H;9I"static VALUE
thread_value(VALUE self)
{
rb_thread_t *th = rb_thread_ptr(self);
thread_join(th, Qnil, 0);
return th->value;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Thread#kill;F;7[ ;[[@iw
;T;;(;0; [ ; { ; IC; "Terminates +thr+ and schedules another thread to be run, returning
the terminated Thread. If this is the main thread, or the last
thread, exits the process.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" exit;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ o;=
;>I"
overload;F;?0;;(;@0;:I" kill;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ o;=
;>I"
overload;F;?0;;;@0;:I"terminate;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ ;![ ;"I"Terminates +thr+ and schedules another thread to be run, returning
the terminated Thread. If this is the main thread, or the last
thread, exits the process.
@overload exit
@overload kill
@overload terminate;T;#0;$@ ;.F;/o;0;1T;2il
;3is
;%@H;9I"MVALUE
rb_thread_kill(VALUE thread)
{
rb_thread_t *th = rb_thread_ptr(thread);
if (th->to_kill || th->status == THREAD_KILLED) {
return thread;
}
if (th == th->vm->ractor.main_thread) {
rb_exit(EXIT_SUCCESS);
}
thread_debug("rb_thread_kill: %p (%"PRI_THREAD_ID")\n", (void *)th, thread_id_str(th));
if (th == GET_THREAD()) {
/* kill myself immediately */
rb_threadptr_to_kill(th);
}
else {
threadptr_check_pending_interrupt_queue(th);
rb_threadptr_pending_interrupt_enque(th, eKillSignal);
rb_threadptr_interrupt(th);
}
return thread;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Thread#terminate;F;7[ ;[[@iw
;T;;;0; [ ; { ; IC; "Terminates +thr+ and schedules another thread to be run, returning
the terminated Thread. If this is the main thread, or the last
thread, exits the process.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" exit;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@8 ;.F;Bi ;C0;7[ ;$@8 o;=
;>I"
overload;F;?0;;(;@0;:I" kill;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@8 ;.F;Bi ;C0;7[ ;$@8 o;=
;>I"
overload;F;?0;;;@0;:I"terminate;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@8 ;.F;Bi ;C0;7[ ;$@8 ;![ ;"@4 ;#0;$@8 ;.F;/o;0;1T;2il
;3is
;%@H;9I"MVALUE
rb_thread_kill(VALUE thread)
{
rb_thread_t *th = rb_thread_ptr(thread);
if (th->to_kill || th->status == THREAD_KILLED) {
return thread;
}
if (th == th->vm->ractor.main_thread) {
rb_exit(EXIT_SUCCESS);
}
thread_debug("rb_thread_kill: %p (%"PRI_THREAD_ID")\n", (void *)th, thread_id_str(th));
if (th == GET_THREAD()) {
/* kill myself immediately */
rb_threadptr_to_kill(th);
}
else {
threadptr_check_pending_interrupt_queue(th);
rb_threadptr_pending_interrupt_enque(th, eKillSignal);
rb_threadptr_interrupt(th);
}
return thread;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Thread#exit;F;7[ ;[[@iw
;T;;;0; [ ; { ; IC; "Terminates +thr+ and schedules another thread to be run, returning
the terminated Thread. If this is the main thread, or the last
thread, exits the process.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" exit;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@] ;.F;Bi ;C0;7[ ;$@] o;=
;>I"
overload;F;?0;;(;@0;:I" kill;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@] ;.F;Bi ;C0;7[ ;$@] o;=
;>I"
overload;F;?0;;;@0;:I"terminate;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@] ;.F;Bi ;C0;7[ ;$@] ;![ ;"@4 ;#0;$@] ;.F;/o;0;1T;2il
;3is
;%@H;9I"MVALUE
rb_thread_kill(VALUE thread)
{
rb_thread_t *th = rb_thread_ptr(thread);
if (th->to_kill || th->status == THREAD_KILLED) {
return thread;
}
if (th == th->vm->ractor.main_thread) {
rb_exit(EXIT_SUCCESS);
}
thread_debug("rb_thread_kill: %p (%"PRI_THREAD_ID")\n", (void *)th, thread_id_str(th));
if (th == GET_THREAD()) {
/* kill myself immediately */
rb_threadptr_to_kill(th);
}
else {
threadptr_check_pending_interrupt_queue(th);
rb_threadptr_pending_interrupt_enque(th, eKillSignal);
rb_threadptr_interrupt(th);
}
return thread;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Thread#run;F;7[ ;[[@i ;T;:run;0; [ ; { ; IC; "Wakes up +thr+, making it eligible for scheduling.
a = Thread.new { puts "a"; Thread.stop; puts "c" }
sleep 0.1 while a.status!='sleep'
puts "Got here"
a.run
a.join
This will produce:
a
Got here
c
See also the instance method #wakeup.
;T; [o;=
;>I"
overload;F;?0;;6;@0;:I"run;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ ;![ ;"I"Wakes up +thr+, making it eligible for scheduling.
a = Thread.new { puts "a"; Thread.stop; puts "c" }
sleep 0.1 while a.status!='sleep'
puts "Got here"
a.run
a.join
This will produce:
a
Got here
c
See also the instance method #wakeup.
@overload run;T;#0;$@ ;.F;/o;0;1T;2i
;3i ;%@H;9I"uVALUE
rb_thread_run(VALUE thread)
{
rb_thread_wakeup(thread);
rb_thread_schedule();
return thread;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Thread#wakeup;F;7[ ;[[@i
;T;: wakeup;0; [ ; { ; IC; "!Marks a given thread as eligible for scheduling, however it may still
remain blocked on I/O.
*Note:* This does not invoke the scheduler, see #run for more information.
c = Thread.new { Thread.stop; puts "hey!" }
sleep 0.1 while c.status!='sleep'
c.wakeup
c.join
#=> "hey!"
;T; [o;=
;>I"
overload;F;?0;;7;@0;:I" wakeup;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@ ;.F;Bi ;C0;7[ ;$@ ;![ ;"I"4Marks a given thread as eligible for scheduling, however it may still
remain blocked on I/O.
*Note:* This does not invoke the scheduler, see #run for more information.
c = Thread.new { Thread.stop; puts "hey!" }
sleep 0.1 while c.status!='sleep'
c.wakeup
c.join
#=> "hey!"
@overload wakeup;T;#0;$@ ;.F;/o;0;1T;2i
;3i
;%@H;9I"VALUE
rb_thread_wakeup(VALUE thread)
{
if (!RTEST(rb_thread_wakeup_alive(thread))) {
rb_raise(rb_eThreadError, "killed thread");
}
return thread;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Thread#[];F;7[[I"key;T0;[[@i
;T;;;0; [ ; { ; IC; "Attribute Reference---Returns the value of a fiber-local variable (current thread's root fiber
if not explicitly inside a Fiber), using either a symbol or a string name.
If the specified variable does not exist, returns +nil+.
[
Thread.new { Thread.current["name"] = "A" },
Thread.new { Thread.current[:name] = "B" },
Thread.new { Thread.current["name"] = "C" }
].each do |th|
th.join
puts "#{th.inspect}: #{th[:name]}"
end
This will produce:
#Fixnums, Symbols
true, false, and nil) are
never returned. In the example below, #each_object returns both
the numbers we defined and several constants defined in the Math
module.
If no block is given, an enumerator is returned instead.
a = 102.7
b = 95 # Won't be returned
c = 12345678987654321
count = ObjectSpace.each_object(Numeric) {|x| p x }
puts "Total count: #{count}"
produces:
12345678987654321
102.7
2.71828182845905
3.14159265358979
2.22044604925031e-16
1.7976931348623157e+308
2.2250738585072e-308
Total count: 7
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"each_object([module]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"obj;T;$@*o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@*;![ ;"I"#@yield [obj]
@return [Integer];T;#0;$@*;.F;Bi ;C0;7[[I"[;T0;$@*o;=
;>I"
overload;F;?0;;;@0;:I"each_object([module]);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@*;.F;Bi ;C0;7[[I"[;T0;$@*;![ ;"I"Calls the block once for each living, nonimmediate object in this
Ruby process. If module is specified, calls the block
for only those classes or modules that match (or are a subclass of)
module. Returns the number of objects found. Immediate
objects (Fixnums, Symbols
true, false, and nil) are
never returned. In the example below, #each_object returns both
the numbers we defined and several constants defined in the Math
module.
If no block is given, an enumerator is returned instead.
a = 102.7
b = 95 # Won't be returned
c = 12345678987654321
count = ObjectSpace.each_object(Numeric) {|x| p x }
puts "Total count: #{count}"
produces:
12345678987654321
102.7
2.71828182845905
3.14159265358979
2.22044604925031e-16
1.7976931348623157e+308
2.2250738585072e-308
Total count: 7
@overload each_object([module])
@yield [obj]
@return [Integer]
@overload each_object([module])
;T;#0;$@*;.F;C0;%@&;9I"static VALUE
os_each_obj(int argc, VALUE *argv, VALUE os)
{
VALUE of;
of = (!rb_check_arity(argc, 0, 1) ? 0 : argv[0]);
RETURN_ENUMERATOR(os, 1, &of);
return os_obj_of(of);
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I" ObjectSpace.each_object;F;7@*;@*;T;;;0; @*; { ; IC; "Calls the block once for each living, nonimmediate object in this
Ruby process. If module is specified, calls the block
for only those classes or modules that match (or are a subclass of)
module. Returns the number of objects found. Immediate
objects (Fixnums, Symbols
true, false, and nil) are
never returned. In the example below, #each_object returns both
the numbers we defined and several constants defined in the Math
module.
If no block is given, an enumerator is returned instead.
a = 102.7
b = 95 # Won't be returned
c = 12345678987654321
count = ObjectSpace.each_object(Numeric) {|x| p x }
puts "Total count: #{count}"
produces:
12345678987654321
102.7
2.71828182845905
3.14159265358979
2.22044604925031e-16
1.7976931348623157e+308
2.2250738585072e-308
Total count: 7;T; [o;=
;>I"
overload;F;?0;;;@0;:I"each_object([module]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"obj;T;$@$+o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@$+;![ ;"I"#@yield [obj]
@return [Integer];T;#0;$@$+;.F;Bi ;C0;7[[I"[;T0;$@$+o;=
;>I"
overload;F;?0;;;@0;:I"each_object([module]);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@$+;.F;Bi ;C0;7[[I"[;T0;$@$+;![ ;"I"Calls the block once for each living, nonimmediate object in this
Ruby process. If module is specified, calls the block
for only those classes or modules that match (or are a subclass of)
module. Returns the number of objects found. Immediate
objects (Fixnums, Symbols
true, false, and nil) are
never returned. In the example below, #each_object returns both
the numbers we defined and several constants defined in the Math
module.
If no block is given, an enumerator is returned instead.
a = 102.7
b = 95 # Won't be returned
c = 12345678987654321
count = ObjectSpace.each_object(Numeric) {|x| p x }
puts "Total count: #{count}"
produces:
12345678987654321
102.7
2.71828182845905
3.14159265358979
2.22044604925031e-16
1.7976931348623157e+308
2.2250738585072e-308
Total count: 7
@overload each_object([module])
@yield [obj]
@return [Integer]
@overload each_object([module]);T;#0;$@$+;.F;/o;0;1T;2i;3i;Bi ;%@&;9@"+;:@#+;;To;4;5F;6;;;;&I"!ObjectSpace#define_finalizer;F;7[[@90;[[@?i ;T;:define_finalizer;0; [ ; { ; IC; "KAdds aProc as a finalizer, to be called after obj
was destroyed. The object ID of the obj will be passed
as an argument to aProc. If aProc is a lambda or
method, make sure it can be called with a single argument.
The return value is an array [0, aProc].
The two recommended patterns are to either create the finaliser proc
in a non-instance method where it can safely capture the needed state,
or to use a custom callable object that stores the needed state
explicitly as instance variables.
class Foo
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
end
def self.create_finalizer(data_needed_for_finalization)
proc {
puts "finalizing #{data_needed_for_finalization}"
}
end
end
class Bar
class Remover
def initialize(data_needed_for_finalization)
@data_needed_for_finalization = data_needed_for_finalization
end
def call(id)
puts "finalizing #{@data_needed_for_finalization}"
end
end
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
end
end
Note that if your finalizer references the object to be
finalized it will never be run on GC, although it will still be
run at exit. You will get a warning if you capture the object
to be finalized as the receiver of the finalizer.
class CapturesSelf
def initialize(name)
ObjectSpace.define_finalizer(self, proc {
# this finalizer will only be run on exit
puts "finalizing #{name}"
})
end
end
Also note that finalization can be unpredictable and is never guaranteed
to be run except on exit.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"(define_finalizer(obj, aProc=proc());T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@J+;.F;Bi ;C0;7[[I"obj;T0[I"
aProc;TI" proc();T;$@J+;![ ;"I"zAdds aProc as a finalizer, to be called after obj
was destroyed. The object ID of the obj will be passed
as an argument to aProc. If aProc is a lambda or
method, make sure it can be called with a single argument.
The return value is an array [0, aProc].
The two recommended patterns are to either create the finaliser proc
in a non-instance method where it can safely capture the needed state,
or to use a custom callable object that stores the needed state
explicitly as instance variables.
class Foo
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
end
def self.create_finalizer(data_needed_for_finalization)
proc {
puts "finalizing #{data_needed_for_finalization}"
}
end
end
class Bar
class Remover
def initialize(data_needed_for_finalization)
@data_needed_for_finalization = data_needed_for_finalization
end
def call(id)
puts "finalizing #{@data_needed_for_finalization}"
end
end
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
end
end
Note that if your finalizer references the object to be
finalized it will never be run on GC, although it will still be
run at exit. You will get a warning if you capture the object
to be finalized as the receiver of the finalizer.
class CapturesSelf
def initialize(name)
ObjectSpace.define_finalizer(self, proc {
# this finalizer will only be run on exit
puts "finalizing #{name}"
})
end
end
Also note that finalization can be unpredictable and is never guaranteed
to be run except on exit.
@overload define_finalizer(obj, aProc=proc())
;T;#0;$@J+;.F;C0;%@&;9I"static VALUE
define_final(int argc, VALUE *argv, VALUE os)
{
VALUE obj, block;
rb_scan_args(argc, argv, "11", &obj, &block);
should_be_finalizable(obj);
if (argc == 1) {
block = rb_block_proc();
}
else {
should_be_callable(block);
}
if (rb_callable_receiver(block) == obj) {
rb_warn("finalizer references object to be finalized");
}
return define_final0(obj, block);
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I"!ObjectSpace.define_finalizer;F;7@L+;@N+;T;;;0; @P+; { ; IC; "KAdds aProc as a finalizer, to be called after obj
was destroyed. The object ID of the obj will be passed
as an argument to aProc. If aProc is a lambda or
method, make sure it can be called with a single argument.
The return value is an array [0, aProc].
The two recommended patterns are to either create the finaliser proc
in a non-instance method where it can safely capture the needed state,
or to use a custom callable object that stores the needed state
explicitly as instance variables.
class Foo
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
end
def self.create_finalizer(data_needed_for_finalization)
proc {
puts "finalizing #{data_needed_for_finalization}"
}
end
end
class Bar
class Remover
def initialize(data_needed_for_finalization)
@data_needed_for_finalization = data_needed_for_finalization
end
def call(id)
puts "finalizing #{@data_needed_for_finalization}"
end
end
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
end
end
Note that if your finalizer references the object to be
finalized it will never be run on GC, although it will still be
run at exit. You will get a warning if you capture the object
to be finalized as the receiver of the finalizer.
class CapturesSelf
def initialize(name)
ObjectSpace.define_finalizer(self, proc {
# this finalizer will only be run on exit
puts "finalizing #{name}"
})
end
end
Also note that finalization can be unpredictable and is never guaranteed
to be run except on exit.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"(define_finalizer(obj, aProc=proc());T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@e+;.F;Bi ;C0;7[[I"obj;T0[I"
aProc;TI" proc();T;$@e+;![ ;"I"{Adds aProc as a finalizer, to be called after obj
was destroyed. The object ID of the obj will be passed
as an argument to aProc. If aProc is a lambda or
method, make sure it can be called with a single argument.
The return value is an array [0, aProc].
The two recommended patterns are to either create the finaliser proc
in a non-instance method where it can safely capture the needed state,
or to use a custom callable object that stores the needed state
explicitly as instance variables.
class Foo
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
end
def self.create_finalizer(data_needed_for_finalization)
proc {
puts "finalizing #{data_needed_for_finalization}"
}
end
end
class Bar
class Remover
def initialize(data_needed_for_finalization)
@data_needed_for_finalization = data_needed_for_finalization
end
def call(id)
puts "finalizing #{@data_needed_for_finalization}"
end
end
def initialize(data_needed_for_finalization)
ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
end
end
Note that if your finalizer references the object to be
finalized it will never be run on GC, although it will still be
run at exit. You will get a warning if you capture the object
to be finalized as the receiver of the finalizer.
class CapturesSelf
def initialize(name)
ObjectSpace.define_finalizer(self, proc {
# this finalizer will only be run on exit
puts "finalizing #{name}"
})
end
end
Also note that finalization can be unpredictable and is never guaranteed
to be run except on exit.
@overload define_finalizer(obj, aProc=proc());T;#0;$@e+;.F;/o;0;1T;2i;3i;Bi ;%@&;9@c+;:@d+;;To;4;5F;6;;;;&I"#ObjectSpace#undefine_finalizer;F;7[[I"obj;T0;[[@?i;T;:undefine_finalizer;0; [ ; { ; IC; "+Removes all finalizers for obj.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" undefine_finalizer(obj);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@z+;.F;Bi ;C0;7[[I"obj;T0;$@z+;![ ;"I"NRemoves all finalizers for obj.
@overload undefine_finalizer(obj)
;T;#0;$@z+;.F;C0;%@&;9I"`static VALUE
undefine_final(VALUE os, VALUE obj)
{
return rb_undefine_finalizer(obj);
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I"#ObjectSpace.undefine_finalizer;F;7@|+;@+;T;;;0; @+; { ; IC; "+Removes all finalizers for obj.;T; [o;=
;>I"
overload;F;?0;;;@0;:I" undefine_finalizer(obj);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@+;.F;Bi ;C0;7[[I"obj;T0;$@+;![ ;"I"PRemoves all finalizers for obj.
@overload undefine_finalizer(obj);T;#0;$@+;.F;/o;0;1T;2i;3i;Bi ;%@&;9@+;:@+;;To;4;5F;6;;;;&I"ObjectSpace#_id2ref;F;7[[I"
objid;T0;[[@?i;T;: _id2ref;0; [ ; { ; IC; "
;T; [ ;![ ;"I" ;F;#0;$@+;.F;C0;%@&;9I"Pstatic VALUE
os_id2ref(VALUE os, VALUE objid)
{
return id2ref(objid);
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I"ObjectSpace._id2ref;F;7@+;@+;T;;;0; @+; { ; IC; " ;T; [ ;![ ;"@;#0;$@+;Bi ;%@&;9@+;:@+;;To;4;5F;6;;;;&I" ObjectSpace#count_objects;F;7[[@90;[[@?ik;T;:count_objects;0; [ ; { ; IC; "Counts all objects grouped by type.
It returns a hash, such as:
{
:TOTAL=>10000,
:FREE=>3011,
:T_OBJECT=>6,
:T_CLASS=>404,
# ...
}
The contents of the returned hash are implementation specific.
It may be changed in future.
The keys starting with +:T_+ means live objects.
For example, +:T_ARRAY+ is the number of arrays.
+:FREE+ means object slots which is not used now.
+:TOTAL+ means sum of above.
If the optional argument +result_hash+ is given,
it is overwritten and returned. This is intended to avoid probe effect.
h = {}
ObjectSpace.count_objects(h)
puts h
# => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }
This method is only expected to work on C Ruby.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"!count_objects([result_hash]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Hash;T;$@+;![ ;"I"@return [Hash];T;#0;$@+;.F;Bi ;C0;7[[I"[result_hash];T0;$@+;![ ;"I"Counts all objects grouped by type.
It returns a hash, such as:
{
:TOTAL=>10000,
:FREE=>3011,
:T_OBJECT=>6,
:T_CLASS=>404,
# ...
}
The contents of the returned hash are implementation specific.
It may be changed in future.
The keys starting with +:T_+ means live objects.
For example, +:T_ARRAY+ is the number of arrays.
+:FREE+ means object slots which is not used now.
+:TOTAL+ means sum of above.
If the optional argument +result_hash+ is given,
it is overwritten and returned. This is intended to avoid probe effect.
h = {}
ObjectSpace.count_objects(h)
puts h
# => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }
This method is only expected to work on C Ruby.
@overload count_objects([result_hash])
@return [Hash];T;#0;$@+;.F;C0;%@&;9I"static VALUE
count_objects(int argc, VALUE *argv, VALUE os)
{
rb_objspace_t *objspace = &rb_objspace;
size_t counts[T_MASK+1];
size_t freed = 0;
size_t total = 0;
size_t i;
VALUE hash = Qnil;
if (rb_check_arity(argc, 0, 1) == 1) {
hash = argv[0];
if (!RB_TYPE_P(hash, T_HASH))
rb_raise(rb_eTypeError, "non-hash given");
}
for (i = 0; i <= T_MASK; i++) {
counts[i] = 0;
}
for (i = 0; i < heap_allocated_pages; i++) {
struct heap_page *page = heap_pages_sorted[i];
short stride = page->slot_size;
uintptr_t p = (uintptr_t)page->start;
uintptr_t pend = p + page->total_slots * stride;
for (;p < pend; p += stride) {
VALUE vp = (VALUE)p;
GC_ASSERT((NUM_IN_PAGE(vp) * sizeof(RVALUE)) % page->slot_size == 0);
void *poisoned = asan_poisoned_object_p(vp);
asan_unpoison_object(vp, false);
if (RANY(p)->as.basic.flags) {
counts[BUILTIN_TYPE(vp)]++;
}
else {
freed++;
}
if (poisoned) {
GC_ASSERT(BUILTIN_TYPE(vp) == T_NONE);
asan_poison_object(vp);
}
}
total += page->total_slots;
}
if (NIL_P(hash)) {
hash = rb_hash_new();
}
else if (!RHASH_EMPTY_P(hash)) {
rb_hash_stlike_foreach(hash, set_zero, hash);
}
rb_hash_aset(hash, ID2SYM(rb_intern("TOTAL")), SIZET2NUM(total));
rb_hash_aset(hash, ID2SYM(rb_intern("FREE")), SIZET2NUM(freed));
for (i = 0; i <= T_MASK; i++) {
VALUE type = type_sym(i);
if (counts[i])
rb_hash_aset(hash, type, SIZET2NUM(counts[i]));
}
return hash;
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I" ObjectSpace.count_objects;F;7@+;@+;T;;;0; @+; { ; IC; "Counts all objects grouped by type.
It returns a hash, such as:
{
:TOTAL=>10000,
:FREE=>3011,
:T_OBJECT=>6,
:T_CLASS=>404,
# ...
}
The contents of the returned hash are implementation specific.
It may be changed in future.
The keys starting with +:T_+ means live objects.
For example, +:T_ARRAY+ is the number of arrays.
+:FREE+ means object slots which is not used now.
+:TOTAL+ means sum of above.
If the optional argument +result_hash+ is given,
it is overwritten and returned. This is intended to avoid probe effect.
h = {}
ObjectSpace.count_objects(h)
puts h
# => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }
This method is only expected to work on C Ruby.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"!count_objects([result_hash]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Hash;T;$@+;![ ;"I"@return [Hash];T;#0;$@+;.F;Bi ;C0;7[[I"[result_hash];T0;$@+;![ ;"I"Counts all objects grouped by type.
It returns a hash, such as:
{
:TOTAL=>10000,
:FREE=>3011,
:T_OBJECT=>6,
:T_CLASS=>404,
# ...
}
The contents of the returned hash are implementation specific.
It may be changed in future.
The keys starting with +:T_+ means live objects.
For example, +:T_ARRAY+ is the number of arrays.
+:FREE+ means object slots which is not used now.
+:TOTAL+ means sum of above.
If the optional argument +result_hash+ is given,
it is overwritten and returned. This is intended to avoid probe effect.
h = {}
ObjectSpace.count_objects(h)
puts h
# => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }
This method is only expected to work on C Ruby.
@overload count_objects([result_hash])
@return [Hash];T;#0;$@+;.F;/o;0;1T;2iH;3ih;Bi ;%@&;9@+;:@+;;To; ;IC;[o;4;5F;6;;; ;&I" ObjectSpace::WeakMap#[]=;F;7[ ;[ ;F;;8;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@+;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#[];F;7[ ;[ ;F;;;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@+;%@+;;To;4;5F;6;;; ;&I""ObjectSpace::WeakMap#include?;F;7[ ;[ ;F;:
include?;;; [ ; { ; IC; " ;T; [o;A
;>I" return;F;?@;0;@[@L;$@,;![ ;"@;#0;$@,;Bi ;%@+;;To;4;5F;6;;; ;&I"!ObjectSpace::WeakMap#member?;F;7[ ;[ ;F;: member?;;; [ ; { ; IC; " ;T; [o;A
;>I" return;F;?@;0;@[@L;$@,;![ ;"@;#0;$@,;Bi ;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#key?;F;7[ ;[ ;F;;:;;; [ ; { ; IC; " ;T; [o;A
;>I" return;F;?@;0;@[@L;$@,;![ ;"@;#0;$@,;Bi ;%@+;;To;4;5F;6;;; ;&I"!ObjectSpace::WeakMap#inspect;F;7[ ;[ ;F;;J;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@&,;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#each;F;7[ ;[ ;F;: each;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@/,;%@+;;To;4;5F;6;;; ;&I"#ObjectSpace::WeakMap#each_pair;F;7[ ;[ ;F;:each_pair;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@8,;%@+;;To;4;5F;6;;; ;&I""ObjectSpace::WeakMap#each_key;F;7[ ;[ ;F;:
each_key;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@A,;%@+;;To;4;5F;6;;; ;&I"$ObjectSpace::WeakMap#each_value;F;7[ ;[ ;F;:each_value;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@J,;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#keys;F;7[ ;[ ;F;;;;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@S,;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#values;F;7[ ;[ ;F;: values;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\,;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#size;F;7[ ;[ ;F;;;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@e,;%@+;;To;4;5F;6;;; ;&I" ObjectSpace::WeakMap#length;F;7[ ;[ ;F;;b;;; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@n,;%@+;;T;
@+; IC;[ ;
@+; IC;[o;;IC;[Ao;4;5F;6;;; ;&I"Enumerable#chain;F;7[[@90;[[@i ;T;:
chain;0; [ ; { ; IC; "Returns an enumerator object generated from this enumerator and
given enumerables.
e = (1..3).chain([4, 5])
e.to_a #=> [1, 2, 3, 4, 5]
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"chain(*enums);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@{,;.F;Bi ;C0;7[[I" *enums;T0;$@{,;![ ;"I"Returns an enumerator object generated from this enumerator and
given enumerables.
e = (1..3).chain([4, 5])
e.to_a #=> [1, 2, 3, 4, 5]
@overload chain(*enums);T;#0;$@{,;.F;/o;0;1T;2i ;3i ;%@y,;9I"static VALUE
enum_chain(int argc, VALUE *argv, VALUE obj)
{
VALUE enums = rb_ary_new_from_values(1, &obj);
rb_ary_cat(enums, argv, argc);
return new_enum_chain(enums);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Enumerable#lazy;F;7[ ;[[@id;T;: lazy;0; [ ; { ; IC; "Returns an Enumerator::Lazy, which redefines most Enumerable
methods to postpone enumeration and enumerate values only on an
as-needed basis.
=== Example
The following program finds pythagorean triples:
def pythagorean_triples
(1..Float::INFINITY).lazy.flat_map {|z|
(1..z).flat_map {|x|
(x..z).select {|y|
x**2 + y**2 == z**2
}.map {|y|
[x, y, z]
}
}
}
end
# show first ten pythagorean triples
p pythagorean_triples.take(10).force # take is lazy, so force is needed
p pythagorean_triples.first(10) # first is eager
# show pythagorean triples less than 100
p pythagorean_triples.take_while { |*, z| z < 100 }.force
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" lazy;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@,;.F;Bi ;C0;7[ ;$@,;![ ;"I"Returns an Enumerator::Lazy, which redefines most Enumerable
methods to postpone enumeration and enumerate values only on an
as-needed basis.
=== Example
The following program finds pythagorean triples:
def pythagorean_triples
(1..Float::INFINITY).lazy.flat_map {|z|
(1..z).flat_map {|x|
(x..z).select {|y|
x**2 + y**2 == z**2
}.map {|y|
[x, y, z]
}
}
}
end
# show first ten pythagorean triples
p pythagorean_triples.take(10).force # take is lazy, so force is needed
p pythagorean_triples.first(10) # first is eager
# show pythagorean triples less than 100
p pythagorean_triples.take_while { |*, z| z < 100 }.force
@overload lazy;T;#0;$@,;.F;/o;0;1T;2iG;3ia;%@y,;9I"static VALUE
enumerable_lazy(VALUE obj)
{
VALUE result = lazy_to_enum_i(obj, sym_each, 0, 0, lazyenum_size, rb_keyword_given_p());
/* Qfalse indicates that the Enumerator::Lazy has no method name */
rb_ivar_set(result, id_method, Qfalse);
return result;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Enumerable#to_a;F;7[[@90;[[I" enum.c;Ti;T;: to_a;0; [ ; { ; IC; "Returns an array containing the items in +self+:
(0..4).to_a # => [0, 1, 2, 3, 4]
Enumerable#entries is an alias for Enumerable#to_a.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" to_a;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@,;![ ;"I"@return [Array];T;#0;$@,;.F;Bi ;C0;7[ ;$@,;![ ;"I"Returns an array containing the items in +self+:
(0..4).to_a # => [0, 1, 2, 3, 4]
Enumerable#entries is an alias for Enumerable#to_a.
@overload to_a
@return [Array];T;#0;$@,;.F;/o;0;1T;2i;3i;%@y,;9I"static VALUE
enum_to_a(int argc, VALUE *argv, VALUE obj)
{
VALUE ary = rb_ary_new();
rb_block_call_kw(obj, id_each, argc, argv, collect_all, ary, RB_PASS_CALLED_KEYWORDS);
return ary;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Enumerable#entries;F;7[[@90;[[@,i;T;: entries;0; [ ; { ; IC; "Returns an array containing the items in +self+:
(0..4).to_a # => [0, 1, 2, 3, 4]
Enumerable#entries is an alias for Enumerable#to_a.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" to_a;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@,;![ ;"I"@return [Array];T;#0;$@,;.F;Bi ;C0;7[ ;$@,;![ ;"@,;#0;$@,;.F;/o;0;1T;2i;3i;%@y,;9I"static VALUE
enum_to_a(int argc, VALUE *argv, VALUE obj)
{
VALUE ary = rb_ary_new();
rb_block_call_kw(obj, id_each, argc, argv, collect_all, ary, RB_PASS_CALLED_KEYWORDS);
return ary;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Enumerable#to_h;F;7[[@90;[[@,i ;T;: to_h;0; [ ; { ; IC; "When +self+ consists of 2-element arrays,
returns a hash each of whose entries is the key-value pair
formed from one of those arrays:
[[:foo, 0], [:bar, 1], [:baz, 2]].to_h # => {:foo=>0, :bar=>1, :baz=>2}
When a block is given, the block is called with each element of +self+;
the block should return a 2-element array which becomes a key-value pair
in the returned hash:
(0..3).to_h {|i| [i, i ** 2]} # => {0=>0, 1=>1, 2=>4, 3=>9}
Raises an exception if an element of +self+ is not a 2-element array,
and a block is not passed.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" to_h;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Hash;T;$@,;![ ;"I"@return [Hash];T;#0;$@,;.F;Bi ;C0;7[ ;$@,o;=
;>I"
overload;F;?0;;;@0;:I" to_h;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" element;T;$@,o;A
;>I" return;F;?I" ;T;0;@[I" Hash;T;$@,;![ ;"I"$@yield [element]
@return [Hash];T;#0;$@,;.F;Bi ;C0;7[ ;$@,;![ ;"I"nWhen +self+ consists of 2-element arrays,
returns a hash each of whose entries is the key-value pair
formed from one of those arrays:
[[:foo, 0], [:bar, 1], [:baz, 2]].to_h # => {:foo=>0, :bar=>1, :baz=>2}
When a block is given, the block is called with each element of +self+;
the block should return a 2-element array which becomes a key-value pair
in the returned hash:
(0..3).to_h {|i| [i, i ** 2]} # => {0=>0, 1=>1, 2=>4, 3=>9}
Raises an exception if an element of +self+ is not a 2-element array,
and a block is not passed.
@overload to_h
@return [Hash]
@overload to_h
@yield [element]
@return [Hash];T;#0;$@,;.F;/o;0;1T;2i;3i;%@y,;9I"static VALUE
enum_to_h(int argc, VALUE *argv, VALUE obj)
{
rb_block_call_func *iter = rb_block_given_p() ? enum_to_h_ii : enum_to_h_i;
return enum_hashify(obj, argc, argv, iter);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Enumerable#sort;F;7[ ;[[@,i,;T;: sort;0; [ ; { ; IC; "Returns an array containing the sorted elements of +self+.
The ordering of equal elements is indeterminate and may be unstable.
With no block given, the sort compares
using the elements' own method <=>:
%w[b c a d].sort # => ["a", "b", "c", "d"]
{foo: 0, bar: 1, baz: 2}.sort # => [[:bar, 1], [:baz, 2], [:foo, 0]]
With a block given, comparisons in the block determine the ordering.
The block is called with two elements +a+ and +b+, and must return:
- A negative integer if a < b.
- Zero if a == b.
- A positive integer if a > b.
Examples:
a = %w[b c a d]
a.sort {|a, b| b <=> a } # => ["d", "c", "b", "a"]
h = {foo: 0, bar: 1, baz: 2}
h.sort {|a, b| b <=> a } # => [[:foo, 0], [:baz, 2], [:bar, 1]]
See also #sort_by. It implements a Schwartzian transform
which is useful when key computation or comparison is expensive.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" sort;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@-;![ ;"I"@return [Array];T;#0;$@-;.F;Bi ;C0;7[ ;$@-o;=
;>I"
overload;F;?0;;;@0;:I" sort;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"a;TI"b;T;$@-o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@-;![ ;"I""@yield [a, b]
@return [Array];T;#0;$@-;.F;Bi ;C0;7[ ;$@-;![ ;"I"Returns an array containing the sorted elements of +self+.
The ordering of equal elements is indeterminate and may be unstable.
With no block given, the sort compares
using the elements' own method <=>:
%w[b c a d].sort # => ["a", "b", "c", "d"]
{foo: 0, bar: 1, baz: 2}.sort # => [[:bar, 1], [:baz, 2], [:foo, 0]]
With a block given, comparisons in the block determine the ordering.
The block is called with two elements +a+ and +b+, and must return:
- A negative integer if a < b.
- Zero if a == b.
- A positive integer if a > b.
Examples:
a = %w[b c a d]
a.sort {|a, b| b <=> a } # => ["d", "c", "b", "a"]
h = {foo: 0, bar: 1, baz: 2}
h.sort {|a, b| b <=> a } # => [[:foo, 0], [:baz, 2], [:bar, 1]]
See also #sort_by. It implements a Schwartzian transform
which is useful when key computation or comparison is expensive.
@overload sort
@return [Array]
@overload sort
@yield [a, b]
@return [Array];T;#0;$@-;.F;/o;0;1T;2i ;3i+;%@y,;9I"]static VALUE
enum_sort(VALUE obj)
{
return rb_ary_sort_bang(enum_to_a(0, 0, obj));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Enumerable#sort_by;F;7[ ;[[@,i;T;: sort_by;0; [ ; { ; IC; "(
With a block given, returns an array of elements of +self+,
sorted according to the value returned by the block for each element.
The ordering of equal elements is indeterminate and may be unstable.
Examples:
a = %w[xx xxx x xxxx]
a.sort_by {|s| s.size } # => ["x", "xx", "xxx", "xxxx"]
a.sort_by {|s| -s.size } # => ["xxxx", "xxx", "xx", "x"]
h = {foo: 2, bar: 1, baz: 0}
h.sort_by{|key, value| value } # => [[:baz, 0], [:bar, 1], [:foo, 2]]
h.sort_by{|key, value| key } # => [[:bar, 1], [:baz, 0], [:foo, 2]]
With no block given, returns an Enumerator.
The current implementation of #sort_by generates an array of
tuples containing the original collection element and the mapped
value. This makes #sort_by fairly expensive when the keysets are
simple.
require 'benchmark'
a = (1..100000).map { rand(100000) }
Benchmark.bm(10) do |b|
b.report("Sort") { a.sort }
b.report("Sort by") { a.sort_by { |a| a } }
end
produces:
user system total real
Sort 0.180000 0.000000 0.180000 ( 0.175469)
Sort by 1.980000 0.040000 2.020000 ( 2.013586)
However, consider the case where comparing the keys is a non-trivial
operation. The following code sorts some files on modification time
using the basic #sort method.
files = Dir["*"]
sorted = files.sort { |a, b| File.new(a).mtime <=> File.new(b).mtime }
sorted #=> ["mon", "tues", "wed", "thurs"]
This sort is inefficient: it generates two new File
objects during every comparison. A slightly better technique is to
use the Kernel#test method to generate the modification
times directly.
files = Dir["*"]
sorted = files.sort { |a, b|
test(?M, a) <=> test(?M, b)
}
sorted #=> ["mon", "tues", "wed", "thurs"]
This still generates many unnecessary Time objects. A more
efficient technique is to cache the sort keys (modification times
in this case) before the sort. Perl users often call this approach
a Schwartzian transform, after Randal Schwartz. We construct a
temporary array, where each element is an array containing our
sort key along with the filename. We sort this array, and then
extract the filename from the result.
sorted = Dir["*"].collect { |f|
[test(?M, f), f]
}.sort.collect { |f| f[1] }
sorted #=> ["mon", "tues", "wed", "thurs"]
This is exactly what #sort_by does internally.
sorted = Dir["*"].sort_by { |f| test(?M, f) }
sorted #=> ["mon", "tues", "wed", "thurs"]
To produce the reverse of a specific order, the following can be used:
ary.sort_by { ... }.reverse!
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" sort_by;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" element;T;$@>-o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@>-;![ ;"I"%@yield [element]
@return [Array];T;#0;$@>-;.F;Bi ;C0;7[ ;$@>-o;=
;>I"
overload;F;?0;;;@0;:I" sort_by;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@>-;.F;Bi ;C0;7[ ;$@>-;![ ;"I"s
With a block given, returns an array of elements of +self+,
sorted according to the value returned by the block for each element.
The ordering of equal elements is indeterminate and may be unstable.
Examples:
a = %w[xx xxx x xxxx]
a.sort_by {|s| s.size } # => ["x", "xx", "xxx", "xxxx"]
a.sort_by {|s| -s.size } # => ["xxxx", "xxx", "xx", "x"]
h = {foo: 2, bar: 1, baz: 0}
h.sort_by{|key, value| value } # => [[:baz, 0], [:bar, 1], [:foo, 2]]
h.sort_by{|key, value| key } # => [[:bar, 1], [:baz, 0], [:foo, 2]]
With no block given, returns an Enumerator.
The current implementation of #sort_by generates an array of
tuples containing the original collection element and the mapped
value. This makes #sort_by fairly expensive when the keysets are
simple.
require 'benchmark'
a = (1..100000).map { rand(100000) }
Benchmark.bm(10) do |b|
b.report("Sort") { a.sort }
b.report("Sort by") { a.sort_by { |a| a } }
end
produces:
user system total real
Sort 0.180000 0.000000 0.180000 ( 0.175469)
Sort by 1.980000 0.040000 2.020000 ( 2.013586)
However, consider the case where comparing the keys is a non-trivial
operation. The following code sorts some files on modification time
using the basic #sort method.
files = Dir["*"]
sorted = files.sort { |a, b| File.new(a).mtime <=> File.new(b).mtime }
sorted #=> ["mon", "tues", "wed", "thurs"]
This sort is inefficient: it generates two new File
objects during every comparison. A slightly better technique is to
use the Kernel#test method to generate the modification
times directly.
files = Dir["*"]
sorted = files.sort { |a, b|
test(?M, a) <=> test(?M, b)
}
sorted #=> ["mon", "tues", "wed", "thurs"]
This still generates many unnecessary Time objects. A more
efficient technique is to cache the sort keys (modification times
in this case) before the sort. Perl users often call this approach
a Schwartzian transform, after Randal Schwartz. We construct a
temporary array, where each element is an array containing our
sort key along with the filename. We sort this array, and then
extract the filename from the result.
sorted = Dir["*"].collect { |f|
[test(?M, f), f]
}.sort.collect { |f| f[1] }
sorted #=> ["mon", "tues", "wed", "thurs"]
This is exactly what #sort_by does internally.
sorted = Dir["*"].sort_by { |f| test(?M, f) }
sorted #=> ["mon", "tues", "wed", "thurs"]
To produce the reverse of a specific order, the following can be used:
ary.sort_by { ... }.reverse!
@overload sort_by
@yield [element]
@return [Array]
@overload sort_by;T;#0;$@>-;.F;/o;0;1T;2ig;3i;%@y,;9I"static VALUE
enum_sort_by(VALUE obj)
{
VALUE ary, buf;
struct MEMO *memo;
long i;
struct sort_by_data *data;
RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);
if (RB_TYPE_P(obj, T_ARRAY) && RARRAY_LEN(obj) <= LONG_MAX/2) {
ary = rb_ary_new2(RARRAY_LEN(obj)*2);
}
else {
ary = rb_ary_new();
}
RBASIC_CLEAR_CLASS(ary);
buf = rb_ary_tmp_new(SORT_BY_BUFSIZE*2);
rb_ary_store(buf, SORT_BY_BUFSIZE*2-1, Qnil);
memo = MEMO_NEW(0, 0, 0);
data = (struct sort_by_data *)&memo->v1;
RB_OBJ_WRITE(memo, &data->ary, ary);
RB_OBJ_WRITE(memo, &data->buf, buf);
data->n = 0;
rb_block_call(obj, id_each, 0, 0, sort_by_i, (VALUE)memo);
ary = data->ary;
buf = data->buf;
if (data->n) {
rb_ary_resize(buf, data->n*2);
rb_ary_concat(ary, buf);
}
if (RARRAY_LEN(ary) > 2) {
RARRAY_PTR_USE(ary, ptr,
ruby_qsort(ptr, RARRAY_LEN(ary)/2, 2*sizeof(VALUE),
sort_by_cmp, (void *)ary));
}
if (RBASIC(ary)->klass) {
rb_raise(rb_eRuntimeError, "sort_by reentered");
}
for (i=1; iObjectSpace.define_finalizer for important information on
how to use this method correctly.
a = "A"
b = "B"
ObjectSpace.define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
ObjectSpace.define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })
a = nil
b = nil
_produces:_
Finalizer two on 537763470
Finalizer one on 537763480;T; [ ;![ ;"I"
The ObjectSpace module contains a number of routines
that interact with the garbage collection facility and allow you to
traverse all living objects with an iterator.
ObjectSpace also provides support for object finalizers, procs that will be
called when a specific object is about to be destroyed by garbage
collection. See the documentation for
ObjectSpace.define_finalizer for important information on
how to use this method correctly.
a = "A"
b = "B"
ObjectSpace.define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
ObjectSpace.define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })
a = nil
b = nil
_produces:_
Finalizer two on 537763470
Finalizer one on 537763480
;T;#0;$@&;.F;/o;0;1T;2i4;3i4;Bi ;%@;&I"ObjectSpace;F@ho; ;IC;[Uo;4;5F;6;;; ;&I"Module#include;F;7[[@90;[[@Oib;T;: include;0; [ ; { ; IC; "GInvokes Module.append_features on each parameter in reverse order.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"include(module, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@C7;![ ;"I"@return [self];T;#0;$@C7;.F;Bi ;C0;7[ ;$@C7;![ ;"I"yInvokes Module.append_features on each parameter in reverse order.
@overload include(module, ...)
@return [self];T;#0;$@C7;.F;/o;0;1T;2i[;3i_;%@A7;9I"`static VALUE
rb_mod_include(int argc, VALUE *argv, VALUE module)
{
int i;
ID id_append_features, id_included;
CONST_ID(id_append_features, "append_features");
CONST_ID(id_included, "included");
if (FL_TEST(module, RMODULE_IS_REFINEMENT)) {
rb_warn_deprecated_to_remove_at(3.2, "Refinement#include", NULL);
}
rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
for (i = 0; i < argc; i++)
Check_Type(argv[i], T_MODULE);
while (argc--) {
rb_funcall(argv[argc], id_append_features, 1, module);
rb_funcall(argv[argc], id_included, 1, module);
}
return module;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#prepend;F;7[[@90;[[@Oi;T;: prepend;0; [ ; { ; IC; "HInvokes Module.prepend_features on each parameter in reverse order.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"prepend(module, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@_7;![ ;"I"@return [self];T;#0;$@_7;.F;Bi ;C0;7[ ;$@_7;![ ;"I"zInvokes Module.prepend_features on each parameter in reverse order.
@overload prepend(module, ...)
@return [self];T;#0;$@_7;.F;/o;0;1T;2i;3i;%@A7;9I"hstatic VALUE
rb_mod_prepend(int argc, VALUE *argv, VALUE module)
{
int i;
ID id_prepend_features, id_prepended;
if (FL_TEST(module, RMODULE_IS_REFINEMENT)) {
rb_warn_deprecated_to_remove_at(3.2, "Refinement#prepend", NULL);
}
CONST_ID(id_prepend_features, "prepend_features");
CONST_ID(id_prepended, "prepended");
rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
for (i = 0; i < argc; i++)
Check_Type(argv[i], T_MODULE);
while (argc--) {
rb_funcall(argv[argc], id_prepend_features, 1, module);
rb_funcall(argv[argc], id_prepended, 1, module);
}
return module;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#append_features;F;7[[I" include;T0;[[@OiP;T;:append_features;0; [ ; { ; IC; "PWhen this module is included in another, Ruby calls
#append_features in this module, passing it the receiving module
in _mod_. Ruby's default implementation is to add the constants,
methods, and module variables of this module to _mod_ if this
module has not already been added to _mod_ or one of its
ancestors. See also Module#include.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"append_features(mod);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@{7;.F;Bi ;C0;7[[I"mod;T0;$@{7;![ ;"I"qWhen this module is included in another, Ruby calls
#append_features in this module, passing it the receiving module
in _mod_. Ruby's default implementation is to add the constants,
methods, and module variables of this module to _mod_ if this
module has not already been added to _mod_ or one of its
ancestors. See also Module#include.
@overload append_features(mod);T;#0;$@{7;.F;/o;0;1T;2iD;3iL;%@A7;9I"static VALUE
rb_mod_append_features(VALUE module, VALUE include)
{
if (!CLASS_OR_MODULE_P(include)) {
Check_Type(include, T_CLASS);
}
rb_include_module(include, module);
return module;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#extend_object;F;7[[I"obj;T0;[[@OiK;T;:extend_object;0; [ ; { ; IC; "#Extends the specified object by adding this module's constants and
methods (which are added as singleton methods). This is the callback
method used by Object#extend.
module Picky
def Picky.extend_object(o)
if String === o
puts "Can't add Picky to a String"
else
puts "Picky added to #{o.class}"
super
end
end
end
(s = Array.new).extend Picky # Call Object.extend
(s = "quick brown fox").extend Picky
produces:
Picky added to Array
Can't add Picky to a String
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"extend_object(obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@7;![ ;"I"@return [Object];T;#0;$@7;.F;Bi ;C0;7[[I"obj;T0;$@7;![ ;"I"UExtends the specified object by adding this module's constants and
methods (which are added as singleton methods). This is the callback
method used by Object#extend.
module Picky
def Picky.extend_object(o)
if String === o
puts "Can't add Picky to a String"
else
puts "Picky added to #{o.class}"
super
end
end
end
(s = Array.new).extend Picky # Call Object.extend
(s = "quick brown fox").extend Picky
produces:
Picky added to Array
Can't add Picky to a String
@overload extend_object(obj)
@return [Object];T;#0;$@7;.F;/o;0;1T;2i0;3iH;%@A7;9I"pstatic VALUE
rb_mod_extend_object(VALUE mod, VALUE obj)
{
rb_extend_object(obj, mod);
return obj;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I" Module#prepend_features;F;7[[I" prepend;T0;[[@Oi;T;:prepend_features;0; [ ; { ; IC; "VWhen this module is prepended in another, Ruby calls
#prepend_features in this module, passing it the receiving module
in _mod_. Ruby's default implementation is to overlay the
constants, methods, and module variables of this module to _mod_
if this module has not already been added to _mod_ or one of its
ancestors. See also Module#prepend.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"prepend_features(mod);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@7;.F;Bi ;C0;7[[I"mod;T0;$@7;![ ;"I"xWhen this module is prepended in another, Ruby calls
#prepend_features in this module, passing it the receiving module
in _mod_. Ruby's default implementation is to overlay the
constants, methods, and module variables of this module to _mod_
if this module has not already been added to _mod_ or one of its
ancestors. See also Module#prepend.
@overload prepend_features(mod);T;#0;$@7;.F;/o;0;1T;2iy;3i;%@A7;9I"static VALUE
rb_mod_prepend_features(VALUE module, VALUE prepend)
{
if (!CLASS_OR_MODULE_P(prepend)) {
Check_Type(prepend, T_CLASS);
}
rb_prepend_module(prepend, module);
return module;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#refine;F;7[[I"
klass;T0;[[@Oi^;T;: refine;0; [ ; { ; IC; "]Refine mod in the receiver.
Returns a module, where refined methods are defined.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"refine(mod);T; IC; " ;T; [o;A
;>I"
yield;F;?I"[];T;0;@0;$@7;![ ;"I"@yield [];T;#0;$@7;.F;Bi ;C0;7[[I"mod;T0;$@7;![ ;"I"|Refine mod in the receiver.
Returns a module, where refined methods are defined.
@overload refine(mod)
@yield [];T;#0;$@7;.F;/o;0;1T;2iU;3i[;%@A7;9I"static VALUE
rb_mod_refine(VALUE module, VALUE klass)
{
VALUE refinement;
ID id_refinements, id_activated_refinements,
id_refined_class, id_defined_at;
VALUE refinements, activated_refinements;
rb_thread_t *th = GET_THREAD();
VALUE block_handler = rb_vm_frame_block_handler(th->ec->cfp);
if (block_handler == VM_BLOCK_HANDLER_NONE) {
rb_raise(rb_eArgError, "no block given");
}
if (vm_block_handler_type(block_handler) != block_handler_type_iseq) {
rb_raise(rb_eArgError, "can't pass a Proc as a block to Module#refine");
}
ensure_class_or_module(klass);
CONST_ID(id_refinements, "__refinements__");
refinements = rb_attr_get(module, id_refinements);
if (NIL_P(refinements)) {
refinements = hidden_identity_hash_new();
rb_ivar_set(module, id_refinements, refinements);
}
CONST_ID(id_activated_refinements, "__activated_refinements__");
activated_refinements = rb_attr_get(module, id_activated_refinements);
if (NIL_P(activated_refinements)) {
activated_refinements = hidden_identity_hash_new();
rb_ivar_set(module, id_activated_refinements,
activated_refinements);
}
refinement = rb_hash_lookup(refinements, klass);
if (NIL_P(refinement)) {
VALUE superclass = refinement_superclass(klass);
refinement = rb_refinement_new();
RCLASS_SET_SUPER(refinement, superclass);
FL_SET(refinement, RMODULE_IS_REFINEMENT);
CONST_ID(id_refined_class, "__refined_class__");
rb_ivar_set(refinement, id_refined_class, klass);
CONST_ID(id_defined_at, "__defined_at__");
rb_ivar_set(refinement, id_defined_at, module);
rb_hash_aset(refinements, klass, refinement);
add_activated_refinement(activated_refinements, klass, refinement);
}
rb_yield_refine_block(refinement, activated_refinements);
return refinement;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#using;F;7[[I" module;T0;[[@Oi;T;:
using;0; [ ; { ; IC; "]Import class refinements from module into the current class or
module definition.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"using(module);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@7;![ ;"I"@return [self];T;#0;$@7;.F;Bi ;C0;7[ ;$@7;![ ;"I"Import class refinements from module into the current class or
module definition.
@overload using(module)
@return [self];T;#0;$@7;.F;/o;0;1T;2i;3i;%@A7;9I"static VALUE
mod_using(VALUE self, VALUE module)
{
rb_control_frame_t *prev_cfp = previous_frame(GET_EC());
if (prev_frame_func()) {
rb_raise(rb_eRuntimeError,
"Module#using is not permitted in methods");
}
if (prev_cfp && prev_cfp->self != self) {
rb_raise(rb_eRuntimeError, "Module#using is not called on self");
}
if (rb_block_given_p()) {
ignored_block(module, "Module#");
}
rb_using_module(rb_vm_cref_replace_with_duplicated_cref(), module);
return self;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module.used_modules;F;7[ ;[[@Oi;T;:used_modules;0; [ ; { ; IC; ".Returns an array of all modules used in the current scope. The ordering
of modules in the resulting array is not defined.
module A
refine Object do
end
end
module B
refine Object do
end
end
using A
using B
p Module.used_modules
produces:
[B, A]
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"used_modules;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@8;![ ;"I"@return [Array];T;#0;$@8;.F;Bi ;C0;7[ ;$@8;![ ;"I"YReturns an array of all modules used in the current scope. The ordering
of modules in the resulting array is not defined.
module A
refine Object do
end
end
module B
refine Object do
end
end
using A
using B
p Module.used_modules
produces:
[B, A]
@overload used_modules
@return [Array];T;#0;$@8;.F;/o;0;1T;2i;3i;%@A7;9I"Jstatic VALUE
rb_mod_s_used_modules(VALUE _)
{
const rb_cref_t *cref = rb_vm_cref();
VALUE ary = rb_ary_new();
while (cref) {
if (!NIL_P(CREF_REFINEMENTS(cref))) {
rb_hash_foreach(CREF_REFINEMENTS(cref), used_modules_i, ary);
}
cref = CREF_NEXT(cref);
}
return rb_funcall(ary, rb_intern("uniq"), 0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#remove_method;F;7[[@90;[[@i;T;:remove_method;0; [ ; { ; IC; "Removes the method identified by _symbol_ from the current
class. For an example, see Module#undef_method.
String arguments are converted to symbols.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"remove_method(symbol);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@#8;![ ;"I"@return [self];T;#0;$@#8;.F;Bi ;C0;7[[I" symbol;T0;$@#8o;=
;>I"
overload;F;?0;;;@0;:I"remove_method(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@#8;![ ;"I"@return [self];T;#0;$@#8;.F;Bi ;C0;7[[I" string;T0;$@#8;![ ;"I"Removes the method identified by _symbol_ from the current
class. For an example, see Module#undef_method.
String arguments are converted to symbols.
@overload remove_method(symbol)
@return [self]
@overload remove_method(string)
@return [self];T;#0;$@#8;.F;/o;0;1T;2i;3i;%@A7;9I".static VALUE
rb_mod_remove_method(int argc, VALUE *argv, VALUE mod)
{
int i;
for (i = 0; i < argc; i++) {
VALUE v = argv[i];
ID id = rb_check_id(&v);
if (!id) {
rb_name_err_raise("method `%1$s' not defined in %2$s",
mod, v);
}
remove_method(mod, id);
}
return mod;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#undef_method;F;7[[@90;[[@i;T;:undef_method;0; [ ; { ; IC; "Prevents the current class from responding to calls to the named
method. Contrast this with remove_method, which deletes
the method from the particular class; Ruby will still search
superclasses and mixed-in modules for a possible receiver.
String arguments are converted to symbols.
class Parent
def hello
puts "In parent"
end
end
class Child < Parent
def hello
puts "In child"
end
end
c = Child.new
c.hello
class Child
remove_method :hello # remove from child, still in parent
end
c.hello
class Child
undef_method :hello # prevent any calls to 'hello'
end
c.hello
produces:
In child
In parent
prog.rb:23: undefined method `hello' for #remove_method, which deletes
the method from the particular class; Ruby will still search
superclasses and mixed-in modules for a possible receiver.
String arguments are converted to symbols.
class Parent
def hello
puts "In parent"
end
end
class Child < Parent
def hello
puts "In child"
end
end
c = Child.new
c.hello
class Child
remove_method :hello # remove from child, still in parent
end
c.hello
class Child
undef_method :hello # prevent any calls to 'hello'
end
c.hello
produces:
In child
In parent
prog.rb:23: undefined method `hello' for #self of the context is the same as the method.
(method definition or instance_eval). This behavior is different from
Java's protected method. Usually private should be used.
Note that a protected method is slow because it can't use inline cache.
To show a private method on RDoc, use :doc: instead of this.
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I"protected;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@8;![ ;"I"@return [nil];T;#0;$@8;.F;Bi ;C0;7[ ;$@8o;=
;>I"
overload;F;?0;;;@0;:I"protected(method_name);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@8;.F;Bi ;C0;7[[I"method_name;T0;$@8o;=
;>I"
overload;F;?0;;;@0;:I"-protected(method_name, method_name, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@8;![ ;"I"@return [Array];T;#0;$@8;.F;Bi ;C0;7[[I"method_name;T0[I"method_name;T0[I"...;T0;$@8o;=
;>I"
overload;F;?0;;;@0;:I"protected(array);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@8;![ ;"I"@return [Array];T;#0;$@8;.F;Bi ;C0;7[[I"
array;T0;$@8;![ ;"I"With no arguments, sets the default visibility for subsequently
defined methods to protected. With arguments, sets the named methods
to have protected visibility.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
If a single argument is passed, it is returned.
If no argument is passed, nil is returned.
If multiple arguments are passed, the arguments are returned as an array.
If a method has protected visibility, it is callable only where
self of the context is the same as the method.
(method definition or instance_eval). This behavior is different from
Java's protected method. Usually private should be used.
Note that a protected method is slow because it can't use inline cache.
To show a private method on RDoc, use :doc: instead of this.
@overload protected
@return [nil]
@overload protected(method_name)
@overload protected(method_name, method_name, ...)
@return [Array]
@overload protected(array)
@return [Array];T;#0;$@8;.F;/o;0;1T;2i;3i;%@A7;9I"static VALUE
rb_mod_protected(int argc, VALUE *argv, VALUE module)
{
return set_visibility(argc, argv, module, METHOD_VISI_PROTECTED);
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#private;F;7[[@90;[[@i ;T;;;0; [ ; { ; IC; "With no arguments, sets the default visibility for subsequently
defined methods to private. With arguments, sets the named methods
to have private visibility.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
If a single argument is passed, it is returned.
If no argument is passed, nil is returned.
If multiple arguments are passed, the arguments are returned as an array.
module Mod
def a() end
def b() end
private
def c() end
private :a
end
Mod.private_instance_methods #=> [:a, :c]
Note that to show a private method on RDoc, use :doc:.
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I" private;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@+9;![ ;"I"@return [nil];T;#0;$@+9;.F;Bi ;C0;7[ ;$@+9o;=
;>I"
overload;F;?0;;;@0;:I"private(method_name);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@+9;.F;Bi ;C0;7[[I"method_name;T0;$@+9o;=
;>I"
overload;F;?0;;;@0;:I"+private(method_name, method_name, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@+9;![ ;"I"@return [Array];T;#0;$@+9;.F;Bi ;C0;7[[I"method_name;T0[I"method_name;T0[I"...;T0;$@+9o;=
;>I"
overload;F;?0;;;@0;:I"private(array);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@+9;![ ;"I"@return [Array];T;#0;$@+9;.F;Bi ;C0;7[[I"
array;T0;$@+9;![ ;"I"1With no arguments, sets the default visibility for subsequently
defined methods to private. With arguments, sets the named methods
to have private visibility.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
If a single argument is passed, it is returned.
If no argument is passed, nil is returned.
If multiple arguments are passed, the arguments are returned as an array.
module Mod
def a() end
def b() end
private
def c() end
private :a
end
Mod.private_instance_methods #=> [:a, :c]
Note that to show a private method on RDoc, use :doc:.
@overload private
@return [nil]
@overload private(method_name)
@overload private(method_name, method_name, ...)
@return [Array]
@overload private(array)
@return [Array];T;#0;$@+9;.F;/o;0;1T;2i;3i ;%@A7;9I"static VALUE
rb_mod_private(int argc, VALUE *argv, VALUE module)
{
return set_visibility(argc, argv, module, METHOD_VISI_PRIVATE);
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#module_function;F;7[[@90;[[@i
;T;:module_function;0; [ ; { ; IC; "Creates module functions for the named methods. These functions may
be called with the module as a receiver, and also become available
as instance methods to classes that mix in the module. Module
functions are copies of the original, and so may be changed
independently. The instance-method versions are made private. If
used with no arguments, subsequently defined methods become module
functions.
String arguments are converted to symbols.
If a single argument is passed, it is returned.
If no argument is passed, nil is returned.
If multiple arguments are passed, the arguments are returned as an array.
module Mod
def one
"This is one"
end
module_function :one
end
class Cls
include Mod
def call_one
one
end
end
Mod.one #=> "This is one"
c = Cls.new
c.call_one #=> "This is one"
module Mod
def one
"This is the new one"
end
end
Mod.one #=> "This is one"
c.call_one #=> "This is the new one"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"module_function;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@s9;![ ;"I"@return [nil];T;#0;$@s9;.F;Bi ;C0;7[ ;$@s9o;=
;>I"
overload;F;?0;;;@0;:I"!module_function(method_name);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@s9;.F;Bi ;C0;7[[I"method_name;T0;$@s9o;=
;>I"
overload;F;?0;;;@0;:I"3module_function(method_name, method_name, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@s9;![ ;"I"@return [Array];T;#0;$@s9;.F;Bi ;C0;7[[I"method_name;T0[I"method_name;T0[I"...;T0;$@s9;![ ;"I"Creates module functions for the named methods. These functions may
be called with the module as a receiver, and also become available
as instance methods to classes that mix in the module. Module
functions are copies of the original, and so may be changed
independently. The instance-method versions are made private. If
used with no arguments, subsequently defined methods become module
functions.
String arguments are converted to symbols.
If a single argument is passed, it is returned.
If no argument is passed, nil is returned.
If multiple arguments are passed, the arguments are returned as an array.
module Mod
def one
"This is one"
end
module_function :one
end
class Cls
include Mod
def call_one
one
end
end
Mod.one #=> "This is one"
c = Cls.new
c.call_one #=> "This is one"
module Mod
def one
"This is the new one"
end
end
Mod.one #=> "This is one"
c.call_one #=> "This is the new one"
@overload module_function
@return [nil]
@overload module_function(method_name)
@overload module_function(method_name, method_name, ...)
@return [Array];T;#0;$@s9;.F;/o;0;1T;2i ;3i
;%@A7;9I"static VALUE
rb_mod_modfunc(int argc, VALUE *argv, VALUE module)
{
int i;
ID id;
const rb_method_entry_t *me;
if (!RB_TYPE_P(module, T_MODULE)) {
rb_raise(rb_eTypeError, "module_function must be called for modules");
}
if (argc == 0) {
rb_scope_module_func_set();
return Qnil;
}
set_method_visibility(module, argc, argv, METHOD_VISI_PRIVATE);
for (i = 0; i < argc; i++) {
VALUE m = module;
id = rb_to_id(argv[i]);
for (;;) {
me = search_method(m, id, 0);
if (me == 0) {
me = search_method(rb_cObject, id, 0);
}
if (UNDEFINED_METHOD_ENTRY_P(me)) {
rb_print_undef(module, id, METHOD_VISI_UNDEF);
}
if (me->def->type != VM_METHOD_TYPE_ZSUPER) {
break; /* normal case: need not to follow 'super' link */
}
m = RCLASS_SUPER(m);
if (!m)
break;
}
rb_method_entry_set(rb_singleton_class(module), id, me, METHOD_VISI_PUBLIC);
}
if (argc == 1) {
return argv[0];
}
return rb_ary_new_from_values(argc, argv);
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#ruby2_keywords;F;7[[@90;[[@i> ;T;:ruby2_keywords;0; [ ; { ; IC; " For the given method names, marks the method as passing keywords through
a normal argument splat. This should only be called on methods that
accept an argument splat (*args) but not explicit keywords or
a keyword splat. It marks the method such that if the method is called
with keyword arguments, the final hash argument is marked with a special
flag such that if it is the final element of a normal argument splat to
another method call, and that method call does not include explicit
keywords or a keyword splat, the final element is interpreted as keywords.
In other words, keywords will be passed through the method to other
methods.
This should only be used for methods that delegate keywords to another
method, and only for backwards compatibility with Ruby versions before 3.0.
See https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
for details on why +ruby2_keywords+ exists and when and how to use it.
This method will probably be removed at some point, as it exists only
for backwards compatibility. As it does not exist in Ruby versions before
2.7, check that the module responds to this method before calling it:
module Mod
def foo(meth, *args, &block)
send(:"do_#{meth}", *args, &block)
end
ruby2_keywords(:foo) if respond_to?(:ruby2_keywords, true)
end
However, be aware that if the +ruby2_keywords+ method is removed, the
behavior of the +foo+ method using the above approach will change so that
the method does not pass through keywords.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"%ruby2_keywords(method_name, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@9;![ ;"I"@return [nil];T;#0;$@9;.F;Bi ;C0;7[[I"method_name;T0[I"...;T0;$@9;![ ;"I"FFor the given method names, marks the method as passing keywords through
a normal argument splat. This should only be called on methods that
accept an argument splat (*args) but not explicit keywords or
a keyword splat. It marks the method such that if the method is called
with keyword arguments, the final hash argument is marked with a special
flag such that if it is the final element of a normal argument splat to
another method call, and that method call does not include explicit
keywords or a keyword splat, the final element is interpreted as keywords.
In other words, keywords will be passed through the method to other
methods.
This should only be used for methods that delegate keywords to another
method, and only for backwards compatibility with Ruby versions before 3.0.
See https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
for details on why +ruby2_keywords+ exists and when and how to use it.
This method will probably be removed at some point, as it exists only
for backwards compatibility. As it does not exist in Ruby versions before
2.7, check that the module responds to this method before calling it:
module Mod
def foo(meth, *args, &block)
send(:"do_#{meth}", *args, &block)
end
ruby2_keywords(:foo) if respond_to?(:ruby2_keywords, true)
end
However, be aware that if the +ruby2_keywords+ method is removed, the
behavior of the +foo+ method using the above approach will change so that
the method does not pass through keywords.
@overload ruby2_keywords(method_name, ...)
@return [nil];T;#0;$@9;.F;/o;0;1T;2i ;3i; ;%@A7;9I": static VALUE
rb_mod_ruby2_keywords(int argc, VALUE *argv, VALUE module)
{
int i;
VALUE origin_class = RCLASS_ORIGIN(module);
rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
rb_check_frozen(module);
for (i = 0; i < argc; i++) {
VALUE v = argv[i];
ID name = rb_check_id(&v);
rb_method_entry_t *me;
VALUE defined_class;
if (!name) {
rb_print_undef_str(module, v);
}
me = search_method(origin_class, name, &defined_class);
if (!me && RB_TYPE_P(module, T_MODULE)) {
me = search_method(rb_cObject, name, &defined_class);
}
if (UNDEFINED_METHOD_ENTRY_P(me) ||
UNDEFINED_REFINED_METHOD_P(me->def)) {
rb_print_undef(module, name, METHOD_VISI_UNDEF);
}
if (module == defined_class || origin_class == defined_class) {
switch (me->def->type) {
case VM_METHOD_TYPE_ISEQ:
if (me->def->body.iseq.iseqptr->body->param.flags.has_rest &&
!me->def->body.iseq.iseqptr->body->param.flags.has_kw &&
!me->def->body.iseq.iseqptr->body->param.flags.has_kwrest) {
me->def->body.iseq.iseqptr->body->param.flags.ruby2_keywords = 1;
rb_clear_method_cache(module, name);
}
else {
rb_warn("Skipping set of ruby2_keywords flag for %s (method accepts keywords or method does not accept argument splat)", rb_id2name(name));
}
break;
case VM_METHOD_TYPE_BMETHOD: {
VALUE procval = me->def->body.bmethod.proc;
if (vm_block_handler_type(procval) == block_handler_type_proc) {
procval = vm_proc_to_block_handler(VM_BH_TO_PROC(procval));
}
if (vm_block_handler_type(procval) == block_handler_type_iseq) {
const struct rb_captured_block *captured = VM_BH_TO_ISEQ_BLOCK(procval);
const rb_iseq_t *iseq = rb_iseq_check(captured->code.iseq);
if (iseq->body->param.flags.has_rest &&
!iseq->body->param.flags.has_kw &&
!iseq->body->param.flags.has_kwrest) {
iseq->body->param.flags.ruby2_keywords = 1;
rb_clear_method_cache(module, name);
}
else {
rb_warn("Skipping set of ruby2_keywords flag for %s (method accepts keywords or method does not accept argument splat)", rb_id2name(name));
}
break;
}
}
/* fallthrough */
default:
rb_warn("Skipping set of ruby2_keywords flag for %s (method not defined in Ruby)", rb_id2name(name));
break;
}
}
else {
rb_warn("Skipping set of ruby2_keywords flag for %s (can only set in method defining module)", rb_id2name(name));
}
}
return Qnil;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#method_defined?;F;7[[@90;[[@iH;T;:method_defined?;0; [ ; { ; IC; "Returns +true+ if the named method is defined by
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors. Public and protected methods are matched.
String arguments are converted to symbols.
module A
def method1() end
def protected_method1() end
protected :protected_method1
end
class B
def method2() end
def private_method2() end
private :private_method2
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.method_defined? "method1" #=> true
C.method_defined? "method2" #=> true
C.method_defined? "method2", true #=> true
C.method_defined? "method2", false #=> false
C.method_defined? "method3" #=> true
C.method_defined? "protected_method1" #=> true
C.method_defined? "method4" #=> false
C.method_defined? "private_method2" #=> false;T; [o;=
;>I"
overload;F;?0;;;@0;:I"*method_defined?(symbol, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@9;![ ;"I"@return [Boolean];T;#0;$@9;.F;Bi ;C0;7[[I" symbol;T0[I" inherit;TI" true;T;$@9o;=
;>I"
overload;F;?0;;;@0;:I"*method_defined?(string, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@9;![ ;"I"@return [Boolean];T;#0;$@9;.F;Bi ;C0;7[[I" string;T0[I" inherit;TI" true;T;$@9;![ ;"I"HReturns +true+ if the named method is defined by
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors. Public and protected methods are matched.
String arguments are converted to symbols.
module A
def method1() end
def protected_method1() end
protected :protected_method1
end
class B
def method2() end
def private_method2() end
private :private_method2
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.method_defined? "method1" #=> true
C.method_defined? "method2" #=> true
C.method_defined? "method2", true #=> true
C.method_defined? "method2", false #=> false
C.method_defined? "method3" #=> true
C.method_defined? "protected_method1" #=> true
C.method_defined? "method4" #=> false
C.method_defined? "private_method2" #=> false
@overload method_defined?(symbol, inherit=true)
@return [Boolean]
@overload method_defined?(string, inherit=true)
@return [Boolean];T;#0;$@9;.F;/o;0;1T;2i$;3iF;Bi ;%@A7;9I"static VALUE
rb_mod_method_defined(int argc, VALUE *argv, VALUE mod)
{
rb_method_visibility_t visi = check_definition_visibility(mod, argc, argv);
return RBOOL(visi == METHOD_VISI_PUBLIC || visi == METHOD_VISI_PROTECTED);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I""Module#public_method_defined?;F;7[[@90;[[@is;T;:public_method_defined?;0; [ ; { ; IC; "Returns +true+ if the named public method is defined by
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors.
String arguments are converted to symbols.
module A
def method1() end
end
class B
protected
def method2() end
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.public_method_defined? "method1" #=> true
C.public_method_defined? "method1", true #=> true
C.public_method_defined? "method1", false #=> true
C.public_method_defined? "method2" #=> false
C.method_defined? "method2" #=> true;T; [o;=
;>I"
overload;F;?0;;;@0;:I"1public_method_defined?(symbol, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@9;![ ;"I"@return [Boolean];T;#0;$@9;.F;Bi ;C0;7[[I" symbol;T0[I" inherit;TI" true;T;$@9o;=
;>I"
overload;F;?0;;;@0;:I"1public_method_defined?(string, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@9;![ ;"I"@return [Boolean];T;#0;$@9;.F;Bi ;C0;7[[I" string;T0[I" inherit;TI" true;T;$@9;![ ;"I"4Returns +true+ if the named public method is defined by
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors.
String arguments are converted to symbols.
module A
def method1() end
end
class B
protected
def method2() end
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.public_method_defined? "method1" #=> true
C.public_method_defined? "method1", true #=> true
C.public_method_defined? "method1", false #=> true
C.public_method_defined? "method2" #=> false
C.method_defined? "method2" #=> true
@overload public_method_defined?(symbol, inherit=true)
@return [Boolean]
@overload public_method_defined?(string, inherit=true)
@return [Boolean];T;#0;$@9;.F;/o;0;1T;2iU;3iq;Bi ;%@A7;9I"static VALUE
rb_mod_public_method_defined(int argc, VALUE *argv, VALUE mod)
{
return check_definition(mod, argc, argv, METHOD_VISI_PUBLIC);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"#Module#private_method_defined?;F;7[[@90;[[@i;T;: private_method_defined?;0; [ ; { ; IC; "Returns +true+ if the named private method is defined by
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors.
String arguments are converted to symbols.
module A
def method1() end
end
class B
private
def method2() end
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.private_method_defined? "method1" #=> false
C.private_method_defined? "method2" #=> true
C.private_method_defined? "method2", true #=> true
C.private_method_defined? "method2", false #=> false
C.method_defined? "method2" #=> false;T; [o;=
;>I"
overload;F;?0;;;@0;:I"2private_method_defined?(symbol, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@2:;![ ;"I"@return [Boolean];T;#0;$@2:;.F;Bi ;C0;7[[I" symbol;T0[I" inherit;TI" true;T;$@2:o;=
;>I"
overload;F;?0;;;@0;:I"2private_method_defined?(string, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@2:;![ ;"I"@return [Boolean];T;#0;$@2:;.F;Bi ;C0;7[[I" string;T0[I" inherit;TI" true;T;$@2:;![ ;"I"CReturns +true+ if the named private method is defined by
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors.
String arguments are converted to symbols.
module A
def method1() end
end
class B
private
def method2() end
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.private_method_defined? "method1" #=> false
C.private_method_defined? "method2" #=> true
C.private_method_defined? "method2", true #=> true
C.private_method_defined? "method2", false #=> false
C.method_defined? "method2" #=> false
@overload private_method_defined?(symbol, inherit=true)
@return [Boolean]
@overload private_method_defined?(string, inherit=true)
@return [Boolean];T;#0;$@2:;.F;/o;0;1T;2iy;3i;Bi ;%@A7;9I"static VALUE
rb_mod_private_method_defined(int argc, VALUE *argv, VALUE mod)
{
return check_definition(mod, argc, argv, METHOD_VISI_PRIVATE);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"%Module#protected_method_defined?;F;7[[@90;[[@i;T;: protected_method_defined?;0; [ ; { ; IC; "Returns +true+ if the named protected method is defined
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors.
String arguments are converted to symbols.
module A
def method1() end
end
class B
protected
def method2() end
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.protected_method_defined? "method1" #=> false
C.protected_method_defined? "method2" #=> true
C.protected_method_defined? "method2", true #=> true
C.protected_method_defined? "method2", false #=> false
C.method_defined? "method2" #=> true;T; [o;=
;>I"
overload;F;?0;;;@0;:I"4protected_method_defined?(symbol, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@e:;![ ;"I"@return [Boolean];T;#0;$@e:;.F;Bi ;C0;7[[I" symbol;T0[I" inherit;TI" true;T;$@e:o;=
;>I"
overload;F;?0;;;@0;:I"4protected_method_defined?(string, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@e:;![ ;"I"@return [Boolean];T;#0;$@e:;.F;Bi ;C0;7[[I" string;T0[I" inherit;TI" true;T;$@e:;![ ;"I"MReturns +true+ if the named protected method is defined
_mod_. If _inherit_ is set, the lookup will also search _mod_'s
ancestors.
String arguments are converted to symbols.
module A
def method1() end
end
class B
protected
def method2() end
end
class C < B
include A
def method3() end
end
A.method_defined? :method1 #=> true
C.protected_method_defined? "method1" #=> false
C.protected_method_defined? "method2" #=> true
C.protected_method_defined? "method2", true #=> true
C.protected_method_defined? "method2", false #=> false
C.method_defined? "method2" #=> true
@overload protected_method_defined?(symbol, inherit=true)
@return [Boolean]
@overload protected_method_defined?(string, inherit=true)
@return [Boolean];T;#0;$@e:;.F;/o;0;1T;2i;3i;Bi ;%@A7;9I"static VALUE
rb_mod_protected_method_defined(int argc, VALUE *argv, VALUE mod)
{
return check_definition(mod, argc, argv, METHOD_VISI_PROTECTED);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Module#public_class_method;F;7[[@90;[[@i ;T;:public_class_method;0; [ ; { ; IC; "Makes a list of existing class methods public.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"%public_class_method(symbol, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@:;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@:o;=
;>I"
overload;F;?0;;;@0;:I"%public_class_method(string, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@:;.F;Bi ;C0;7[[I" string;T0[I"...;T0;$@:o;=
;>I"
overload;F;?0;;;@0;:I" public_class_method(array);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@:;.F;Bi ;C0;7[[I"
array;T0;$@:;![ ;"I" Makes a list of existing class methods public.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
@overload public_class_method(symbol, ...)
@overload public_class_method(string, ...)
@overload public_class_method(array);T;#0;$@:;.F;/o;0;1T;2i ;3i ;%@A7;9I"static VALUE
rb_mod_public_method(int argc, VALUE *argv, VALUE obj)
{
set_method_visibility(rb_singleton_class(obj), argc, argv, METHOD_VISI_PUBLIC);
return obj;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Module#private_class_method;F;7[[@90;[[@i ;T;:private_class_method;0; [ ; { ; IC; "Makes existing class methods private. Often used to hide the default
constructor new.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
class SimpleSingleton # Not thread safe
private_class_method :new
def SimpleSingleton.create(*args, &block)
@me = new(*args, &block) if ! @me
@me
end
end
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"&private_class_method(symbol, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@:;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@:o;=
;>I"
overload;F;?0;;;@0;:I"&private_class_method(string, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@:;.F;Bi ;C0;7[[I" string;T0[I"...;T0;$@:o;=
;>I"
overload;F;?0;;;@0;:I" private_class_method(array);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@:;.F;Bi ;C0;7[[I"
array;T0;$@:;![ ;"I"Makes existing class methods private. Often used to hide the default
constructor new.
String arguments are converted to symbols.
An Array of Symbols and/or Strings is also accepted.
class SimpleSingleton # Not thread safe
private_class_method :new
def SimpleSingleton.create(*args, &block)
@me = new(*args, &block) if ! @me
@me
end
end
@overload private_class_method(symbol, ...)
@overload private_class_method(string, ...)
@overload private_class_method(array);T;#0;$@:;.F;/o;0;1T;2i ;3i ;%@A7;9I"static VALUE
rb_mod_private_method(int argc, VALUE *argv, VALUE obj)
{
set_method_visibility(rb_singleton_class(obj), argc, argv, METHOD_VISI_PRIVATE);
return obj;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#included;F;7[ ;[ ;F;;
;;; [ ; { ; IC; "call-seq:
included(othermod)
Callback invoked whenever the receiver is included in another
module or class. This should be used in preference to
Module.append_features if your code wants to perform some
action when a module is included in another.
module A
def A.included(mod)
puts "#{self} included in #{mod}"
end
end
module Enumerable
include A
end
# => prints "A included in Enumerable"
;T; [ ;![ ;"I"
call-seq:
included(othermod)
Callback invoked whenever the receiver is included in another
module or class. This should be used in preference to
Module.append_features if your code wants to perform some
action when a module is included in another.
module A
def A.included(mod)
puts "#{self} included in #{mod}"
end
end
module Enumerable
include A
end
# => prints "A included in Enumerable"
;T;#0;$@:;.F;/o;0;1T;2i;3i;%@A7;;To;4;5F;6;;;;&I"Module#extended;F;7[ ;[ ;F;:
extended;;; [ ; { ; IC; ":call-seq:
extended(othermod)
The equivalent of included, but for extended modules.
module A
def self.extended(mod)
puts "#{self} extended in #{mod}"
end
end
module Enumerable
extend A
end
# => prints "A extended in Enumerable"
;T; [ ;![ ;"I"<
call-seq:
extended(othermod)
The equivalent of included, but for extended modules.
module A
def self.extended(mod)
puts "#{self} extended in #{mod}"
end
end
module Enumerable
extend A
end
# => prints "A extended in Enumerable"
;T;#0;$@;;.F;/o;0;1T;2i;3i;%@A7;;To;4;5F;6;;;;&I"Module#prepended;F;7[ ;[ ;F;:prepended;;; [ ; { ; IC; "@call-seq:
prepended(othermod)
The equivalent of included, but for prepended modules.
module A
def self.prepended(mod)
puts "#{self} prepended to #{mod}"
end
end
module Enumerable
prepend A
end
# => prints "A prepended to Enumerable"
;T; [ ;![ ;"I"B
call-seq:
prepended(othermod)
The equivalent of included, but for prepended modules.
module A
def self.prepended(mod)
puts "#{self} prepended to #{mod}"
end
end
module Enumerable
prepend A
end
# => prints "A prepended to Enumerable"
;T;#0;$@;;.F;/o;0;1T;2i;3i*;%@A7;;To;4;5F;6;;;;&I"Module#method_added;F;7[ ;[ ;F;:method_added;;; [ ; { ; IC; "_call-seq:
method_added(method_name)
Invoked as a callback whenever an instance method is added to the
receiver.
module Chatty
def self.method_added(method_name)
puts "Adding #{method_name.inspect}"
end
def self.some_class_method() end
def some_instance_method() end
end
produces:
Adding :some_instance_method
;T; [ ;![ ;"I"b
call-seq:
method_added(method_name)
Invoked as a callback whenever an instance method is added to the
receiver.
module Chatty
def self.method_added(method_name)
puts "Adding #{method_name.inspect}"
end
def self.some_class_method() end
def some_instance_method() end
end
produces:
Adding :some_instance_method
;T;#0;$@;;.F;/o;0;1T;2iR;3ie;%@A7;;To;4;5F;6;;;;&I"Module#method_removed;F;7[ ;[ ;F;:method_removed;;; [ ; { ; IC; "call-seq:
method_removed(method_name)
Invoked as a callback whenever an instance method is removed from the
receiver.
module Chatty
def self.method_removed(method_name)
puts "Removing #{method_name.inspect}"
end
def self.some_class_method() end
def some_instance_method() end
class << self
remove_method :some_class_method
end
remove_method :some_instance_method
end
produces:
Removing :some_instance_method
;T; [ ;![ ;"I"
call-seq:
method_removed(method_name)
Invoked as a callback whenever an instance method is removed from the
receiver.
module Chatty
def self.method_removed(method_name)
puts "Removing #{method_name.inspect}"
end
def self.some_class_method() end
def some_instance_method() end
class << self
remove_method :some_class_method
end
remove_method :some_instance_method
end
produces:
Removing :some_instance_method
;T;#0;$@&;;.F;/o;0;1T;2ii;3i;%@A7;;To;4;5F;6;;;;&I" Module#method_undefined;F;7[ ;[ ;F;:method_undefined;;; [ ; { ; IC; "call-seq:
method_undefined(method_name)
Invoked as a callback whenever an instance method is undefined from the
receiver.
module Chatty
def self.method_undefined(method_name)
puts "Undefining #{method_name.inspect}"
end
def self.some_class_method() end
def some_instance_method() end
class << self
undef_method :some_class_method
end
undef_method :some_instance_method
end
produces:
Undefining :some_instance_method
;T; [ ;![ ;"I"
call-seq:
method_undefined(method_name)
Invoked as a callback whenever an instance method is undefined from the
receiver.
module Chatty
def self.method_undefined(method_name)
puts "Undefining #{method_name.inspect}"
end
def self.some_class_method() end
def some_instance_method() end
class << self
undef_method :some_class_method
end
undef_method :some_instance_method
end
produces:
Undefining :some_instance_method
;T;#0;$@1;;.F;/o;0;1T;2i;3i;%@A7;;To;4;5F;6;;; ;&I"Module#freeze;F;7[ ;[[@mod.
This method returns self.
;T; [o;=
;>I"
overload;F;?0;;f;@0;:I" freeze;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@<;;.F;Bi ;C0;7[ ;$@<;;![ ;"I"`Prevents further modifications to mod.
This method returns self.
@overload freeze;T;#0;$@<;;.F;/o;0;1T;2iW;3i\;%@A7;9I"estatic VALUE
rb_mod_freeze(VALUE mod)
{
rb_class_name(mod);
return rb_obj_freeze(mod);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#===;F;7[[I"arg;T0;[[@true if obj is an
instance of mod or an instance of one of mod's descendants.
Of limited use for modules, but can be used in case statements
to classify objects by class.
;T; [o;=
;>I"
overload;F;?0;;S;@0;:I"
===(obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@R;;![ ;"I"@return [Boolean];T;#0;$@R;;.F;Bi ;C0;7[[I"obj;T0;$@R;;![ ;"I"Case Equality---Returns true if obj is an
instance of mod or an instance of one of mod's descendants.
Of limited use for modules, but can be used in case statements
to classify objects by class.
@overload ===(obj)
@return [Boolean];T;#0;$@R;;.F;/o;0;1T;2ig;3in;%@A7;9I"^static VALUE
rb_mod_eqq(VALUE mod, VALUE arg)
{
return rb_obj_is_kind_of(arg, mod);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#==;F;7[[I" obj2;T0;[[@true
only if +obj+ and +other+ are the same object. Typically, this
method is overridden in descendant classes to provide
class-specific meaning.
Unlike #==, the #equal? method should never be overridden by
subclasses as it is used to determine object identity (that is,
a.equal?(b) if and only if a is the same
object as b):
obj = "a"
other = obj.dup
obj == other #=> true
obj.equal? other #=> false
obj.equal? obj #=> true
The #eql? method returns true if +obj+ and +other+
refer to the same hash key. This is used by Hash to test members
for equality. For any pair of objects where #eql? returns +true+,
the #hash value of both objects must be equal. So any subclass
that overrides #eql? should also override #hash appropriately.
For objects of class Object, #eql? is synonymous
with #==. Subclasses normally continue this tradition by aliasing
#eql? to their overridden #== method, but there are exceptions.
Numeric types, for example, perform type conversion across #==,
but not across #eql?, so:
1 == 1.0 #=> true
1.eql? 1.0 #=> false
;T; [o;=
;>I"
overload;F;?0;;F;@0;:I"==(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@q;;![ ;"I"@return [Boolean];T;#0;$@q;;.F;Bi ;C0;7[[I"
other;T0;$@q;o;=
;>I"
overload;F;?0;;W;@0;:I"equal?(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@q;;![ ;"I"@return [Boolean];T;#0;$@q;;.F;Bi ;C0;7[[I"
other;T0;$@q;o;=
;>I"
overload;F;?0;;V;@0;:I"eql?(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@q;;![ ;"I"@return [Boolean];T;#0;$@q;;.F;Bi ;C0;7[[I"
other;T0;$@q;;![ ;"@;#0;$@q;;.F;/o;0;1T;2i;3i;%@A7;9I"fMJIT_FUNC_EXPORTED VALUE
rb_obj_equal(VALUE obj1, VALUE obj2)
{
return RBOOL(obj1 == obj2);
};T;:I" MJIT_FUNC_EXPORTED VALUE;T;;To;4;5F;6;;; ;&I"Module#<=>;F;7[[I"arg;T0;[[@I"
overload;F;?0;;Y;@0;:I"<=>(other_module);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[ I"-1;TI"0;TI"+1;TI"nil;T;$@;;![ ;"I" @return [-1, 0, +1, nil];T;#0;$@;;.F;Bi ;C0;7[[I"other_module;T0;$@;;![ ;"I"fComparison---Returns -1, 0, +1 or nil depending on whether +module+
includes +other_module+, they are the same, or if +module+ is included by
+other_module+.
Returns +nil+ if +module+ has no relationship with +other_module+, if
+other_module+ is not a module, or if the two values are incomparable.
@overload <=>(other_module)
@return [-1, 0, +1, nil];T;#0;$@;;.F;/o;0;1T;2i;3i;%@A7;9I",static VALUE
rb_mod_cmp(VALUE mod, VALUE arg)
{
VALUE cmp;
if (mod == arg) return INT2FIX(0);
if (!CLASS_OR_MODULE_P(arg)) {
return Qnil;
}
cmp = rb_class_inherited_p(mod, arg);
if (NIL_P(cmp)) return Qnil;
if (cmp) {
return INT2FIX(-1);
}
return INT2FIX(1);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
Module#<;F;7[[I"arg;T0;[[@mod is a subclass of other. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "A < B".)
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
<(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" true;TI"
false;TI"nil;T;$@;;![ ;"I" @return [true, false, nil];T;#0;$@;;.F;Bi ;C0;7[[I"
other;T0;$@;;![ ;"I"Returns true if mod is a subclass of other. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "A < B".)
@overload <(other)
@return [true, false, nil];T;#0;$@;;.F;/o;0;1T;2i;3i;%@A7;9I"~static VALUE
rb_mod_lt(VALUE mod, VALUE arg)
{
if (mod == arg) return Qfalse;
return rb_class_inherited_p(mod, arg);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#<=;F;7[[I"arg;T0;[[@mod is a subclass of other or
is the same as other. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "A < B".)
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"<=(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" true;TI"
false;TI"nil;T;$@;;![ ;"I" @return [true, false, nil];T;#0;$@;;.F;Bi ;C0;7[[I"
other;T0;$@;;![ ;"I"-Returns true if mod is a subclass of other or
is the same as other. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "A < B".)
@overload <=(other)
@return [true, false, nil];T;#0;$@;;.F;/o;0;1T;2iw;3i;%@A7;9I"VALUE
rb_class_inherited_p(VALUE mod, VALUE arg)
{
if (mod == arg) return Qtrue;
if (!CLASS_OR_MODULE_P(arg) && !RB_TYPE_P(arg, T_ICLASS)) {
rb_raise(rb_eTypeError, "compared with non class/module");
}
if (class_search_ancestor(mod, RCLASS_ORIGIN(arg))) {
return Qtrue;
}
/* not mod < arg; check if mod > arg */
if (class_search_ancestor(arg, mod)) {
return Qfalse;
}
return Qnil;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"
Module#>;F;7[[I"arg;T0;[[@;0; [ ; { ; IC; "Returns true if mod is an ancestor of other. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "B > A".)
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
>(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" true;TI"
false;TI"nil;T;$@<;![ ;"I" @return [true, false, nil];T;#0;$@<;.F;Bi ;C0;7[[I"
other;T0;$@<;![ ;"I"Returns true if mod is an ancestor of other. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "B > A".)
@overload >(other)
@return [true, false, nil];T;#0;$@<;.F;/o;0;1T;2i;3i;%@A7;9I"xstatic VALUE
rb_mod_gt(VALUE mod, VALUE arg)
{
if (mod == arg) return Qfalse;
return rb_mod_ge(mod, arg);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#>=;F;7[[I"arg;T0;[[@=;0; [ ; { ; IC; "Returns true if mod is an ancestor of other, or the
two modules are the same. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "B > A".)
;T; [o;=
;>I"
overload;F;?0;;;@0;:I">=(other);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" true;TI"
false;TI"nil;T;$@2<;![ ;"I" @return [true, false, nil];T;#0;$@2<;.F;Bi ;C0;7[[I"
other;T0;$@2<;![ ;"I"1Returns true if mod is an ancestor of other, or the
two modules are the same. Returns
nil if there's no relationship between the two.
(Think of the relationship in terms of the class definition:
"class A < B" implies "B > A".)
@overload >=(other)
@return [true, false, nil];T;#0;$@2<;.F;/o;0;1T;2i;3i;%@A7;9I"static VALUE
rb_mod_ge(VALUE mod, VALUE arg)
{
if (!CLASS_OR_MODULE_P(arg)) {
rb_raise(rb_eTypeError, "compared with non class/module");
}
return rb_class_inherited_p(arg, mod);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#initialize_copy;F;7[[I" orig;T0;[[@ni;T;;];0; [ ; { ; IC; " :nodoc:
;T; [ ;![ ;"I" :nodoc:;T;#0;$@S<;.F;/o;0;1T;2i;3i;%@A7;9I"OVALUE
rb_mod_init_copy(VALUE clone, VALUE orig)
{
switch (BUILTIN_TYPE(clone)) {
case T_CLASS:
case T_ICLASS:
class_init_copy_check(clone, orig);
break;
case T_MODULE:
rb_module_check_initializable(clone);
break;
default:
break;
}
if (!OBJ_INIT_COPY(clone, orig)) return clone;
/* cloned flag is refer at constant inline cache
* see vm_get_const_key_cref() in vm_insnhelper.c
*/
FL_SET(clone, RCLASS_CLONED);
FL_SET(orig , RCLASS_CLONED);
if (!FL_TEST(CLASS_OF(clone), FL_SINGLETON)) {
RBASIC_SET_CLASS(clone, rb_singleton_class_clone(orig));
rb_singleton_class_attached(RBASIC(clone)->klass, (VALUE)clone);
}
RCLASS_ALLOCATOR(clone) = RCLASS_ALLOCATOR(orig);
copy_tables(clone, orig);
if (RCLASS_M_TBL(orig)) {
struct clone_method_arg arg;
arg.old_klass = orig;
arg.new_klass = clone;
RCLASS_M_TBL_INIT(clone);
rb_id_table_foreach(RCLASS_M_TBL(orig), clone_method_i, &arg);
}
if (RCLASS_ORIGIN(orig) == orig) {
RCLASS_SET_SUPER(clone, RCLASS_SUPER(orig));
}
else {
VALUE p = RCLASS_SUPER(orig);
VALUE orig_origin = RCLASS_ORIGIN(orig);
VALUE prev_clone_p = clone;
VALUE origin_stack = rb_ary_tmp_new(2);
VALUE origin[2];
VALUE clone_p = 0;
long origin_len;
int add_subclass;
VALUE clone_origin;
ensure_origin(clone);
clone_origin = RCLASS_ORIGIN(clone);
while (p && p != orig_origin) {
if (BUILTIN_TYPE(p) != T_ICLASS) {
rb_bug("non iclass between module/class and origin");
}
clone_p = class_alloc(RBASIC(p)->flags, RBASIC(p)->klass);
RCLASS_SET_SUPER(prev_clone_p, clone_p);
prev_clone_p = clone_p;
RCLASS_M_TBL(clone_p) = RCLASS_M_TBL(p);
RCLASS_CONST_TBL(clone_p) = RCLASS_CONST_TBL(p);
RCLASS_IV_TBL(clone_p) = RCLASS_IV_TBL(p);
RCLASS_ALLOCATOR(clone_p) = RCLASS_ALLOCATOR(p);
if (RB_TYPE_P(clone, T_CLASS)) {
RCLASS_SET_INCLUDER(clone_p, clone);
}
add_subclass = TRUE;
if (p != RCLASS_ORIGIN(p)) {
origin[0] = clone_p;
origin[1] = RCLASS_ORIGIN(p);
rb_ary_cat(origin_stack, origin, 2);
}
else if ((origin_len = RARRAY_LEN(origin_stack)) > 1 &&
RARRAY_AREF(origin_stack, origin_len - 1) == p) {
RCLASS_SET_ORIGIN(RARRAY_AREF(origin_stack, (origin_len -= 2)), clone_p);
RICLASS_SET_ORIGIN_SHARED_MTBL(clone_p);
rb_ary_resize(origin_stack, origin_len);
add_subclass = FALSE;
}
if (add_subclass) {
rb_module_add_to_subclasses_list(RBASIC(p)->klass, clone_p);
}
p = RCLASS_SUPER(p);
}
if (p == orig_origin) {
if (clone_p) {
RCLASS_SET_SUPER(clone_p, clone_origin);
RCLASS_SET_SUPER(clone_origin, RCLASS_SUPER(orig_origin));
}
copy_tables(clone_origin, orig_origin);
if (RCLASS_M_TBL(orig_origin)) {
struct clone_method_arg arg;
arg.old_klass = orig;
arg.new_klass = clone;
RCLASS_M_TBL_INIT(clone_origin);
rb_id_table_foreach(RCLASS_M_TBL(orig_origin), clone_method_i, &arg);
}
}
else {
rb_bug("no origin for class that has origin");
}
}
return clone;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#to_s;F;7[ ;[[@I"
overload;F;?0;;G;@0;:I" to_s;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@c<;![ ;"I"@return [String];T;#0;$@c<;.F;Bi ;C0;7[ ;$@c<;![ ;"I"Returns a string representing this module or class. For basic
classes and modules, this is the name. For singletons, we
show information on the thing we're attached to as well.
@overload to_s
@return [String];T;#0;$o;4;5F;6;;; ;&I"Module#inspect;F;7[ ;[[@");
return s;
}
refined_class = rb_refinement_module_get_refined_class(klass);
if (!NIL_P(refined_class)) {
VALUE s = rb_usascii_str_new2("#true if module is included
or prepended in mod or one of mod's ancestors.
module A
end
class B
include A
end
class C < B
end
B.include?(A) #=> true
C.include?(A) #=> true
A.include?(A) #=> false;T; [o;=
;>I"
overload;F;?0;;;@0;:I"include?(module);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@<;![ ;"I"@return [Boolean];T;#0;$@<;.F;Bi ;C0;7[ ;$@<;![ ;"I"DReturns true if module is included
or prepended in mod or one of mod's ancestors.
module A
end
class B
include A
end
class C < B
end
B.include?(A) #=> true
C.include?(A) #=> true
A.include?(A) #=> false
@overload include?(module)
@return [Boolean];T;#0;$@<;.F;/o;0;1T;2iT;3id;Bi ;%@A7;9I"3VALUE
rb_mod_include_p(VALUE mod, VALUE mod2)
{
VALUE p;
Check_Type(mod2, T_MODULE);
for (p = RCLASS_SUPER(mod); p; p = RCLASS_SUPER(p)) {
if (BUILTIN_TYPE(p) == T_ICLASS && !FL_TEST(p, RICLASS_IS_ORIGIN)) {
if (RBASIC(p)->klass == mod2) return Qtrue;
}
}
return Qfalse;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#name;F;7[ ;[[@ i};T;;F;0; [ ; { ; IC; "SReturns the name of the module mod. Returns nil for anonymous modules.
;T; [o;=
;>I"
overload;F;?0;;F;@0;:I" name;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@<;![ ;"I"@return [String];T;#0;$@<;.F;Bi ;C0;7[ ;$@<;![ ;"I"wReturns the name of the module mod. Returns nil for anonymous modules.
@overload name
@return [String];T;#0;$@<;.F;/o;0;1T;2iv;3iz;%@A7;9I"_VALUE
rb_mod_name(VALUE mod)
{
int permanent;
return classname(mod, &permanent);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#ancestors;F;7[ ;[[@ni;T;:ancestors;0; [ ; { ; IC; ">Returns a list of modules included/prepended in mod
(including mod itself).
module Mod
include Math
include Comparable
prepend Enumerable
end
Mod.ancestors #=> [Enumerable, Mod, Comparable, Math]
Math.ancestors #=> [Math]
Enumerable.ancestors #=> [Enumerable]
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"ancestors;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@<;![ ;"I"@return [Array];T;#0;$@<;.F;Bi ;C0;7[ ;$@<;![ ;"I"fReturns a list of modules included/prepended in mod
(including mod itself).
module Mod
include Math
include Comparable
prepend Enumerable
end
Mod.ancestors #=> [Enumerable, Mod, Comparable, Math]
Math.ancestors #=> [Math]
Enumerable.ancestors #=> [Enumerable]
@overload ancestors
@return [Array];T;#0;$@<;.F;/o;0;1T;2iu;3i;%@A7;9I"VALUE
rb_mod_ancestors(VALUE mod)
{
VALUE p, ary = rb_ary_new();
VALUE refined_class = Qnil;
if (FL_TEST(mod, RMODULE_IS_REFINEMENT)) {
refined_class = rb_refinement_module_get_refined_class(mod);
}
for (p = mod; p; p = RCLASS_SUPER(p)) {
if (p == refined_class) break;
if (p != RCLASS_ORIGIN(p)) continue;
if (BUILTIN_TYPE(p) == T_ICLASS) {
rb_ary_push(ary, RBASIC(p)->klass);
}
else {
rb_ary_push(ary, p);
}
}
return ary;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#attr;F;7[[@90;[[@attr_accessor(name) but deprecated.
The last form is equivalent to attr_reader(name) but deprecated.
Returns an array of defined method names as symbols.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"attr(name, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@<;![ ;"I"@return [Array];T;#0;$@<;.F;Bi ;C0;7[[I" name;T0[I"...;T0;$@attr_accessor(name) but deprecated.
The last form is equivalent to attr_reader(name) but deprecated.
Returns an array of defined method names as symbols.
@overload attr(name, ...)
@return [Array]
@overload attr(name, true)
@return [Array]
@overload attr(name, false)
@return [Array];T;#0;$@<;.F;/o;0;1T;2ib;3in;%@A7;9I"VALUE
rb_mod_attr(int argc, VALUE *argv, VALUE klass)
{
if (argc == 2 && (argv[1] == Qtrue || argv[1] == Qfalse)) {
ID id = id_for_attr(klass, argv[0]);
VALUE names = rb_ary_new();
rb_category_warning(RB_WARN_CATEGORY_DEPRECATED, "optional boolean argument is obsoleted");
rb_attr(klass, id, 1, RTEST(argv[1]), TRUE);
rb_ary_push(names, ID2SYM(id));
if (argv[1] == Qtrue) rb_ary_push(names, ID2SYM(rb_id_attrset(id)));
return names;
}
return rb_mod_attr_reader(argc, argv, klass);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#attr_reader;F;7[[@90;[[@attr:name'' on each name in turn.
String arguments are converted to symbols.
Returns an array of defined method names as symbols.
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I" attr_reader(symbol, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@6=;![ ;"I"@return [Array];T;#0;$@6=;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@6=o;=
;>I"
overload;F;?0;;;@0;:I"attr(symbol, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@6=;![ ;"I"@return [Array];T;#0;$@6=;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@6=o;=
;>I"
overload;F;?0;;;@0;:I" attr_reader(string, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@6=;![ ;"I"@return [Array];T;#0;$@6=;.F;Bi ;C0;7[[I" string;T0[I"...;T0;$@6=o;=
;>I"
overload;F;?0;;;@0;:I"attr(string, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@6=;![ ;"I"@return [Array];T;#0;$@6=;.F;Bi ;C0;7[[I" string;T0[I"...;T0;$@6=;![ ;"I"Creates instance variables and corresponding methods that return the
value of each instance variable. Equivalent to calling
``attr:name'' on each name in turn.
String arguments are converted to symbols.
Returns an array of defined method names as symbols.
@overload attr_reader(symbol, ...)
@return [Array]
@overload attr(symbol, ...)
@return [Array]
@overload attr_reader(string, ...)
@return [Array]
@overload attr(string, ...)
@return [Array];T;#0;$@6=;.F;/o;0;1T;2iF;3iT;%@A7;9I" static VALUE
rb_mod_attr_reader(int argc, VALUE *argv, VALUE klass)
{
int i;
VALUE names = rb_ary_new2(argc);
for (i=0; i.id2name.
String arguments are converted to symbols.
Returns an array of defined method names as symbols.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" attr_writer(symbol, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@=;![ ;"I"@return [Array];T;#0;$@=;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@=o;=
;>I"
overload;F;?0;;;@0;:I" attr_writer(string, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@=;![ ;"I"@return [Array];T;#0;$@=;.F;Bi ;C0;7[[I" string;T0[I"...;T0;$@=;![ ;"I"/Creates an accessor method to allow assignment to the attribute
symbol.id2name.
String arguments are converted to symbols.
Returns an array of defined method names as symbols.
@overload attr_writer(symbol, ...)
@return [Array]
@overload attr_writer(string, ...)
@return [Array];T;#0;$@=;.F;/o;0;1T;2i;3i;%@A7;9I"+static VALUE
rb_mod_attr_writer(int argc, VALUE *argv, VALUE klass)
{
int i;
VALUE names = rb_ary_new2(argc);
for (i=0; iid2name, creating an instance variable
(@name) and a corresponding access method to read it.
Also creates a method called name= to set the attribute.
String arguments are converted to symbols.
Returns an array of defined method names as symbols.
module Mod
attr_accessor(:one, :two) #=> [:one, :one=, :two, :two=]
end
Mod.instance_methods.sort #=> [:one, :one=, :two, :two=]
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" attr_accessor(symbol, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@=;![ ;"I"@return [Array];T;#0;$@=;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@=o;=
;>I"
overload;F;?0;;;@0;:I" attr_accessor(string, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@=;![ ;"I"@return [Array];T;#0;$@=;.F;Bi ;C0;7[[I" string;T0[I"...;T0;$@=;![ ;"I"iDefines a named attribute for this module, where the name is
symbol.id2name, creating an instance variable
(@name) and a corresponding access method to read it.
Also creates a method called name= to set the attribute.
String arguments are converted to symbols.
Returns an array of defined method names as symbols.
module Mod
attr_accessor(:one, :two) #=> [:one, :one=, :two, :two=]
end
Mod.instance_methods.sort #=> [:one, :one=, :two, :two=]
@overload attr_accessor(symbol, ...)
@return [Array]
@overload attr_accessor(string, ...)
@return [Array];T;#0;$@=;.F;/o;0;1T;2i;3i;%@A7;9I"Rstatic VALUE
rb_mod_attr_accessor(int argc, VALUE *argv, VALUE klass)
{
int i;
VALUE names = rb_ary_new2(argc * 2);
for (i=0; ifalse, the methods of any ancestors are not included.
module A
def method1() end
end
class B
include A
def method2() end
end
class C < B
def method3() end
end
A.instance_methods(false) #=> [:method1]
B.instance_methods(false) #=> [:method2]
B.instance_methods(true).include?(:method1) #=> true
C.instance_methods(false) #=> [:method3]
C.instance_methods.include?(:method2) #=> true
;T; [o;=
;>I"
overload;F;?0;;;@0;:I")instance_methods(include_super=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@ >;![ ;"I"@return [Array];T;#0;$@ >;.F;Bi ;C0;7[[I"include_super;TI" true;T;$@ >;![ ;"I":Returns an array containing the names of the public and protected instance
methods in the receiver. For a module, these are the public and protected methods;
for a class, they are the instance (not singleton) methods. If the optional
parameter is false, the methods of any ancestors are not included.
module A
def method1() end
end
class B
include A
def method2() end
end
class C < B
def method3() end
end
A.instance_methods(false) #=> [:method1]
B.instance_methods(false) #=> [:method2]
B.instance_methods(true).include?(:method1) #=> true
C.instance_methods(false) #=> [:method3]
C.instance_methods.include?(:method2) #=> true
@overload instance_methods(include_super=true)
@return [Array];T;#0;$@ >;.F;/o;0;1T;2il;3i;%@A7;9I"VALUE
rb_class_instance_methods(int argc, const VALUE *argv, VALUE mod)
{
return class_instance_method_list(argc, argv, mod, 0, ins_methods_i);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"#Module#public_instance_methods;F;7[[@90;[[@ni;T;: public_instance_methods;0; [ ; { ; IC; "Returns a list of the public instance methods defined in mod.
If the optional parameter is false, the methods of
any ancestors are not included.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"0public_instance_methods(include_super=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@<>;![ ;"I"@return [Array];T;#0;$@<>;.F;Bi ;C0;7[[I"include_super;TI" true;T;$@<>;![ ;"I"Returns a list of the public instance methods defined in mod.
If the optional parameter is false, the methods of
any ancestors are not included.
@overload public_instance_methods(include_super=true)
@return [Array];T;#0;$@<>;.F;/o;0;1T;2i;3i;%@A7;9I"VALUE
rb_class_public_instance_methods(int argc, const VALUE *argv, VALUE mod)
{
return class_instance_method_list(argc, argv, mod, 0, ins_methods_pub_i);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"&Module#protected_instance_methods;F;7[[@90;[[@ni;T;: protected_instance_methods;0; [ ; { ; IC; "Returns a list of the protected instance methods defined in
mod. If the optional parameter is false, the
methods of any ancestors are not included.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"3protected_instance_methods(include_super=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@[>;![ ;"I"@return [Array];T;#0;$@[>;.F;Bi ;C0;7[[I"include_super;TI" true;T;$@[>;![ ;"I"Returns a list of the protected instance methods defined in
mod. If the optional parameter is false, the
methods of any ancestors are not included.
@overload protected_instance_methods(include_super=true)
@return [Array];T;#0;$@[>;.F;/o;0;1T;2i;3i;%@A7;9I"VALUE
rb_class_protected_instance_methods(int argc, const VALUE *argv, VALUE mod)
{
return class_instance_method_list(argc, argv, mod, 0, ins_methods_prot_i);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"$Module#private_instance_methods;F;7[[@90;[[@ni;T;: private_instance_methods;0; [ ; { ; IC; "cReturns a list of the private instance methods defined in
mod. If the optional parameter is false, the
methods of any ancestors are not included.
module Mod
def method1() end
private :method1
def method2() end
end
Mod.instance_methods #=> [:method2]
Mod.private_instance_methods #=> [:method1]
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"1private_instance_methods(include_super=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@z>;![ ;"I"@return [Array];T;#0;$@z>;.F;Bi ;C0;7[[I"include_super;TI" true;T;$@z>;![ ;"I"Returns a list of the private instance methods defined in
mod. If the optional parameter is false, the
methods of any ancestors are not included.
module Mod
def method1() end
private :method1
def method2() end
end
Mod.instance_methods #=> [:method2]
Mod.private_instance_methods #=> [:method1]
@overload private_instance_methods(include_super=true)
@return [Array];T;#0;$@z>;.F;/o;0;1T;2i;3i;%@A7;9I"VALUE
rb_class_private_instance_methods(int argc, const VALUE *argv, VALUE mod)
{
return class_instance_method_list(argc, argv, mod, 0, ins_methods_priv_i);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#constants;F;7[[@90;[[@ i ;T;:constants;0; [ ; { ; IC; "Returns an array of the names of the constants accessible in
mod. This includes the names of constants in any included
modules (example at start of section), unless the inherit
parameter is set to false.
The implementation makes no guarantees about the order in which the
constants are yielded.
IO.constants.include?(:SYNC) #=> true
IO.constants(false).include?(:SYNC) #=> false
Also see Module#const_defined?.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" constants(inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@>;![ ;"I"@return [Array];T;#0;$@>;.F;Bi ;C0;7[[I" inherit;TI" true;T;$@>;![ ;"I"Returns an array of the names of the constants accessible in
mod. This includes the names of constants in any included
modules (example at start of section), unless the inherit
parameter is set to false.
The implementation makes no guarantees about the order in which the
constants are yielded.
IO.constants.include?(:SYNC) #=> true
IO.constants(false).include?(:SYNC) #=> false
Also see Module#const_defined?.
@overload constants(inherit=true)
@return [Array];T;#0;$@>;.F;/o;0;1T;2i ;3i ;%@A7;9I"VALUE
rb_mod_constants(int argc, const VALUE *argv, VALUE mod)
{
bool inherit = true;
if (rb_check_arity(argc, 0, 1)) inherit = RTEST(argv[0]);
if (inherit) {
return rb_const_list(rb_mod_const_of(mod, 0));
}
else {
return rb_local_constants(mod);
}
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#const_get;F;7[[@90;[[@mod.
If +inherit+ is set, the lookup will also search
the ancestors (and +Object+ if mod is a +Module+).
The value of the constant is returned if a definition is found,
otherwise a +NameError+ is raised.
Math.const_get(:PI) #=> 3.14159265358979
This method will recursively look up constant names if a namespaced
class name is provided. For example:
module Foo; class Bar; end end
Object.const_get 'Foo::Bar'
The +inherit+ flag is respected on each lookup. For example:
module Foo
class Bar
VAL = 10
end
class Baz < Bar; end
end
Object.const_get 'Foo::Baz::VAL' # => 10
Object.const_get 'Foo::Baz::VAL', false # => NameError
If the argument is not a valid constant name a +NameError+ will be
raised with a warning "wrong constant name".
Object.const_get 'foobar' #=> NameError: wrong constant name foobar
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"!const_get(sym, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@>;![ ;"I"@return [Object];T;#0;$@>;.F;Bi ;C0;7[[I"sym;T0[I" inherit;TI" true;T;$@>o;=
;>I"
overload;F;?0;;;@0;:I"!const_get(str, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@>;![ ;"I"@return [Object];T;#0;$@>;.F;Bi ;C0;7[[I"str;T0[I" inherit;TI" true;T;$@>;![ ;"I"Checks for a constant with the given name in mod.
If +inherit+ is set, the lookup will also search
the ancestors (and +Object+ if mod is a +Module+).
The value of the constant is returned if a definition is found,
otherwise a +NameError+ is raised.
Math.const_get(:PI) #=> 3.14159265358979
This method will recursively look up constant names if a namespaced
class name is provided. For example:
module Foo; class Bar; end end
Object.const_get 'Foo::Bar'
The +inherit+ flag is respected on each lookup. For example:
module Foo
class Bar
VAL = 10
end
class Baz < Bar; end
end
Object.const_get 'Foo::Baz::VAL' # => 10
Object.const_get 'Foo::Baz::VAL', false # => NameError
If the argument is not a valid constant name a +NameError+ will be
raised with a warning "wrong constant name".
Object.const_get 'foobar' #=> NameError: wrong constant name foobar
@overload const_get(sym, inherit=true)
@return [Object]
@overload const_get(str, inherit=true)
@return [Object];T;#0;$@>;.F;/o;0;1T;2i;3i;%@A7;9I"static VALUE
rb_mod_const_get(int argc, VALUE *argv, VALUE mod)
{
VALUE name, recur;
rb_encoding *enc;
const char *pbeg, *p, *path, *pend;
ID id;
rb_check_arity(argc, 1, 2);
name = argv[0];
recur = (argc == 1) ? Qtrue : argv[1];
if (SYMBOL_P(name)) {
if (!rb_is_const_sym(name)) goto wrong_name;
id = rb_check_id(&name);
if (!id) return rb_const_missing(mod, name);
return RTEST(recur) ? rb_const_get(mod, id) : rb_const_get_at(mod, id);
}
path = StringValuePtr(name);
enc = rb_enc_get(name);
if (!rb_enc_asciicompat(enc)) {
rb_raise(rb_eArgError, "invalid class path encoding (non ASCII)");
}
pbeg = p = path;
pend = path + RSTRING_LEN(name);
if (p >= pend || !*p) {
goto wrong_name;
}
if (p + 2 < pend && p[0] == ':' && p[1] == ':') {
mod = rb_cObject;
p += 2;
pbeg = p;
}
while (p < pend) {
VALUE part;
long len, beglen;
while (p < pend && *p != ':') p++;
if (pbeg == p) goto wrong_name;
id = rb_check_id_cstr(pbeg, len = p-pbeg, enc);
beglen = pbeg-path;
if (p < pend && p[0] == ':') {
if (p + 2 >= pend || p[1] != ':') goto wrong_name;
p += 2;
pbeg = p;
}
if (!RB_TYPE_P(mod, T_MODULE) && !RB_TYPE_P(mod, T_CLASS)) {
rb_raise(rb_eTypeError, "%"PRIsVALUE" does not refer to class/module",
QUOTE(name));
}
if (!id) {
part = rb_str_subseq(name, beglen, len);
OBJ_FREEZE(part);
if (!rb_is_const_name(part)) {
name = part;
goto wrong_name;
}
else if (!rb_method_basic_definition_p(CLASS_OF(mod), id_const_missing)) {
part = rb_str_intern(part);
mod = rb_const_missing(mod, part);
continue;
}
else {
rb_mod_const_missing(mod, part);
}
}
if (!rb_is_const_id(id)) {
name = ID2SYM(id);
goto wrong_name;
}
#if 0
mod = rb_const_get_0(mod, id, beglen > 0 || !RTEST(recur), RTEST(recur), FALSE);
#else
if (!RTEST(recur)) {
mod = rb_const_get_at(mod, id);
}
else if (beglen == 0) {
mod = rb_const_get(mod, id);
}
else {
mod = rb_const_get_from(mod, id);
}
#endif
}
return mod;
wrong_name:
rb_name_err_raise(wrong_constant_name, mod, name);
UNREACHABLE_RETURN(Qundef);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#const_set;F;7[[I" name;T0[I"
value;T0;[[@ 3.14285714285714
Math::HIGH_SCHOOL_PI - Math::PI #=> 0.00126448926734968
If +sym+ or +str+ is not a valid constant name a +NameError+ will be
raised with a warning "wrong constant name".
Object.const_set('foobar', 42) #=> NameError: wrong constant name foobar
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"const_set(sym, obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@>;![ ;"I"@return [Object];T;#0;$@>;.F;Bi ;C0;7[[I"sym;T0[I"obj;T0;$@>o;=
;>I"
overload;F;?0;;;@0;:I"const_set(str, obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@>;![ ;"I"@return [Object];T;#0;$@>;.F;Bi ;C0;7[[I"str;T0[I"obj;T0;$@>;![ ;"I"ASets the named constant to the given object, returning that object.
Creates a new constant if no constant with the given name previously
existed.
Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0) #=> 3.14285714285714
Math::HIGH_SCHOOL_PI - Math::PI #=> 0.00126448926734968
If +sym+ or +str+ is not a valid constant name a +NameError+ will be
raised with a warning "wrong constant name".
Object.const_set('foobar', 42) #=> NameError: wrong constant name foobar
@overload const_set(sym, obj)
@return [Object]
@overload const_set(str, obj)
@return [Object];T;#0;$@>;.F;/o;0;1T;2iK ;3i\ ;%@A7;9I"static VALUE
rb_mod_const_set(VALUE mod, VALUE name, VALUE value)
{
ID id = id_for_var(mod, name, const);
if (!id) id = rb_intern_str(name);
rb_const_set(mod, id, value);
return value;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#const_defined?;F;7[[@90;[[@ true, found in Float itself
Float.const_defined?("String") #=> true, found in Object (ancestor)
BasicObject.const_defined?(:Hash) #=> false
If _mod_ is a +Module+, additionally +Object+ and its ancestors are checked:
Math.const_defined?(:String) #=> true, found in Object
In each of the checked classes or modules, if the constant is not present
but there is an autoload for it, +true+ is returned directly without
autoloading:
module Admin
autoload :User, 'admin/user'
end
Admin.const_defined?(:User) #=> true
If the constant is not found the callback +const_missing+ is *not* called
and the method returns +false+.
If +inherit+ is false, the lookup only checks the constants in the receiver:
IO.const_defined?(:SYNC) #=> true, found in File::Constants (ancestor)
IO.const_defined?(:SYNC, false) #=> false, not found in IO itself
In this case, the same logic for autoloading applies.
If the argument is not a valid constant name a +NameError+ is raised with the
message "wrong constant name _name_":
Hash.const_defined? 'foobar' #=> NameError: wrong constant name foobar;T; [o;=
;>I"
overload;F;?0;;;@0;:I"&const_defined?(sym, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@ ?;![ ;"I"@return [Boolean];T;#0;$@ ?;.F;Bi ;C0;7[[I"sym;T0[I" inherit;TI" true;T;$@ ?o;=
;>I"
overload;F;?0;;;@0;:I"&const_defined?(str, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@ ?;![ ;"I"@return [Boolean];T;#0;$@ ?;.F;Bi ;C0;7[[I"str;T0[I" inherit;TI" true;T;$@ ?;![ ;"I"^Says whether _mod_ or its ancestors have a constant with the given name:
Float.const_defined?(:EPSILON) #=> true, found in Float itself
Float.const_defined?("String") #=> true, found in Object (ancestor)
BasicObject.const_defined?(:Hash) #=> false
If _mod_ is a +Module+, additionally +Object+ and its ancestors are checked:
Math.const_defined?(:String) #=> true, found in Object
In each of the checked classes or modules, if the constant is not present
but there is an autoload for it, +true+ is returned directly without
autoloading:
module Admin
autoload :User, 'admin/user'
end
Admin.const_defined?(:User) #=> true
If the constant is not found the callback +const_missing+ is *not* called
and the method returns +false+.
If +inherit+ is false, the lookup only checks the constants in the receiver:
IO.const_defined?(:SYNC) #=> true, found in File::Constants (ancestor)
IO.const_defined?(:SYNC, false) #=> false, not found in IO itself
In this case, the same logic for autoloading applies.
If the argument is not a valid constant name a +NameError+ is raised with the
message "wrong constant name _name_":
Hash.const_defined? 'foobar' #=> NameError: wrong constant name foobar
@overload const_defined?(sym, inherit=true)
@return [Boolean]
@overload const_defined?(str, inherit=true)
@return [Boolean];T;#0;$@ ?;.F;/o;0;1T;2ih ;3i ;Bi ;%@A7;9I" static VALUE
rb_mod_const_defined(int argc, VALUE *argv, VALUE mod)
{
VALUE name, recur;
rb_encoding *enc;
const char *pbeg, *p, *path, *pend;
ID id;
rb_check_arity(argc, 1, 2);
name = argv[0];
recur = (argc == 1) ? Qtrue : argv[1];
if (SYMBOL_P(name)) {
if (!rb_is_const_sym(name)) goto wrong_name;
id = rb_check_id(&name);
if (!id) return Qfalse;
return RTEST(recur) ? rb_const_defined(mod, id) : rb_const_defined_at(mod, id);
}
path = StringValuePtr(name);
enc = rb_enc_get(name);
if (!rb_enc_asciicompat(enc)) {
rb_raise(rb_eArgError, "invalid class path encoding (non ASCII)");
}
pbeg = p = path;
pend = path + RSTRING_LEN(name);
if (p >= pend || !*p) {
goto wrong_name;
}
if (p + 2 < pend && p[0] == ':' && p[1] == ':') {
mod = rb_cObject;
p += 2;
pbeg = p;
}
while (p < pend) {
VALUE part;
long len, beglen;
while (p < pend && *p != ':') p++;
if (pbeg == p) goto wrong_name;
id = rb_check_id_cstr(pbeg, len = p-pbeg, enc);
beglen = pbeg-path;
if (p < pend && p[0] == ':') {
if (p + 2 >= pend || p[1] != ':') goto wrong_name;
p += 2;
pbeg = p;
}
if (!id) {
part = rb_str_subseq(name, beglen, len);
OBJ_FREEZE(part);
if (!rb_is_const_name(part)) {
name = part;
goto wrong_name;
}
else {
return Qfalse;
}
}
if (!rb_is_const_id(id)) {
name = ID2SYM(id);
goto wrong_name;
}
#if 0
mod = rb_const_search(mod, id, beglen > 0 || !RTEST(recur), RTEST(recur), FALSE);
if (mod == Qundef) return Qfalse;
#else
if (!RTEST(recur)) {
if (!rb_const_defined_at(mod, id))
return Qfalse;
if (p == pend) return Qtrue;
mod = rb_const_get_at(mod, id);
}
else if (beglen == 0) {
if (!rb_const_defined(mod, id))
return Qfalse;
if (p == pend) return Qtrue;
mod = rb_const_get(mod, id);
}
else {
if (!rb_const_defined_from(mod, id))
return Qfalse;
if (p == pend) return Qtrue;
mod = rb_const_get_from(mod, id);
}
#endif
if (p < pend && !RB_TYPE_P(mod, T_MODULE) && !RB_TYPE_P(mod, T_CLASS)) {
rb_raise(rb_eTypeError, "%"PRIsVALUE" does not refer to class/module",
QUOTE(name));
}
}
return Qtrue;
wrong_name:
rb_name_err_raise(wrong_constant_name, mod, name);
UNREACHABLE_RETURN(Qundef);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"!Module#const_source_location;F;7[[@90;[[@mod.ancestors (+true+
by default).
# test.rb:
class A # line 1
C1 = 1
C2 = 2
end
module M # line 6
C3 = 3
end
class B < A # line 10
include M
C4 = 4
end
class A # continuation of A definition
C2 = 8 # constant redefinition; warned yet allowed
end
p B.const_source_location('C4') # => ["test.rb", 12]
p B.const_source_location('C3') # => ["test.rb", 7]
p B.const_source_location('C1') # => ["test.rb", 2]
p B.const_source_location('C3', false) # => nil -- don't lookup in ancestors
p A.const_source_location('C2') # => ["test.rb", 16] -- actual (last) definition place
p Object.const_source_location('B') # => ["test.rb", 10] -- top-level constant could be looked through Object
p Object.const_source_location('A') # => ["test.rb", 1] -- class reopening is NOT considered new definition
p B.const_source_location('A') # => ["test.rb", 1] -- because Object is in ancestors
p M.const_source_location('A') # => ["test.rb", 1] -- Object is not ancestor, but additionally checked for modules
p Object.const_source_location('A::C1') # => ["test.rb", 2] -- nesting is supported
p Object.const_source_location('String') # => [] -- constant is defined in C code
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"-const_source_location(sym, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I"];T;0;@[I"
Array;TI" Integer;T;$@R?;![ ;"I" @return [Array, Integer]];T;#0;$@R?;.F;Bi ;C0;7[[I"sym;T0[I" inherit;TI" true;T;$@R?o;=
;>I"
overload;F;?0;;;@0;:I"-const_source_location(str, inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I"];T;0;@[I"
Array;TI" Integer;T;$@R?;![ ;"I" @return [Array, Integer]];T;#0;$@R?;.F;Bi ;C0;7[[I"str;T0[I" inherit;TI" true;T;$@R?;![ ;"I"^Returns the Ruby source filename and line number containing the definition
of the constant specified. If the named constant is not found, +nil+ is returned.
If the constant is found, but its source location can not be extracted
(constant is defined in C code), empty array is returned.
_inherit_ specifies whether to lookup in mod.ancestors (+true+
by default).
# test.rb:
class A # line 1
C1 = 1
C2 = 2
end
module M # line 6
C3 = 3
end
class B < A # line 10
include M
C4 = 4
end
class A # continuation of A definition
C2 = 8 # constant redefinition; warned yet allowed
end
p B.const_source_location('C4') # => ["test.rb", 12]
p B.const_source_location('C3') # => ["test.rb", 7]
p B.const_source_location('C1') # => ["test.rb", 2]
p B.const_source_location('C3', false) # => nil -- don't lookup in ancestors
p A.const_source_location('C2') # => ["test.rb", 16] -- actual (last) definition place
p Object.const_source_location('B') # => ["test.rb", 10] -- top-level constant could be looked through Object
p Object.const_source_location('A') # => ["test.rb", 1] -- class reopening is NOT considered new definition
p B.const_source_location('A') # => ["test.rb", 1] -- because Object is in ancestors
p M.const_source_location('A') # => ["test.rb", 1] -- Object is not ancestor, but additionally checked for modules
p Object.const_source_location('A::C1') # => ["test.rb", 2] -- nesting is supported
p Object.const_source_location('String') # => [] -- constant is defined in C code
@overload const_source_location(sym, inherit=true)
@return [Array, Integer]]
@overload const_source_location(str, inherit=true)
@return [Array, Integer]];T;#0;$@R?;.F;/o;0;1T;2i ;3i0
;%@A7;9I" static VALUE
rb_mod_const_source_location(int argc, VALUE *argv, VALUE mod)
{
VALUE name, recur, loc = Qnil;
rb_encoding *enc;
const char *pbeg, *p, *path, *pend;
ID id;
rb_check_arity(argc, 1, 2);
name = argv[0];
recur = (argc == 1) ? Qtrue : argv[1];
if (SYMBOL_P(name)) {
if (!rb_is_const_sym(name)) goto wrong_name;
id = rb_check_id(&name);
if (!id) return Qnil;
return RTEST(recur) ? rb_const_source_location(mod, id) : rb_const_source_location_at(mod, id);
}
path = StringValuePtr(name);
enc = rb_enc_get(name);
if (!rb_enc_asciicompat(enc)) {
rb_raise(rb_eArgError, "invalid class path encoding (non ASCII)");
}
pbeg = p = path;
pend = path + RSTRING_LEN(name);
if (p >= pend || !*p) {
goto wrong_name;
}
if (p + 2 < pend && p[0] == ':' && p[1] == ':') {
mod = rb_cObject;
p += 2;
pbeg = p;
}
while (p < pend) {
VALUE part;
long len, beglen;
while (p < pend && *p != ':') p++;
if (pbeg == p) goto wrong_name;
id = rb_check_id_cstr(pbeg, len = p-pbeg, enc);
beglen = pbeg-path;
if (p < pend && p[0] == ':') {
if (p + 2 >= pend || p[1] != ':') goto wrong_name;
p += 2;
pbeg = p;
}
if (!id) {
part = rb_str_subseq(name, beglen, len);
OBJ_FREEZE(part);
if (!rb_is_const_name(part)) {
name = part;
goto wrong_name;
}
else {
return Qnil;
}
}
if (!rb_is_const_id(id)) {
name = ID2SYM(id);
goto wrong_name;
}
if (p < pend) {
if (RTEST(recur)) {
mod = rb_const_get(mod, id);
}
else {
mod = rb_const_get_at(mod, id);
}
if (!RB_TYPE_P(mod, T_MODULE) && !RB_TYPE_P(mod, T_CLASS)) {
rb_raise(rb_eTypeError, "%"PRIsVALUE" does not refer to class/module",
QUOTE(name));
}
}
else {
if (RTEST(recur)) {
loc = rb_const_source_location(mod, id);
}
else {
loc = rb_const_source_location_at(mod, id);
}
break;
}
recur = Qfalse;
}
return loc;
wrong_name:
rb_name_err_raise(wrong_constant_name, mod, name);
UNREACHABLE_RETURN(Qundef);
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I"Module#remove_const;F;7[[I" name;T0;[[@ i ;T;:remove_const;0; [ ; { ; IC; "Removes the definition of the given constant, returning that
constant's previous value. If that constant referred to
a module, this will not change that module's name and can lead
to confusion.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"remove_const(sym);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@?;![ ;"I"@return [Object];T;#0;$@?;.F;Bi ;C0;7[[I"sym;T0;$@?;![ ;"I"Removes the definition of the given constant, returning that
constant's previous value. If that constant referred to
a module, this will not change that module's name and can lead
to confusion.
@overload remove_const(sym)
@return [Object];T;#0;$@?;.F;/o;0;1T;2i
;3i ;%@A7;9I"VALUE
rb_mod_remove_const(VALUE mod, VALUE name)
{
const ID id = id_for_var(mod, name, a, constant);
if (!id) {
undefined_constant(mod, name);
}
return rb_const_remove(mod, id);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#const_missing;F;7[[I" name;T0;[[@ i;T;:const_missing;0; [ ; { ; IC; "Invoked when a reference is made to an undefined constant in
mod. It is passed a symbol for the undefined constant, and
returns a value to be used for that constant. The
following code is an example of the same:
def Foo.const_missing(name)
name # return the constant name as Symbol
end
Foo::UNDEFINED_CONST #=> :UNDEFINED_CONST: symbol returned
In the next example when a reference is made to an undefined constant,
it attempts to load a file whose name is the lowercase version of the
constant (thus class Fred is assumed to be in file
fred.rb). If found, it returns the loaded class. It
therefore implements an autoload feature similar to Kernel#autoload and
Module#autoload.
def Object.const_missing(name)
@looked_for ||= {}
str_name = name.to_s
raise "Class not found: #{name}" if @looked_for[str_name]
@looked_for[str_name] = 1
file = str_name.downcase
require file
klass = const_get(name)
return klass if klass
raise "Class not found: #{name}"
end
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"const_missing(sym);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@?;![ ;"I"@return [Object];T;#0;$@?;.F;Bi ;C0;7[[I"sym;T0;$@?;![ ;"I"GInvoked when a reference is made to an undefined constant in
mod. It is passed a symbol for the undefined constant, and
returns a value to be used for that constant. The
following code is an example of the same:
def Foo.const_missing(name)
name # return the constant name as Symbol
end
Foo::UNDEFINED_CONST #=> :UNDEFINED_CONST: symbol returned
In the next example when a reference is made to an undefined constant,
it attempts to load a file whose name is the lowercase version of the
constant (thus class Fred is assumed to be in file
fred.rb). If found, it returns the loaded class. It
therefore implements an autoload feature similar to Kernel#autoload and
Module#autoload.
def Object.const_missing(name)
@looked_for ||= {}
str_name = name.to_s
raise "Class not found: #{name}" if @looked_for[str_name]
@looked_for[str_name] = 1
file = str_name.downcase
require file
klass = const_get(name)
return klass if klass
raise "Class not found: #{name}"
end
@overload const_missing(sym)
@return [Object];T;#0;$@?;.F;/o;0;1T;2i;3i;%@A7;9I"2VALUE
rb_mod_const_missing(VALUE klass, VALUE name)
{
VALUE ref = GET_EC()->private_const_reference;
rb_vm_pop_cfunc_frame();
if (ref) {
rb_name_err_raise("private constant %2$s::%1$s referenced",
ref, name);
}
uninitialized_constant(klass, name);
UNREACHABLE_RETURN(Qnil);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"Module#class_variables;F;7[[@90;[[@ if;T;:class_variables;0; [ ; { ; IC; "Returns an array of the names of class variables in mod.
This includes the names of class variables in any included
modules, unless the inherit parameter is set to
false.
class One
@@var1 = 1
end
class Two < One
@@var2 = 2
end
One.class_variables #=> [:@@var1]
Two.class_variables #=> [:@@var2, :@@var1]
Two.class_variables(false) #=> [:@@var2]
;T; [o;=
;>I"
overload;F;?0;;;@0;:I""class_variables(inherit=true);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@?;![ ;"I"@return [Array];T;#0;$@?;.F;Bi ;C0;7[[I" inherit;TI" true;T;$@?;![ ;"I"Returns an array of the names of class variables in mod.
This includes the names of class variables in any included
modules, unless the inherit parameter is set to
false.
class One
@@var1 = 1
end
class Two < One
@@var2 = 2
end
One.class_variables #=> [:@@var1]
Two.class_variables #=> [:@@var2, :@@var1]
Two.class_variables(false) #=> [:@@var2]
@overload class_variables(inherit=true)
@return [Array];T;#0;$@?;.F;/o;0;1T;2iR;3ic;%@A7;9I"0VALUE
rb_mod_class_variables(int argc, const VALUE *argv, VALUE mod)
{
bool inherit = true;
st_table *tbl;
if (rb_check_arity(argc, 0, 1)) inherit = RTEST(argv[0]);
if (inherit) {
tbl = mod_cvar_of(mod, 0);
}
else {
tbl = mod_cvar_at(mod, 0);
}
return cvar_list(tbl);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"!Module#remove_class_variable;F;7[[I" name;T0;[[@ i;T;:remove_class_variable;0; [ ; { ; IC; "Removes the named class variable from the receiver, returning that
variable's value.
class Example
@@var = 99
puts remove_class_variable(:@@var)
p(defined? @@var)
end
produces:
99
nil
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" remove_class_variable(sym);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@?;![ ;"I"@return [Object];T;#0;$@?;.F;Bi ;C0;7[[I"sym;T0;$@?;![ ;"I"Removes the named class variable from the receiver, returning that
variable's value.
class Example
@@var = 99
puts remove_class_variable(:@@var)
p(defined? @@var)
end
produces:
99
nil
@overload remove_class_variable(sym)
@return [Object];T;#0;$@?;.F;/o;0;1T;2iv;3i;%@A7;9I"VVALUE
rb_mod_remove_cvar(VALUE mod, VALUE name)
{
const ID id = id_for_var_message(mod, name, class, "wrong class variable name %1$s");
st_data_t val, n = id;
if (!id) {
goto not_defined;
}
rb_check_frozen(mod);
if (RCLASS_IV_TBL(mod) && st_delete(RCLASS_IV_TBL(mod), &n, &val)) {
return (VALUE)val;
}
if (rb_cvar_defined(mod, id)) {
rb_name_err_raise("cannot remove %1$s for %2$s", mod, ID2SYM(id));
}
not_defined:
rb_name_err_raise("class variable %1$s not defined for %2$s",
mod, name);
UNREACHABLE_RETURN(Qundef);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" Module#class_variable_get;F;7[[I"iv;T0;[[@@@ part of the
variable name should be included for regular class variables.
String arguments are converted to symbols.
class Fred
@@foo = 99
end
Fred.class_variable_get(:@@foo) #=> 99
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" class_variable_get(symbol);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@@;![ ;"I"@return [Object];T;#0;$@@;.F;Bi ;C0;7[[I" symbol;T0;$@@o;=
;>I"
overload;F;?0;;;@0;:I" class_variable_get(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@@;![ ;"I"@return [Object];T;#0;$@@;.F;Bi ;C0;7[[I" string;T0;$@@;![ ;"I"Returns the value of the given class variable (or throws a
NameError exception). The @@ part of the
variable name should be included for regular class variables.
String arguments are converted to symbols.
class Fred
@@foo = 99
end
Fred.class_variable_get(:@@foo) #=> 99
@overload class_variable_get(symbol)
@return [Object]
@overload class_variable_get(string)
@return [Object];T;#0;$@@;.F;/o;0;1T;2i
;3i ;%@A7;9I"static VALUE
rb_mod_cvar_get(VALUE obj, VALUE iv)
{
ID id = id_for_var(obj, iv, class);
if (!id) {
rb_name_err_raise("uninitialized class variable %1$s in %2$s",
obj, iv);
}
return rb_cvar_get(obj, id);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Module#class_variable_set;F;7[[I"iv;T0[I"val;T0;[[@symbol to the given
object.
If the class variable name is passed as a string, that string
is converted to a symbol.
class Fred
@@foo = 99
def foo
@@foo
end
end
Fred.class_variable_set(:@@foo, 101) #=> 101
Fred.new.foo #=> 101
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"$class_variable_set(symbol, obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@1@;![ ;"I"@return [Object];T;#0;$@1@;.F;Bi ;C0;7[[I" symbol;T0[I"obj;T0;$@1@o;=
;>I"
overload;F;?0;;;@0;:I"$class_variable_set(string, obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@1@;![ ;"I"@return [Object];T;#0;$@1@;.F;Bi ;C0;7[[I" string;T0[I"obj;T0;$@1@;![ ;"I"Sets the class variable named by symbol to the given
object.
If the class variable name is passed as a string, that string
is converted to a symbol.
class Fred
@@foo = 99
def foo
@@foo
end
end
Fred.class_variable_set(:@@foo, 101) #=> 101
Fred.new.foo #=> 101
@overload class_variable_set(symbol, obj)
@return [Object]
@overload class_variable_set(string, obj)
@return [Object];T;#0;$@1@;.F;/o;0;1T;2i ;3i$ ;%@A7;9I"static VALUE
rb_mod_cvar_set(VALUE obj, VALUE iv, VALUE val)
{
ID id = id_for_var(obj, iv, class);
if (!id) id = rb_intern_str(iv);
rb_cvar_set(obj, id, val);
return val;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"#Module#class_variable_defined?;F;7[[I"iv;T0;[[@true if the given class variable is defined
in obj.
String arguments are converted to symbols.
class Fred
@@foo = 99
end
Fred.class_variable_defined?(:@@foo) #=> true
Fred.class_variable_defined?(:@@bar) #=> false;T; [o;=
;>I"
overload;F;?0;; ;@0;:I"$class_variable_defined?(symbol);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@e@;![ ;"I"@return [Boolean];T;#0;$@e@;.F;Bi ;C0;7[[I" symbol;T0;$@e@o;=
;>I"
overload;F;?0;; ;@0;:I"$class_variable_defined?(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@e@;![ ;"I"@return [Boolean];T;#0;$@e@;.F;Bi ;C0;7[[I" string;T0;$@e@;![ ;"I"Returns true if the given class variable is defined
in obj.
String arguments are converted to symbols.
class Fred
@@foo = 99
end
Fred.class_variable_defined?(:@@foo) #=> true
Fred.class_variable_defined?(:@@bar) #=> false
@overload class_variable_defined?(symbol)
@return [Boolean]
@overload class_variable_defined?(string)
@return [Boolean];T;#0;$@e@;.F;/o;0;1T;2i/ ;3i= ;Bi ;%@A7;9I"static VALUE
rb_mod_cvar_defined(VALUE obj, VALUE iv)
{
ID id = id_for_var(obj, iv, class);
if (!id) {
return Qfalse;
}
return rb_cvar_defined(obj, id);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#public_constant;F;7[[@90;[[@ i
;T;:public_constant;0; [ ; { ; IC; "/Makes a list of existing constants public.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"!public_constant(symbol, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@@;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@@;![ ;"I"XMakes a list of existing constants public.
@overload public_constant(symbol, ...);T;#0;$@@;.F;/o;0;1T;2i
;3i
;%@A7;9I"VALUE
rb_mod_public_constant(int argc, const VALUE *argv, VALUE obj)
{
set_const_visibility(obj, argc, argv, CONST_PUBLIC, CONST_VISIBILITY_MASK);
return obj;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" Module#private_constant;F;7[[@90;[[@ i
;T;:private_constant;0; [ ; { ; IC; "0Makes a list of existing constants private.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I""private_constant(symbol, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@@;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@@;![ ;"I"ZMakes a list of existing constants private.
@overload private_constant(symbol, ...);T;#0;$@@;.F;/o;0;1T;2i
;3i
;%@A7;9I"VALUE
rb_mod_private_constant(int argc, const VALUE *argv, VALUE obj)
{
set_const_visibility(obj, argc, argv, CONST_PRIVATE, CONST_VISIBILITY_MASK);
return obj;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" Module#deprecate_constant;F;7[[@90;[[@ i7
;T;:deprecate_constant;0; [ ; { ; IC; "LMakes a list of existing constants deprecated. Attempt
to refer to them will produce a warning.
module HTTP
NotFound = Exception.new
NOT_FOUND = NotFound # previous version of the library used this name
deprecate_constant :NOT_FOUND
end
HTTP::NOT_FOUND
# warning: constant HTTP::NOT_FOUND is deprecated
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"$deprecate_constant(symbol, ...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@@;.F;Bi ;C0;7[[I" symbol;T0[I"...;T0;$@@;![ ;"I"yMakes a list of existing constants deprecated. Attempt
to refer to them will produce a warning.
module HTTP
NotFound = Exception.new
NOT_FOUND = NotFound # previous version of the library used this name
deprecate_constant :NOT_FOUND
end
HTTP::NOT_FOUND
# warning: constant HTTP::NOT_FOUND is deprecated
@overload deprecate_constant(symbol, ...);T;#0;$@@;.F;/o;0;1T;2i$
;3i3
;%@A7;9I"VALUE
rb_mod_deprecate_constant(int argc, const VALUE *argv, VALUE obj)
{
set_const_visibility(obj, argc, argv, CONST_DEPRECATED, CONST_DEPRECATED);
return obj;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" Module#singleton_class?;F;7[ ;[[@true if mod is a singleton class or
false if it is an ordinary class or module.
class C
end
C.singleton_class? #=> false
C.singleton_class.singleton_class? #=> true;T; [o;=
;>I"
overload;F;?0;;;@0;:I"singleton_class?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@@;![ ;"I"@return [Boolean];T;#0;$@@;.F;Bi ;C0;7[ ;$@@;![ ;"I" Returns true if mod is a singleton class or
false if it is an ordinary class or module.
class C
end
C.singleton_class? #=> false
C.singleton_class.singleton_class? #=> true
@overload singleton_class?
@return [Boolean];T;#0;$@@;.F;/o;0;1T;2iJ ;3iT ;Bi ;%@A7;9I"}static VALUE
rb_mod_singleton_p(VALUE klass)
{
return RBOOL(RB_TYPE_P(klass, T_CLASS) && FL_TEST(klass, FL_SINGLETON));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#module_exec;F;7[[@90;[[@Ciu;T;:module_exec;0; [ ; { ; IC; "Evaluates the given block in the context of the class/module.
The method defined in the block will belong to the receiver.
Any arguments passed to the method will be passed to the block.
This can be used if the block needs to access instance variables.
class Thing
end
Thing.class_exec{
def hello() "Hello there!" end
}
puts Thing.new.hello()
produces:
Hello there!
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"module_exec(arg...);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" var...;T;$@@o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@@;![ ;"I"%@yield [var...]
@return [Object];T;#0;$@@;.F;Bi ;C0;7[[I" arg...;T0;$@@o;=
;>I"
overload;F;?0;:class_exec;@0;:I"class_exec(arg...);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" var...;T;$@@o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@@;![ ;"I"%@yield [var...]
@return [Object];T;#0;$@@;.F;Bi ;C0;7[[I" arg...;T0;$@@;![ ;"I"Evaluates the given block in the context of the class/module.
The method defined in the block will belong to the receiver.
Any arguments passed to the method will be passed to the block.
This can be used if the block needs to access instance variables.
class Thing
end
Thing.class_exec{
def hello() "Hello there!" end
}
puts Thing.new.hello()
produces:
Hello there!
@overload module_exec(arg...)
@yield [var...]
@return [Object]
@overload class_exec(arg...)
@yield [var...]
@return [Object];T;#0;$@@;.F;/o;0;1T;2i_;3iu;%@A7;9I"static VALUE
rb_mod_module_exec_internal(int argc, const VALUE *argv, VALUE mod)
{
return yield_under(mod, FALSE, argc, argv, RB_PASS_CALLED_KEYWORDS);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#class_exec;F;7[[@90;[[@Ciu;T;;;0; [ ; { ; IC; "Evaluates the given block in the context of the class/module.
The method defined in the block will belong to the receiver.
Any arguments passed to the method will be passed to the block.
This can be used if the block needs to access instance variables.
class Thing
end
Thing.class_exec{
def hello() "Hello there!" end
}
puts Thing.new.hello()
produces:
Hello there!
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"module_exec(arg...);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" var...;T;$@6Ao;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@6A;![ ;"I"%@yield [var...]
@return [Object];T;#0;$@6A;.F;Bi ;C0;7[[I" arg...;T0;$@6Ao;=
;>I"
overload;F;?0;;;@0;:I"class_exec(arg...);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" var...;T;$@6Ao;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@6A;![ ;"I"%@yield [var...]
@return [Object];T;#0;$@6A;.F;Bi ;C0;7[[I" arg...;T0;$@6A;![ ;"@2A;#0;$@6A;.F;/o;0;1T;2i_;3iu;%@A7;9I"static VALUE
rb_mod_module_exec_internal(int argc, const VALUE *argv, VALUE mod)
{
return yield_under(mod, FALSE, argc, argv, RB_PASS_CALLED_KEYWORDS);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#module_eval;F;7[[@90;[[@CiS;T;:module_eval;0; [ ; { ; IC; "yEvaluates the string or block in the context of _mod_, except that when
a block is given, constant/class variable lookup is not affected. This
can be used to add methods to a class. module_eval returns
the result of evaluating its argument. The optional _filename_ and
_lineno_ parameters set the text for error messages.
class Thing
end
a = %q{def hello() "Hello there!" end}
Thing.module_eval(a)
puts Thing.new.hello()
Thing.module_eval("invalid code", "dummy", 123)
produces:
Hello there!
dummy:123:in `module_eval': undefined local variable
or method `code' for Thing:Class
;T; [ o;=
;>I"
overload;F;?0;:class_eval;@0;:I"/class_eval(string [, filename [, lineno]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@lA;![ ;"I"@return [Object];T;#0;$@lA;.F;Bi ;C0;7[[I""string[, filename [, lineno]];T0;$@lAo;=
;>I"
overload;F;?0;;;@0;:I"class_eval;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"mod;T;$@lAo;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@lA;![ ;"I""@yield [mod]
@return [Object];T;#0;$@lA;.F;Bi ;C0;7[ ;$@lAo;=
;>I"
overload;F;?0;;;@0;:I"0module_eval(string [, filename [, lineno]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@lA;![ ;"I"@return [Object];T;#0;$@lA;.F;Bi ;C0;7[[I""string[, filename [, lineno]];T0;$@lAo;=
;>I"
overload;F;?0;;;@0;:I"module_eval;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"mod;T;$@lAo;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@lA;![ ;"I""@yield [mod]
@return [Object];T;#0;$@lA;.F;Bi ;C0;7[ ;$@lA;![ ;"I"{Evaluates the string or block in the context of _mod_, except that when
a block is given, constant/class variable lookup is not affected. This
can be used to add methods to a class. module_eval returns
the result of evaluating its argument. The optional _filename_ and
_lineno_ parameters set the text for error messages.
class Thing
end
a = %q{def hello() "Hello there!" end}
Thing.module_eval(a)
puts Thing.new.hello()
Thing.module_eval("invalid code", "dummy", 123)
produces:
Hello there!
dummy:123:in `module_eval': undefined local variable
or method `code' for Thing:Class
@overload class_eval(string [, filename [, lineno]])
@return [Object]
@overload class_eval
@yield [mod]
@return [Object]
@overload module_eval(string [, filename [, lineno]])
@return [Object]
@overload module_eval
@yield [mod]
@return [Object];T;#0;$@lA;.F;/o;0;1T;2i8;3iU;%@A7;9I"static VALUE
rb_mod_module_eval_internal(int argc, const VALUE *argv, VALUE mod)
{
return specific_eval(argc, argv, mod, FALSE, RB_PASS_CALLED_KEYWORDS);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#class_eval;F;7[[@90;[[@CiS;T;;;0; [ ; { ; IC; "yEvaluates the string or block in the context of _mod_, except that when
a block is given, constant/class variable lookup is not affected. This
can be used to add methods to a class. module_eval returns
the result of evaluating its argument. The optional _filename_ and
_lineno_ parameters set the text for error messages.
class Thing
end
a = %q{def hello() "Hello there!" end}
Thing.module_eval(a)
puts Thing.new.hello()
Thing.module_eval("invalid code", "dummy", 123)
produces:
Hello there!
dummy:123:in `module_eval': undefined local variable
or method `code' for Thing:Class
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I"/class_eval(string [, filename [, lineno]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@A;![ ;"I"@return [Object];T;#0;$@A;.F;Bi ;C0;7[[I""string[, filename [, lineno]];T0;$@Ao;=
;>I"
overload;F;?0;;;@0;:I"class_eval;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"mod;T;$@Ao;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@A;![ ;"I""@yield [mod]
@return [Object];T;#0;$@A;.F;Bi ;C0;7[ ;$@Ao;=
;>I"
overload;F;?0;;;@0;:I"0module_eval(string [, filename [, lineno]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@A;![ ;"I"@return [Object];T;#0;$@A;.F;Bi ;C0;7[[I""string[, filename [, lineno]];T0;$@Ao;=
;>I"
overload;F;?0;;;@0;:I"module_eval;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"mod;T;$@Ao;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@A;![ ;"I""@yield [mod]
@return [Object];T;#0;$@A;.F;Bi ;C0;7[ ;$@A;![ ;"@A;#0;$@A;.F;/o;0;1T;2i8;3iU;%@A7;9I"static VALUE
rb_mod_module_eval_internal(int argc, const VALUE *argv, VALUE mod)
{
return specific_eval(argc, argv, mod, FALSE, RB_PASS_CALLED_KEYWORDS);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#instance_method;F;7[[I"vid;T0;[[@i=;T;:instance_method;0; [ ; { ; IC; "}Returns an +UnboundMethod+ representing the given
instance method in _mod_.
class Interpreter
def do_a() print "there, "; end
def do_d() print "Hello "; end
def do_e() print "!\n"; end
def do_v() print "Dave"; end
Dispatcher = {
"a" => instance_method(:do_a),
"d" => instance_method(:do_d),
"e" => instance_method(:do_e),
"v" => instance_method(:do_v)
}
def interpret(string)
string.each_char {|b| Dispatcher[b].bind(self).call }
end
end
interpreter = Interpreter.new
interpreter.interpret('dave')
produces:
Hello there, Dave!
;T; [o;=
;>I"
overload;F;?0;; ;@0;:I" instance_method(symbol);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@
B;.F;Bi ;C0;7[[I" symbol;T0;$@
B;![ ;"I"Returns an +UnboundMethod+ representing the given
instance method in _mod_.
class Interpreter
def do_a() print "there, "; end
def do_d() print "Hello "; end
def do_e() print "!\n"; end
def do_v() print "Dave"; end
Dispatcher = {
"a" => instance_method(:do_a),
"d" => instance_method(:do_d),
"e" => instance_method(:do_e),
"v" => instance_method(:do_v)
}
def interpret(string)
string.each_char {|b| Dispatcher[b].bind(self).call }
end
end
interpreter = Interpreter.new
interpreter.interpret('dave')
produces:
Hello there, Dave!
@overload instance_method(symbol);T;#0;$@
B;.F;/o;0;1T;2i ;3i9;%@A7;9I"static VALUE
rb_mod_instance_method(VALUE mod, VALUE vid)
{
ID id = rb_check_id(&vid);
if (!id) {
rb_method_name_error(mod, vid);
}
return mnew_unbound(mod, id, rb_cUnboundMethod, FALSE);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I""Module#public_instance_method;F;7[[I"vid;T0;[[@iN;T;:public_instance_method;0; [ ; { ; IC; "?Similar to _instance_method_, searches public method only.
;T; [o;=
;>I"
overload;F;?0;;
;@0;:I"#public_instance_method(symbol);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@'B;.F;Bi ;C0;7[[I" symbol;T0;$@'B;![ ;"I"jSimilar to _instance_method_, searches public method only.
@overload public_instance_method(symbol);T;#0;$@'B;.F;/o;0;1T;2iG;3iJ;%@A7;9I"static VALUE
rb_mod_public_instance_method(VALUE mod, VALUE vid)
{
ID id = rb_check_id(&vid);
if (!id) {
rb_method_name_error(mod, vid);
}
return mnew_unbound(mod, id, rb_cUnboundMethod, TRUE);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Module#define_method;F;7[[@90;[[@i;T;:define_method;0; [ ; { ; IC; "?Defines an instance method in the receiver. The _method_
parameter can be a +Proc+, a +Method+ or an +UnboundMethod+ object.
If a block is specified, it is used as the method body.
If a block or the _method_ parameter has parameters,
they're used as method parameters.
This block is evaluated using #instance_eval.
class A
def fred
puts "In Fred"
end
def create_method(name, &block)
self.class.define_method(name, &block)
end
define_method(:wilma) { puts "Charge it!" }
define_method(:flint) {|name| puts "I'm #{name}!"}
end
class B < A
define_method(:barney, instance_method(:fred))
end
a = B.new
a.barney
a.wilma
a.flint('Dino')
a.create_method(:betty) { p self }
a.betty
produces:
In Fred
Charge it!
I'm Dino!
#:name).
module Mod
include Math
CONST = 1
def meth
# ...
end
end
Mod.class #=> Module
Mod.constants #=> [:CONST, :PI, :E]
Mod.instance_methods #=> [:meth];T; [ ;![ ;"I"H*********************************************************************
A Module is a collection of methods and constants. The
methods in a module may be instance methods or module methods.
Instance methods appear as methods in a class when the module is
included, module methods do not. Conversely, module methods may be
called without creating an encapsulating object, while instance
methods may not. (See Module#module_function.)
In the descriptions that follow, the parameter sym refers
to a symbol, which is either a quoted string or a
Symbol (such as :name).
module Mod
include Math
CONST = 1
def meth
# ...
end
end
Mod.class #=> Module
Mod.constants #=> [:CONST, :PI, :E]
Mod.instance_methods #=> [:meth]
;T;#0;$@A7;.F;/o;0;1T;2i;3i(;Bi ;%@;&I" Module;F;'@o;;IC;[o;4;5F;6;;;;&I" NKF#nkf;F;7[[I"opt;T0[I"src;T0;[[I"ext/nkf/nkf.c;Ti;T;:nkf;0; [ ; { ; IC; "Convert _str_ and return converted result.
Conversion details are specified by _opt_ as String.
require 'nkf'
output = NKF.nkf("-s", input)
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"nkf(opt, str);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@C;![ ;"I"@return [String];T;#0;$@C;.F;Bi ;C0;7[[I"opt;T0[I"str;T0;$@C;![ ;"I"Convert _str_ and return converted result.
Conversion details are specified by _opt_ as String.
require 'nkf'
output = NKF.nkf("-s", input)
@overload nkf(opt, str)
@return [String];T;#0;$@C;.F;C0;%@C;9I"static VALUE
rb_nkf_convert(VALUE obj, VALUE opt, VALUE src)
{
VALUE tmp;
reinit();
nkf_split_options(StringValueCStr(opt));
if (!output_encoding) rb_raise(rb_eArgError, "no output encoding given");
switch (nkf_enc_to_index(output_encoding)) {
case UTF_8_BOM: output_encoding = nkf_enc_from_index(UTF_8); break;
case UTF_16BE_BOM: output_encoding = nkf_enc_from_index(UTF_16BE); break;
case UTF_16LE_BOM: output_encoding = nkf_enc_from_index(UTF_16LE); break;
case UTF_32BE_BOM: output_encoding = nkf_enc_from_index(UTF_32BE); break;
case UTF_32LE_BOM: output_encoding = nkf_enc_from_index(UTF_32LE); break;
}
output_bom_f = FALSE;
incsize = INCSIZE;
input_ctr = 0;
input = (unsigned char *)StringValuePtr(src);
i_len = RSTRING_LENINT(src);
tmp = rb_str_new(0, i_len*3 + 10);
output_ctr = 0;
output = (unsigned char *)RSTRING_PTR(tmp);
o_len = RSTRING_LENINT(tmp);
*output = '\0';
/* use _result_ begin*/
result = tmp;
kanji_convert(NULL);
result = Qnil;
/* use _result_ end */
rb_str_set_len(tmp, output_ctr);
if (mimeout_f)
rb_enc_associate(tmp, rb_usascii_encoding());
else
rb_enc_associate(tmp, rb_nkf_enc_get(nkf_enc_name(output_encoding)));
return tmp;
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I" NKF.nkf;F;7@C;@ C;T;;;0; @C; { ; IC; "Convert _str_ and return converted result.
Conversion details are specified by _opt_ as String.
require 'nkf'
output = NKF.nkf("-s", input);T; [o;=
;>I"
overload;F;?0;;;@0;:I"nkf(opt, str);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@(C;![ ;"I"@return [String];T;#0;$@(C;.F;Bi ;C0;7[[I"opt;T0[I"str;T0;$@(C;![ ;"I"Convert _str_ and return converted result.
Conversion details are specified by _opt_ as String.
require 'nkf'
output = NKF.nkf("-s", input)
@overload nkf(opt, str)
@return [String];T;#0;$@(C;.F;/o;0;1T;2i|;3i;Bi ;%@C;9@&C;:@'C;;To;4;5F;6;;;;&I"NKF#guess;F;7[[I"src;T0;[[@Ci;T;:
guess;0; [ ; { ; IC; "6Returns guessed encoding of _str_ by nkf routine.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"guess(str);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Encoding;T;$@AC;![ ;"I"@return [Encoding];T;#0;$@AC;.F;Bi ;C0;7[[I"str;T0;$@AC;![ ;"I"aReturns guessed encoding of _str_ by nkf routine.
@overload guess(str)
@return [Encoding];T;#0;$@AC;.F;C0;%@C;9I"3static VALUE
rb_nkf_guess(VALUE obj, VALUE src)
{
reinit();
input_ctr = 0;
input = (unsigned char *)StringValuePtr(src);
i_len = RSTRING_LENINT(src);
guess_f = TRUE;
kanji_convert( NULL );
guess_f = FALSE;
return rb_enc_from_encoding(rb_nkf_enc_get(get_guessed_code()));
};T;:I"static VALUE;T;;To;4;5T;6;;; ;&I"NKF.guess;F;7@CC;@FC;T;;;0; @HC; { ; IC; "6Returns guessed encoding of _str_ by nkf routine.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"guess(str);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Encoding;T;$@_C;![ ;"I"@return [Encoding];T;#0;$@_C;.F;Bi ;C0;7[[I"str;T0;$@_C;![ ;"I"cReturns guessed encoding of _str_ by nkf routine.
@overload guess(str)
@return [Encoding];T;#0;$@_C;.F;/o;0;1T;2i;3i;Bi ;%@C;9@]C;:@^C;;To;u;[[@Ci;F;: AUTO;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@vC;%@C;&I"NKF::AUTO;F;xI" Qnil;To;u;[[@Ci;F;: NOCONV;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::NOCONV;F;xI" Qnil;To;u;[[@Ci;F;: UNKNOWN;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::UNKNOWN;F;xI" Qnil;To;u;[[@Ci;F;: BINARY;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::BINARY;F;xI"3rb_enc_from_encoding(rb_nkf_enc_get("BINARY"));To;u;[[@Ci;F;:
ASCII;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::ASCII;F;xI"5rb_enc_from_encoding(rb_nkf_enc_get("US-ASCII"));To;u;[[@Ci;F;:JIS;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"
NKF::JIS;F;xI"8rb_enc_from_encoding(rb_nkf_enc_get("ISO-2022-JP"));To;u;[[@Ci;F;:EUC;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"
NKF::EUC;F;xI"3rb_enc_from_encoding(rb_nkf_enc_get("EUC-JP"));To;u;[[@Ci;F;: SJIS;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::SJIS;F;xI"6rb_enc_from_encoding(rb_nkf_enc_get("Shift_JIS"));To;u;[[@Ci;F;: UTF8;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::UTF8;F;xI"-rb_enc_from_encoding(rb_utf8_encoding());To;u;[[@Ci;F;:
UTF16;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::UTF16;F;xI"5rb_enc_from_encoding(rb_nkf_enc_get("UTF-16BE"));To;u;[[@Ci;F;:
UTF32;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;%@C;&I"NKF::UTF32;F;xI"5rb_enc_from_encoding(rb_nkf_enc_get("UTF-32BE"));To;u;[[@Ci;F;: VERSION;;w;; ; [ ; { ; IC; " Full version string of nkf
;T; [ ;![ ;"I" Full version string of nkf;T;#0;$@C;.F;/o;0;1T;2i;3i;%@C;&I"NKF::VERSION;F;xI""rb_str_new2(RUBY_NKF_VERSION);To;u;[[@Ci;F;:NKF_VERSION;;w;; ; [ ; { ; IC; "Version of nkf
;T; [ ;![ ;"I"Version of nkf;T;#0;$@C;.F;/o;0;1T;2i;3i;%@C;&I"NKF::NKF_VERSION;F;xI" rb_str_new2(NKF_VERSION);To;u;[[@Ci;F;:NKF_RELEASE_DATE;;w;; ; [ ; { ; IC; "Release date of nkf
;T; [ ;![ ;"I"Release date of nkf;T;#0;$@C;.F;/o;0;1T;2i;3i;%@C;&I"NKF::NKF_RELEASE_DATE;F;xI""rb_str_new2(NKF_RELEASE_DATE);T;
@C; IC;[ ;
@C; IC;[ ;
@C;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[@Ci;F;:NKF;;;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@C;Bi ;%@;&I"NKF;Fo;;IC;[o;;IC;[o;4;5F;6;;; ;&I""Digest::Instance#bubblebabble;F;7[ ;[[I"+ext/digest/bubblebabble/bubblebabble.c;Tiw;T;:bubblebabble;0; [ ; { ; IC; "{call-seq:
digest_obj.bubblebabble -> hash_string
Returns the resulting hash value in a Bubblebabble encoded form.
;T; [ ;![ ;"I"}
call-seq:
digest_obj.bubblebabble -> hash_string
Returns the resulting hash value in a Bubblebabble encoded form.
;T;#0;$@D;.F;/o;0;1T;2ip;3iu;%@D;9I"}static VALUE
rb_digest_instance_bubblebabble(VALUE self)
{
return bubblebabble_str_new(rb_funcall(self, id_digest, 0));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Digest::Instance#update;F;7[[I"str;T0;[[I"ext/digest/digest.c;Ti;T;: update;0; [ ; { ; IC; "Updates the digest using a given _string_ and returns self.
The update() method and the left-shift operator are overridden by
each implementation subclass. (One should be an alias for the
other)
;T; [o;=
;>I"
overload;F;?0;; ;@0;:I"update(string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@*D;.F;Bi ;C0;7[[I" string;T0;$@*Do;=
;>I"
overload;F;?0;;;@0;:I"<<(string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@*D;.F;Bi ;C0;7[[I" string;T0;$@*D;![ ;"I"Updates the digest using a given _string_ and returns self.
The update() method and the left-shift operator are overridden by
each implementation subclass. (One should be an alias for the
other)
@overload update(string)
@overload <<(string);T;#0;$@*D;.F;/o;0;1T;2i;3i;%@D;9I"static VALUE
rb_digest_instance_update(VALUE self, VALUE str)
{
rb_digest_instance_method_unimpl(self, "update");
UNREACHABLE;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Digest::Instance#<<;F;7[[I"str;T0;[[@1Di;T;;;0; [ ; { ; IC; "Updates the digest using a given _string_ and returns self.
The update() method and the left-shift operator are overridden by
each implementation subclass. (One should be an alias for the
other)
;T; [o;=
;>I"
overload;F;?0;; ;@0;:I"update(string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@OD;.F;Bi ;C0;7[[I" string;T0;$@ODo;=
;>I"
overload;F;?0;;;@0;:I"<<(string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@OD;.F;Bi ;C0;7[[I" string;T0;$@OD;![ ;"@KD;#0;$@OD;.F;/o;0;1T;2i;3i;%@D;9I"static VALUE
rb_digest_instance_update(VALUE self, VALUE str)
{
rb_digest_instance_method_unimpl(self, "update");
UNREACHABLE;
};T;:I"static VALUE;T;;To;4;5F;6;;;;&I" Digest::Instance#finish;F;7[ ;[[@1Di;T;: finish;0; [ ; { ; IC; "TFinishes the digest and returns the resulting hash value.
This method is overridden by each implementation subclass and often
made private, because some of those subclasses may leave internal
data uninitialized. Do not call this method from outside. Use
#digest!() instead, which ensures that internal data be reset for
security reasons.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"instance_eval;T; IC; " ;T; [o;A
;>I"
yield;F;?I"[];T;0;@0;$@rD;![ ;"I"@yield [];T;#0;$@rD;.F;Bi ;C0;7[ ;$@rD;![ ;"I"zFinishes the digest and returns the resulting hash value.
This method is overridden by each implementation subclass and often
made private, because some of those subclasses may leave internal
data uninitialized. Do not call this method from outside. Use
#digest!() instead, which ensures that internal data be reset for
security reasons.
@overload instance_eval
@yield [];T;#0;$@rD;.F;/o;0;1T;2i;3i;%@D;9I"~static VALUE
rb_digest_instance_finish(VALUE self)
{
rb_digest_instance_method_unimpl(self, "finish");
UNREACHABLE;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Digest::Instance#reset;F;7[ ;[[@1Di;T;;;0; [ ; { ; IC; "yResets the digest to the initial state and returns self.
This method is overridden by each implementation subclass.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
reset;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@D;.F;Bi ;C0;7[ ;$@D;![ ;"I"Resets the digest to the initial state and returns self.
This method is overridden by each implementation subclass.
@overload reset;T;#0;$@D;.F;/o;0;1T;2i;3i;%@D;9I"|static VALUE
rb_digest_instance_reset(VALUE self)
{
rb_digest_instance_method_unimpl(self, "reset");
UNREACHABLE;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"#Digest::Instance#digest_length;F;7[ ;[[@1Di;T;:digest_length;0; [ ; { ; IC; "Returns the length of the hash value of the digest.
This method should be overridden by each implementation subclass.
If not, digest_obj.digest().length() is returned.
;T; [o;=
;>I"
overload;F;?0;;";@0;:I"digest_length;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@D;![ ;"I"@return [Integer];T;#0;$@D;.F;Bi ;C0;7[ ;$@D;![ ;"I"Returns the length of the hash value of the digest.
This method should be overridden by each implementation subclass.
If not, digest_obj.digest().length() is returned.
@overload digest_length
@return [Integer];T;#0;$@D;.F;/o;0;1T;2i;3i;%@D;9I"2static VALUE
rb_digest_instance_digest_length(VALUE self)
{
/* subclasses really should redefine this method */
VALUE digest = rb_digest_instance_digest(0, 0, self);
/* never blindly assume that #digest() returns a string */
StringValue(digest);
return LONG2NUM(RSTRING_LEN(digest));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I""Digest::Instance#block_length;F;7[ ;[[@1Di;T;:block_length;0; [ ; { ; IC; "hReturns the block length of the digest.
This method is overridden by each implementation subclass.
;T; [o;=
;>I"
overload;F;?0;;#;@0;:I"block_length;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@D;![ ;"I"@return [Integer];T;#0;$@D;.F;Bi ;C0;7[ ;$@D;![ ;"I"Returns the block length of the digest.
This method is overridden by each implementation subclass.
@overload block_length
@return [Integer];T;#0;$@D;.F;/o;0;1T;2i;3i;%@D;9I"static VALUE
rb_digest_instance_block_length(VALUE self)
{
rb_digest_instance_method_unimpl(self, "block_length");
UNREACHABLE;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"Digest::Instance#==;F;7[[I"
other;T0;[[@1Dio;T;;F;0; [ ; { ; IC; "If a string is given, checks whether it is equal to the hex-encoded
hash value of the digest object. If another digest instance is
given, checks whether they have the same hash value. Otherwise
returns false.
;T; [o;=
;>I"
overload;F;?0;;F;@0;:I"==(another_digest_obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@D;![ ;"I"@return [Boolean];T;#0;$@D;.F;Bi ;C0;7[[I"another_digest_obj;T0;$@Do;=
;>I"
overload;F;?0;;F;@0;:I"==(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@D;![ ;"I"@return [Boolean];T;#0;$@D;.F;Bi ;C0;7[[I" string;T0;$@D;![ ;"I"2If a string is given, checks whether it is equal to the hex-encoded
hash value of the digest object. If another digest instance is
given, checks whether they have the same hash value. Otherwise
returns false.
@overload ==(another_digest_obj)
@return [Boolean]
@overload ==(string)
@return [Boolean];T;#0;$@D;.F;/o;0;1T;2ie;3in;%@D;9I"static VALUE
rb_digest_instance_equal(VALUE self, VALUE other)
{
VALUE str1, str2;
if (rb_obj_is_kind_of(other, rb_mDigest_Instance) == Qtrue) {
str1 = rb_digest_instance_digest(0, 0, self);
str2 = rb_digest_instance_digest(0, 0, other);
} else {
str1 = rb_digest_instance_to_s(self);
str2 = rb_check_string_type(other);
if (NIL_P(str2)) return Qfalse;
}
/* never blindly assume that subclass methods return strings */
StringValue(str1);
StringValue(str2);
if (RSTRING_LEN(str1) == RSTRING_LEN(str2) &&
rb_str_cmp(str1, str2) == 0) {
return Qtrue;
}
return Qfalse;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" Digest::Instance#inspect;F;7[ ;[[@1DiR;T;;J;0; [ ; { ; IC; "6Creates a printable version of the digest object.
;T; [o;=
;>I"
overload;F;?0;;J;@0;:I" inspect;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@E;![ ;"I"@return [String];T;#0;$@E;.F;Bi ;C0;7[ ;$@E;![ ;"I"]Creates a printable version of the digest object.
@overload inspect
@return [String];T;#0;$@E;.F;/o;0;1T;2iL;3iP;%@D;9I"static VALUE
rb_digest_instance_inspect(VALUE self)
{
VALUE str;
size_t digest_len = 32; /* about this size at least */
const char *cname;
cname = rb_obj_classname(self);
/* #-'',
then a new instance of Ruby is started as the subprocess.
If cmd is an +Array+ of +String+,
then it will be used as the subprocess's +argv+ bypassing a shell.
The array can contain a hash at first for environments and
a hash at last for options similar to #spawn.
The default mode for the new file object is ``r'',
but mode may be set to any of the modes listed in the description for class IO.
The last argument opt qualifies mode.
# set IO encoding
IO.popen("nkf -e filename", :external_encoding=>"EUC-JP") {|nkf_io|
euc_jp_string = nkf_io.read
}
# merge standard output and standard error using
# spawn option. See the document of Kernel.spawn.
IO.popen(["ls", "/", :err=>[:child, :out]]) {|ls_io|
ls_result_with_error = ls_io.read
}
# spawn options can be mixed with IO options
IO.popen(["ls", "/"], :err=>[:child, :out]) {|ls_io|
ls_result_with_error = ls_io.read
}
Raises exceptions which IO.pipe and Kernel.spawn raise.
If a block is given, Ruby will run the command as a child connected
to Ruby with a pipe. Ruby's end of the pipe will be passed as a
parameter to the block.
At the end of block, Ruby closes the pipe and sets $?.
In this case IO.popen returns the value of the block.
If a block is given with a _cmd_ of ``-'',
the block will be run in two separate processes: once in the parent,
and once in a child. The parent process will be passed the pipe
object as a parameter to the block, the child version of the block
will be passed +nil+, and the child's standard in and
standard out will be connected to the parent through the pipe. Not
available on all platforms.
f = IO.popen("uname")
p f.readlines
f.close
puts "Parent is #{Process.pid}"
IO.popen("date") {|f| puts f.gets }
IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
p $?
IO.popen(%w"sed -e s|^|-'',
then a new instance of Ruby is started as the subprocess.
If cmd is an +Array+ of +String+,
then it will be used as the subprocess's +argv+ bypassing a shell.
The array can contain a hash at first for environments and
a hash at last for options similar to #spawn.
The default mode for the new file object is ``r'',
but mode may be set to any of the modes listed in the description for class IO.
The last argument opt qualifies mode.
# set IO encoding
IO.popen("nkf -e filename", :external_encoding=>"EUC-JP") {|nkf_io|
euc_jp_string = nkf_io.read
}
# merge standard output and standard error using
# spawn option. See the document of Kernel.spawn.
IO.popen(["ls", "/", :err=>[:child, :out]]) {|ls_io|
ls_result_with_error = ls_io.read
}
# spawn options can be mixed with IO options
IO.popen(["ls", "/"], :err=>[:child, :out]) {|ls_io|
ls_result_with_error = ls_io.read
}
Raises exceptions which IO.pipe and Kernel.spawn raise.
If a block is given, Ruby will run the command as a child connected
to Ruby with a pipe. Ruby's end of the pipe will be passed as a
parameter to the block.
At the end of block, Ruby closes the pipe and sets $?.
In this case IO.popen returns the value of the block.
If a block is given with a _cmd_ of ``-'',
the block will be run in two separate processes: once in the parent,
and once in a child. The parent process will be passed the pipe
object as a parameter to the block, the child version of the block
will be passed +nil+, and the child's standard in and
standard out will be connected to the parent through the pipe. Not
available on all platforms.
f = IO.popen("uname")
p f.readlines
f.close
puts "Parent is #{Process.pid}"
IO.popen("date") {|f| puts f.gets }
IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
p $?
IO.popen(%w"sed -e s|^|"|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.foreach to disable the behavior of subprocess invocation.
File.foreach("testfile") {|x| print "GOT ", x }
IO.foreach("| cat testfile") {|x| print "GOT ", x }
produces:
GOT This is line one
GOT This is line two
GOT This is line three
GOT And so on...
If the last argument is a hash, it's the keyword argument to open.
See IO.readlines for details about getline_args.
And see also IO.read for details about open_args.
;T; [
o;=
;>I"
overload;F;?0;;p;@0;:I"6foreach(name, sep=$/ [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Mo;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@M;![ ;"I" @yield [line]
@return [nil];T;#0;$@M;.F;Bi ;C0;7[[I" name;T0[I"sep;TI""$/[, getline_args, open_args];T;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I"5foreach(name, limit [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Mo;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@M;![ ;"I" @yield [line]
@return [nil];T;#0;$@M;.F;Bi ;C0;7[[I" name;T0[I"%limit[, getline_args, open_args];T0;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I":foreach(name, sep, limit [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Mo;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@M;![ ;"I" @yield [line]
@return [nil];T;#0;$@M;.F;Bi ;C0;7[[I" name;T0[I"sep;T0[I"%limit[, getline_args, open_args];T0;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I"foreach(...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@M;.F;Bi ;C0;7[[I"...;T0;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I"6foreach(name, sep=$/ [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Mo;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@M;![ ;"I" @yield [line]
@return [nil];T;#0;$@M;.F;Bi ;C0;7[[I" name;T0[I"sep;TI""$/[, getline_args, open_args];T;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I"5foreach(name, limit [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Mo;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@M;![ ;"I" @yield [line]
@return [nil];T;#0;$@M;.F;Bi ;C0;7[[I" name;T0[I"%limit[, getline_args, open_args];T0;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I":foreach(name, sep, limit [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Mo;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@M;![ ;"I" @yield [line]
@return [nil];T;#0;$@M;.F;Bi ;C0;7[[I" name;T0[I"sep;T0[I"%limit[, getline_args, open_args];T0;$@Mo;=
;>I"
overload;F;?0;;p;@0;:I"foreach(...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@M;.F;Bi ;C0;7[[I"...;T0;$@M;![ ;"I"Executes the block for every line in the named I/O port, where lines
are separated by sep.
If no block is given, an enumerator is returned instead.
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.foreach to disable the behavior of subprocess invocation.
File.foreach("testfile") {|x| print "GOT ", x }
IO.foreach("| cat testfile") {|x| print "GOT ", x }
produces:
GOT This is line one
GOT This is line two
GOT This is line three
GOT And so on...
If the last argument is a hash, it's the keyword argument to open.
See IO.readlines for details about getline_args.
And see also IO.read for details about open_args.
@overload foreach(name, sep=$/ [, getline_args, open_args])
@yield [line]
@return [nil]
@overload foreach(name, limit [, getline_args, open_args])
@yield [line]
@return [nil]
@overload foreach(name, sep, limit [, getline_args, open_args])
@yield [line]
@return [nil]
@overload foreach(...)
@overload foreach(name, sep=$/ [, getline_args, open_args])
@yield [line]
@return [nil]
@overload foreach(name, limit [, getline_args, open_args])
@yield [line]
@return [nil]
@overload foreach(name, sep, limit [, getline_args, open_args])
@yield [line]
@return [nil]
@overload foreach(...);T;#0;$@M;.F;/o;0;1T;2i*;3i*;%@kL;9I"Qstatic VALUE
rb_io_s_foreach(int argc, VALUE *argv, VALUE self)
{
VALUE opt;
int orig_argc = argc;
struct foreach_arg arg;
struct getline_arg garg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, NULL, NULL, &opt);
RETURN_ENUMERATOR(self, orig_argc, argv);
extract_getline_args(argc-1, argv+1, &garg);
open_key_args(self, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
extract_getline_opts(opt, &garg);
check_getline_args(&garg.rs, &garg.limit, garg.io = arg.io);
return rb_ensure(io_s_foreach, (VALUE)&garg, rb_io_close, arg.io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO.readlines;F;7[[@90;[[@Ti +;T;;;0; [ ; { ; IC; "Reads the entire file specified by name as individual
lines, and returns those lines in an array. Lines are separated by
sep.
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.readlines to disable the behavior of subprocess invocation.
a = File.readlines("testfile")
a[0] #=> "This is line one\n"
b = File.readlines("testfile", chomp: true)
b[0] #=> "This is line one"
IO.readlines("|ls -a") #=> [".\n", "..\n", ...]
If the last argument is a hash, it's the keyword argument to open.
=== Options for getline
The options hash accepts the following keys:
:chomp::
When the optional +chomp+ keyword argument has a true value,
\n, \r, and \r\n
will be removed from the end of each line.
See also IO.read for details about +name+ and open_args.
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I"8readlines(name, sep=$/ [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@LN;![ ;"I"@return [Array];T;#0;$@LN;.F;Bi ;C0;7[[I" name;T0[I"sep;TI""$/[, getline_args, open_args];T;$@LNo;=
;>I"
overload;F;?0;;;@0;:I"7readlines(name, limit [, getline_args, open_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@LN;![ ;"I"@return [Array];T;#0;$@LN;.F;Bi ;C0;7[[I" name;T0[I"%limit[, getline_args, open_args];T0;$@LNo;=
;>I"
overload;F;?0;;;@0;:I""|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.readlines to disable the behavior of subprocess invocation.
a = File.readlines("testfile")
a[0] #=> "This is line one\n"
b = File.readlines("testfile", chomp: true)
b[0] #=> "This is line one"
IO.readlines("|ls -a") #=> [".\n", "..\n", ...]
If the last argument is a hash, it's the keyword argument to open.
=== Options for getline
The options hash accepts the following keys:
:chomp::
When the optional +chomp+ keyword argument has a true value,
\n, \r, and \r\n
will be removed from the end of each line.
See also IO.read for details about +name+ and open_args.
@overload readlines(name, sep=$/ [, getline_args, open_args])
@return [Array]
@overload readlines(name, limit [, getline_args, open_args])
@return [Array]
@overload readlines(name, sep, limit [, getline_args, open_args])
@return [Array]
@overload readlines(name, sep=$/ [, getline_args, open_args])
@return [Array]
@overload readlines(name, limit [, getline_args, open_args])
@return [Array]
@overload readlines(name, sep, limit [, getline_args, open_args])
@return [Array];T;#0;$@LN;.F;/o;0;1T;2i*;3i
+;%@kL;9I" static VALUE
rb_io_s_readlines(int argc, VALUE *argv, VALUE io)
{
VALUE opt;
struct foreach_arg arg;
struct getline_arg garg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, NULL, NULL, &opt);
extract_getline_args(argc-1, argv+1, &garg);
open_key_args(io, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
extract_getline_opts(opt, &garg);
check_getline_args(&garg.rs, &garg.limit, garg.io = arg.io);
return rb_ensure(io_s_readlines, (VALUE)&garg, rb_io_close, arg.io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO.read;F;7[[@90;[[@Ti^+;T;: read;0; [ ; { ; IC; "XOpens the file, optionally seeks to the given +offset+, then returns
+length+ bytes (defaulting to the rest of the file). #read ensures
the file is closed before returning.
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.read to disable the behavior of subprocess invocation.
=== Options
The options hash accepts the following keys:
:encoding::
string or encoding
Specifies the encoding of the read string. +:encoding+ will be ignored
if +length+ is specified. See Encoding.aliases for possible encodings.
:mode::
string or integer
Specifies the mode argument for open(). It must start
with an "r", otherwise it will cause an error.
See IO.new for the list of possible modes.
:open_args::
array
Specifies arguments for open() as an array. This key can not be used
in combination with either +:encoding+ or +:mode+.
Examples:
File.read("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
File.read("testfile", 20) #=> "This is line one\nThi"
File.read("testfile", 20, 10) #=> "ne one\nThis is line "
File.read("binfile", mode: "rb") #=> "\xF7\x00\x00\x0E\x12"
IO.read("|ls -a") #=> ".\n..\n"...
;T; [o;=
;>I"
overload;F;?0;;q;@0;:I",read(name, [length [, offset]] [, opt]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@N;![ ;"I"@return [String];T;#0;$@N;.F;Bi ;C0;7[[I" name;T0[I" [length [, offset]][, opt];T0;$@No;=
;>I"
overload;F;?0;;q;@0;:I",read(name, [length [, offset]] [, opt]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@N;![ ;"I"@return [String];T;#0;$@N;.F;Bi ;C0;7[[I" name;T0[I" [length [, offset]][, opt];T0;$@N;![ ;"I"Opens the file, optionally seeks to the given +offset+, then returns
+length+ bytes (defaulting to the rest of the file). #read ensures
the file is closed before returning.
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.read to disable the behavior of subprocess invocation.
=== Options
The options hash accepts the following keys:
:encoding::
string or encoding
Specifies the encoding of the read string. +:encoding+ will be ignored
if +length+ is specified. See Encoding.aliases for possible encodings.
:mode::
string or integer
Specifies the mode argument for open(). It must start
with an "r", otherwise it will cause an error.
See IO.new for the list of possible modes.
:open_args::
array
Specifies arguments for open() as an array. This key can not be used
in combination with either +:encoding+ or +:mode+.
Examples:
File.read("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
File.read("testfile", 20) #=> "This is line one\nThi"
File.read("testfile", 20, 10) #=> "ne one\nThis is line "
File.read("binfile", mode: "rb") #=> "\xF7\x00\x00\x0E\x12"
IO.read("|ls -a") #=> ".\n..\n"...
@overload read(name, [length [, offset]] [, opt])
@return [String]
@overload read(name, [length [, offset]] [, opt])
@return [String];T;#0;$@N;.F;/o;0;1T;2i0+;3i\+;%@kL;9I"ystatic VALUE
rb_io_s_read(int argc, VALUE *argv, VALUE io)
{
VALUE opt, offset;
struct foreach_arg arg;
argc = rb_scan_args(argc, argv, "13:", NULL, NULL, &offset, NULL, &opt);
open_key_args(io, argc, argv, opt, &arg);
if (NIL_P(arg.io)) return Qnil;
if (!NIL_P(offset)) {
struct seek_arg sarg;
int state = 0;
sarg.io = arg.io;
sarg.offset = offset;
sarg.mode = SEEK_SET;
rb_protect(seek_before_access, (VALUE)&sarg, &state);
if (state) {
rb_io_close(arg.io);
rb_jump_tag(state);
}
if (arg.argc == 2) arg.argc = 1;
}
return rb_ensure(io_s_read, (VALUE)&arg, rb_io_close, arg.io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO.binread;F;7[[@90;[[@Ti+;T;: binread;0; [ ; { ; IC; "Opens the file, optionally seeks to the given offset, then
returns length bytes (defaulting to the rest of the file).
#binread ensures the file is closed before returning. The open mode
would be "rb:ASCII-8BIT".
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.binread to disable the behavior of subprocess invocation.
File.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
File.binread("testfile", 20) #=> "This is line one\nThi"
File.binread("testfile", 20, 10) #=> "ne one\nThis is line "
IO.binread("| cat testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
See also IO.read for details about +name+ and open_args.
;T; [o;=
;>I"
overload;F;?0;;r;@0;:I"'binread(name, [length [, offset]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@N;![ ;"I"@return [String];T;#0;$@N;.F;Bi ;C0;7[[I" name;T0[I"[length [, offset]];T0;$@No;=
;>I"
overload;F;?0;;r;@0;:I"'binread(name, [length [, offset]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@N;![ ;"I"@return [String];T;#0;$@N;.F;Bi ;C0;7[[I" name;T0[I"[length [, offset]];T0;$@N;![ ;"I"Opens the file, optionally seeks to the given offset, then
returns length bytes (defaulting to the rest of the file).
#binread ensures the file is closed before returning. The open mode
would be "rb:ASCII-8BIT".
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.binread to disable the behavior of subprocess invocation.
File.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
File.binread("testfile", 20) #=> "This is line one\nThi"
File.binread("testfile", 20, 10) #=> "ne one\nThis is line "
IO.binread("| cat testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
See also IO.read for details about +name+ and open_args.
@overload binread(name, [length [, offset]])
@return [String]
@overload binread(name, [length [, offset]])
@return [String];T;#0;$@N;.F;/o;0;1T;2iw+;3i+;%@kL;9I"static VALUE
rb_io_s_binread(int argc, VALUE *argv, VALUE io)
{
VALUE offset;
struct foreach_arg arg;
enum {
fmode = FMODE_READABLE|FMODE_BINMODE,
oflags = O_RDONLY
#ifdef O_BINARY
|O_BINARY
#endif
};
convconfig_t convconfig = {NULL, NULL, 0, Qnil};
rb_scan_args(argc, argv, "12", NULL, NULL, &offset);
FilePathValue(argv[0]);
convconfig.enc = rb_ascii8bit_encoding();
arg.io = rb_io_open_generic(io, argv[0], oflags, fmode, &convconfig, 0);
if (NIL_P(arg.io)) return Qnil;
arg.argv = argv+1;
arg.argc = (argc > 1) ? 1 : 0;
if (!NIL_P(offset)) {
struct seek_arg sarg;
int state = 0;
sarg.io = arg.io;
sarg.offset = offset;
sarg.mode = SEEK_SET;
rb_protect(seek_before_access, (VALUE)&sarg, &state);
if (state) {
rb_io_close(arg.io);
rb_jump_tag(state);
}
}
return rb_ensure(io_s_read, (VALUE)&arg, rb_io_close, arg.io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO.write;F;7[[@90;[[@Ti ,;T;:
write;0; [ ; { ; IC; " Opens the file, optionally seeks to the given offset, writes
string, then returns the length written. #write ensures the
file is closed before returning. If offset is not given in
write mode, the file is truncated. Otherwise, it is not truncated.
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.write to disable the behavior of subprocess invocation.
File.write("testfile", "0123456789", 20) #=> 10
# File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"
File.write("testfile", "0123456789") #=> 10
# File would now read: "0123456789"
IO.write("|tr a-z A-Z", "abc") #=> 3
# Prints "ABC" to the standard output
If the last argument is a hash, it specifies options for the internal
open(). It accepts the following keys:
:encoding::
string or encoding
Specifies the encoding of the read string.
See Encoding.aliases for possible encodings.
:mode::
string or integer
Specifies the mode argument for open(). It must start
with "w", "a", or "r+", otherwise it will cause an error.
See IO.new for the list of possible modes.
:perm::
integer
Specifies the perm argument for open().
:open_args::
array
Specifies arguments for open() as an array.
This key can not be used in combination with other keys.
See also IO.read for details about +name+ and open_args.
;T; [ o;=
;>I"
overload;F;?0;;s;@0;:I"#write(name, string [, offset]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@)O;![ ;"I"@return [Integer];T;#0;$@)O;.F;Bi ;C0;7[[I" name;T0[I"string[, offset];T0;$@)Oo;=
;>I"
overload;F;?0;;s;@0;:I"+write(name, string [, offset] [, opt]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@)O;![ ;"I"@return [Integer];T;#0;$@)O;.F;Bi ;C0;7[[I" name;T0[I" string[, offset][, opt];T0;$@)Oo;=
;>I"
overload;F;?0;;s;@0;:I"#write(name, string [, offset]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@)O;![ ;"I"@return [Integer];T;#0;$@)O;.F;Bi ;C0;7[[I" name;T0[I"string[, offset];T0;$@)Oo;=
;>I"
overload;F;?0;;s;@0;:I"+write(name, string [, offset] [, opt]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@)O;![ ;"I"@return [Integer];T;#0;$@)O;.F;Bi ;C0;7[[I" name;T0[I" string[, offset][, opt];T0;$@)O;![ ;"I"Opens the file, optionally seeks to the given offset, writes
string, then returns the length written. #write ensures the
file is closed before returning. If offset is not given in
write mode, the file is truncated. Otherwise, it is not truncated.
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.write to disable the behavior of subprocess invocation.
File.write("testfile", "0123456789", 20) #=> 10
# File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"
File.write("testfile", "0123456789") #=> 10
# File would now read: "0123456789"
IO.write("|tr a-z A-Z", "abc") #=> 3
# Prints "ABC" to the standard output
If the last argument is a hash, it specifies options for the internal
open(). It accepts the following keys:
:encoding::
string or encoding
Specifies the encoding of the read string.
See Encoding.aliases for possible encodings.
:mode::
string or integer
Specifies the mode argument for open(). It must start
with "w", "a", or "r+", otherwise it will cause an error.
See IO.new for the list of possible modes.
:perm::
integer
Specifies the perm argument for open().
:open_args::
array
Specifies arguments for open() as an array.
This key can not be used in combination with other keys.
See also IO.read for details about +name+ and open_args.
@overload write(name, string [, offset])
@return [Integer]
@overload write(name, string [, offset] [, opt])
@return [Integer]
@overload write(name, string [, offset])
@return [Integer]
@overload write(name, string [, offset] [, opt])
@return [Integer];T;#0;$@)O;.F;/o;0;1T;2i+;3i ,;%@kL;9I"nstatic VALUE
rb_io_s_write(int argc, VALUE *argv, VALUE io)
{
return io_s_write(argc, argv, io, 0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO.binwrite;F;7[[@90;[[@Ti7,;T;:
binwrite;0; [ ; { ; IC; "Same as IO.write except opening the file in binary mode and
ASCII-8BIT encoding ("wb:ASCII-8BIT").
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.binwrite to disable the behavior of subprocess invocation.
See also IO.read for details about +name+ and open_args.
;T; [ o;=
;>I"
overload;F;?0;;t;@0;:I"%binwrite(name, string, [offset]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@|O;![ ;"I"@return [Integer];T;#0;$@|O;.F;Bi ;C0;7[[I" name;T0[I" string;T0[I"
[offset];T0;$@|Oo;=
;>I"
overload;F;?0;;t;@0;:I"0binwrite(name, string, [offset], open_args);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@|O;![ ;"I"@return [Integer];T;#0;$@|O;.F;Bi ;C0;7[ [I" name;T0[I" string;T0[I"
[offset];T0[I"open_args;T0;$@|Oo;=
;>I"
overload;F;?0;;t;@0;:I"%binwrite(name, string, [offset]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@|O;![ ;"I"@return [Integer];T;#0;$@|O;.F;Bi ;C0;7[[I" name;T0[I" string;T0[I"
[offset];T0;$@|Oo;=
;>I"
overload;F;?0;;t;@0;:I"0binwrite(name, string, [offset], open_args);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@|O;![ ;"I"@return [Integer];T;#0;$@|O;.F;Bi ;C0;7[ [I" name;T0[I" string;T0[I"
[offset];T0[I"open_args;T0;$@|O;![ ;"I"Same as IO.write except opening the file in binary mode and
ASCII-8BIT encoding ("wb:ASCII-8BIT").
If +name+ starts with a pipe character ("|") and the receiver
is the IO class, a subprocess is created in the same way as Kernel#open,
and its output is returned.
Consider to use File.binwrite to disable the behavior of subprocess invocation.
See also IO.read for details about +name+ and open_args.
@overload binwrite(name, string, [offset])
@return [Integer]
@overload binwrite(name, string, [offset], open_args)
@return [Integer]
@overload binwrite(name, string, [offset])
@return [Integer]
@overload binwrite(name, string, [offset], open_args)
@return [Integer];T;#0;$@|O;.F;/o;0;1T;2i%,;3i7,;%@kL;9I"qstatic VALUE
rb_io_s_binwrite(int argc, VALUE *argv, VALUE io)
{
return io_s_write(argc, argv, io, 1);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO.select;F;7[[@90;[[@TiS';T;;;0; [ ; { ; IC; "Calls select(2) system call.
It monitors given arrays of IO objects, waits until one or more of
IO objects are ready for reading, are ready for writing, and have
pending exceptions respectively, and returns an array that contains
arrays of those IO objects. It will return +nil+ if optional
timeout value is given and no IO object is ready in
timeout seconds.
IO.select peeks the buffer of IO objects for testing readability.
If the IO buffer is not empty, IO.select immediately notifies
readability. This "peek" only happens for IO objects. It does not
happen for IO-like objects such as OpenSSL::SSL::SSLSocket.
The best way to use IO.select is invoking it after nonblocking
methods such as #read_nonblock, #write_nonblock, etc. The methods
raise an exception which is extended by IO::WaitReadable or
IO::WaitWritable. The modules notify how the caller should wait
with IO.select. If IO::WaitReadable is raised, the caller should
wait for reading. If IO::WaitWritable is raised, the caller should
wait for writing.
So, blocking read (#readpartial) can be emulated using
#read_nonblock and IO.select as follows:
begin
result = io_like.read_nonblock(maxlen)
rescue IO::WaitReadable
IO.select([io_like])
retry
rescue IO::WaitWritable
IO.select(nil, [io_like])
retry
end
Especially, the combination of nonblocking methods and IO.select is
preferred for IO like objects such as OpenSSL::SSL::SSLSocket. It
has #to_io method to return underlying IO object. IO.select calls
#to_io to obtain the file descriptor to wait.
This means that readability notified by IO.select doesn't mean
readability from OpenSSL::SSL::SSLSocket object.
The most likely situation is that OpenSSL::SSL::SSLSocket buffers
some data. IO.select doesn't see the buffer. So IO.select can
block when OpenSSL::SSL::SSLSocket#readpartial doesn't block.
However, several more complicated situations exist.
SSL is a protocol which is sequence of records.
The record consists of multiple bytes.
So, the remote side of SSL sends a partial record, IO.select
notifies readability but OpenSSL::SSL::SSLSocket cannot decrypt a
byte and OpenSSL::SSL::SSLSocket#readpartial will block.
Also, the remote side can request SSL renegotiation which forces
the local SSL engine to write some data.
This means OpenSSL::SSL::SSLSocket#readpartial may invoke #write
system call and it can block.
In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock raises
IO::WaitWritable instead of blocking.
So, the caller should wait for ready for writability as above
example.
The combination of nonblocking methods and IO.select is also useful
for streams such as tty, pipe socket socket when multiple processes
read from a stream.
Finally, Linux kernel developers don't guarantee that
readability of select(2) means readability of following read(2) even
for a single process.
See select(2) manual on GNU/Linux system.
Invoking IO.select before IO#readpartial works well as usual.
However it is not the best way to use IO.select.
The writability notified by select(2) doesn't show
how many bytes are writable.
IO#write method blocks until given whole string is written.
So, IO#write(two or more bytes) can block after
writability is notified by IO.select. IO#write_nonblock is required
to avoid the blocking.
Blocking write (#write) can be emulated using #write_nonblock and
IO.select as follows: IO::WaitReadable should also be rescued for
SSL renegotiation in OpenSSL::SSL::SSLSocket.
while 0 < string.bytesize
begin
written = io_like.write_nonblock(string)
rescue IO::WaitReadable
IO.select([io_like])
retry
rescue IO::WaitWritable
IO.select(nil, [io_like])
retry
end
string = string.byteslice(written..-1)
end
=== Parameters
read_array:: an array of IO objects that wait until ready for read
write_array:: an array of IO objects that wait until ready for write
error_array:: an array of IO objects that wait for exceptions
timeout:: a numeric value in second
=== Example
rp, wp = IO.pipe
mesg = "ping "
100.times {
# IO.select follows IO#read. Not the best way to use IO.select.
rs, ws, = IO.select([rp], [wp])
if r = rs[0]
ret = r.read(5)
print ret
case ret
when /ping/
mesg = "pong\n"
when /pong/
mesg = "ping "
end
end
if w = ws[0]
w.write(mesg)
end
}
produces:
ping pong
ping pong
ping pong
(snipped)
ping
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"Cselect(read_array [, write_array [, error_array [, timeout]]]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;TI"nil;T;$@O;![ ;"I"@return [Array, nil];T;#0;$@O;.F;Bi ;C0;7[[I":read_array[, write_array [, error_array [, timeout]]];T0;$@O;![ ;"@ ;#0;$@O;.F;/o;0;1T;2i&;3iP';%@kL;9I"
static VALUE
rb_f_select(int argc, VALUE *argv, VALUE obj)
{
VALUE timeout;
struct select_args args;
struct timeval timerec;
int i;
rb_scan_args(argc, argv, "13", &args.read, &args.write, &args.except, &timeout);
if (NIL_P(timeout)) {
args.timeout = 0;
}
else {
timerec = rb_time_interval(timeout);
args.timeout = &timerec;
}
for (i = 0; i < numberof(args.fdsets); ++i)
rb_fd_init(&args.fdsets[i]);
return rb_ensure(select_call, (VALUE)&args, select_end, (VALUE)&args);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO.pipe;F;7[[@90;[[@Ti!*;T;: pipe;0; [ ; { ; IC; "0IO.pipe(...) {|read_io, write_io| ... }
Creates a pair of pipe endpoints (connected to each other) and
returns them as a two-element array of IO objects:
[ read_io, write_io ].
If a block is given, the block is called and
returns the value of the block.
read_io and write_io are sent to the block as arguments.
If read_io and write_io are not closed when the block exits, they are closed.
i.e. closing read_io and/or write_io doesn't cause an error.
Not available on all platforms.
If an encoding (encoding name or encoding object) is specified as an optional argument,
read string from pipe is tagged with the encoding specified.
If the argument is a colon separated two encoding names "A:B",
the read string is converted from encoding A (external encoding)
to encoding B (internal encoding), then tagged with B.
If two optional arguments are specified, those must be
encoding objects or encoding names,
and the first one is the external encoding,
and the second one is the internal encoding.
If the external encoding and the internal encoding is specified,
optional hash argument specify the conversion option.
In the example below, the two processes close the ends of the pipe
that they are not using. This is not just a cosmetic nicety. The
read end of a pipe will not generate an end of file condition if
there are any writers with the pipe still open. In the case of the
parent process, the rd.read will never return if it
does not first issue a wr.close.
rd, wr = IO.pipe
if fork
wr.close
puts "Parent got: <#{rd.read}>"
rd.close
Process.wait
else
rd.close
puts "Sending message to parent"
wr.write "Hi Dad"
wr.close
end
produces:
Sending message to parent
Parent got: ;T; [ o;= ;>I" overload;F;?0;;u;@0;:I" pipe;T; IC; " ;T; [o;A ;>I" return;F;?I" ;T;0;@[I" Array;T;$@O;![ ;"I"@return [Array];T;#0;$@O;.F;Bi ;C0;7[ ;$@Oo;= ;>I" overload;F;?0;;u;@0;:I"pipe(ext_enc);T; IC; " ;T; [o;A ;>I" return;F;?I" ;T;0;@[I" Array;T;$@O;![ ;"I"@return [Array];T;#0;$@O;.F;Bi ;C0;7[[I" ext_enc;T0;$@Oo;= ;>I" overload;F;?0;;u;@0;:I"$pipe("ext_enc:int_enc" [, opt]);T; IC; " ;T; [o;A ;>I" return;F;?I" ;T;0;@[I" Array;T;$@O;![ ;"I"@return [Array];T;#0;$@O;.F;Bi ;C0;7[[""ext_enc:"int_enc"[, opt];$@Oo;= ;>I" overload;F;?0;;u;@0;:I"#pipe(ext_enc, int_enc [, opt]);T; IC; " ;T; [o;A ;>I" return;F;?I" ;T;0;@[I" Array;T;$@O;![ ;"I"@return [Array];T;#0;$@O;.F;Bi ;C0;7[[I" ext_enc;T0[I"int_enc[, opt];T0;$@O;![ ;"I" IO.pipe(...) {|read_io, write_io| ... } Creates a pair of pipe endpoints (connected to each other) and returns them as a two-element array of IO objects:
[ read_io, write_io ].
If a block is given, the block is called and
returns the value of the block.
read_io and write_io are sent to the block as arguments.
If read_io and write_io are not closed when the block exits, they are closed.
i.e. closing read_io and/or write_io doesn't cause an error.
Not available on all platforms.
If an encoding (encoding name or encoding object) is specified as an optional argument,
read string from pipe is tagged with the encoding specified.
If the argument is a colon separated two encoding names "A:B",
the read string is converted from encoding A (external encoding)
to encoding B (internal encoding), then tagged with B.
If two optional arguments are specified, those must be
encoding objects or encoding names,
and the first one is the external encoding,
and the second one is the internal encoding.
If the external encoding and the internal encoding is specified,
optional hash argument specify the conversion option.
In the example below, the two processes close the ends of the pipe
that they are not using. This is not just a cosmetic nicety. The
read end of a pipe will not generate an end of file condition if
there are any writers with the pipe still open. In the case of the
parent process, the rd.read will never return if it
does not first issue a wr.close.
rd, wr = IO.pipe
if fork
wr.close
puts "Parent got: <#{rd.read}>"
rd.close
Process.wait
else
rd.close
puts "Sending message to parent"
wr.write "Hi Dad"
wr.close
end
produces:
Sending message to parent
Parent got: @overload pipe @return [Array] @overload pipe(ext_enc) @return [Array] @overload pipe("ext_enc:int_enc" [, opt]) @return [Array] @overload pipe(ext_enc, int_enc [, opt]) @return [Array];T;#0;$@O;.F;/o;0;1T;2i);3i!*;%@kL;9I"static VALUE rb_io_s_pipe(int argc, VALUE *argv, VALUE klass) { int pipes[2], state; VALUE r, w, args[3], v1, v2; VALUE opt; rb_io_t *fptr, *fptr2; struct io_encoding_set_args ies_args; int fmode = 0; VALUE ret; argc = rb_scan_args(argc, argv, "02:", &v1, &v2, &opt); if (rb_pipe(pipes) < 0) rb_sys_fail(0); args[0] = klass; args[1] = INT2NUM(pipes[0]); args[2] = INT2FIX(O_RDONLY); r = rb_protect(io_new_instance, (VALUE)args, &state); if (state) { close(pipes[0]); close(pipes[1]); rb_jump_tag(state); } GetOpenFile(r, fptr); ies_args.fptr = fptr; ies_args.v1 = v1; ies_args.v2 = v2; ies_args.opt = opt; rb_protect(io_encoding_set_v, (VALUE)&ies_args, &state); if (state) { close(pipes[1]); io_close(r); rb_jump_tag(state); } args[1] = INT2NUM(pipes[1]); args[2] = INT2FIX(O_WRONLY); w = rb_protect(io_new_instance, (VALUE)args, &state); if (state) { close(pipes[1]); if (!NIL_P(r)) rb_io_close(r); rb_jump_tag(state); } GetOpenFile(w, fptr2); rb_io_synchronized(fptr2); extract_binmode(opt, &fmode); if ((fmode & FMODE_BINMODE) && NIL_P(v1)) { rb_io_ascii8bit_binmode(r); rb_io_ascii8bit_binmode(w); } #if DEFAULT_TEXTMODE if ((fptr->mode & FMODE_TEXTMODE) && (fmode & FMODE_BINMODE)) { fptr->mode &= ~FMODE_TEXTMODE; setmode(fptr->fd, O_BINARY); } #if RUBY_CRLF_ENVIRONMENT if (fptr->encs.ecflags & ECONV_DEFAULT_NEWLINE_DECORATOR) { fptr->encs.ecflags |= ECONV_UNIVERSAL_NEWLINE_DECORATOR; } #endif #endif fptr->mode |= fmode; #if DEFAULT_TEXTMODE if ((fptr2->mode & FMODE_TEXTMODE) && (fmode & FMODE_BINMODE)) { fptr2->mode &= ~FMODE_TEXTMODE; setmode(fptr2->fd, O_BINARY); } #endif fptr2->mode |= fmode; ret = rb_assoc_new(r, w); if (rb_block_given_p()) { VALUE rw[2]; rw[0] = r; rw[1] = w; return rb_ensure(rb_yield, ret, pipe_pair_close, (VALUE)rw); } return ret; };T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO.try_convert;F;7[[I"io;T0;[[@TiS;T;:try_convert;0; [ ; { ; IC; "Attempts to convert +object+ into an \IO object via method +to_io+; returns the new \IO object if successful, or +nil+ otherwise: IO.try_convert(STDOUT) # => #>
IO.try_convert(ARGF) # => #>
IO.try_convert('STDOUT') # => nil
;T; [o;=
;>I"
overload;F;?0;;v;@0;:I"try_convert(object);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@EP;![ ;"I"@return [nil];T;#0;$@EP;.F;Bi ;C0;7[[I" object;T0;$@EP;![ ;"I"4Attempts to convert +object+ into an \IO object via method +to_io+;
returns the new \IO object if successful, or +nil+ otherwise:
IO.try_convert(STDOUT) # => #>
IO.try_convert(ARGF) # => #>
IO.try_convert('STDOUT') # => nil
@overload try_convert(object)
@return [nil];T;#0;$@EP;.F;/o;0;1T;2iG;3iQ;%@kL;9I"_static VALUE
rb_io_s_try_convert(VALUE dummy, VALUE io)
{
return rb_io_check_io(io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO.copy_stream;F;7[[@90;[[@Ti/;T;:copy_stream;0; [ ; { ; IC; "UIO.copy_stream copies src to dst.
src and dst is either a filename or an IO-like object.
IO-like object for src should have #readpartial or #read
method. IO-like object for dst should have #write method.
(Specialized mechanisms, such as sendfile system call, may be used
on appropriate situation.)
This method returns the number of bytes copied.
If optional arguments are not given,
the start position of the copy is
the beginning of the filename or
the current file offset of the IO.
The end position of the copy is the end of file.
If copy_length is given,
No more than copy_length bytes are copied.
If src_offset is given,
it specifies the start position of the copy.
When src_offset is specified and
src is an IO,
IO.copy_stream doesn't move the current file offset.
;T; [o;=
;>I"
overload;F;?0;;w;@0;:I"copy_stream(src, dst);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@dP;.F;Bi ;C0;7[[I"src;T0[I"dst;T0;$@dPo;=
;>I"
overload;F;?0;;w;@0;:I"'copy_stream(src, dst, copy_length);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@dP;.F;Bi ;C0;7[[I"src;T0[I"dst;T0[I"copy_length;T0;$@dPo;=
;>I"
overload;F;?0;;w;@0;:I"3copy_stream(src, dst, copy_length, src_offset);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@dP;.F;Bi ;C0;7[ [I"src;T0[I"dst;T0[I"copy_length;T0[I"src_offset;T0;$@dP;![ ;"I"IO.copy_stream copies src to dst.
src and dst is either a filename or an IO-like object.
IO-like object for src should have #readpartial or #read
method. IO-like object for dst should have #write method.
(Specialized mechanisms, such as sendfile system call, may be used
on appropriate situation.)
This method returns the number of bytes copied.
If optional arguments are not given,
the start position of the copy is
the beginning of the filename or
the current file offset of the IO.
The end position of the copy is the end of file.
If copy_length is given,
No more than copy_length bytes are copied.
If src_offset is given,
it specifies the start position of the copy.
When src_offset is specified and
src is an IO,
IO.copy_stream doesn't move the current file offset.
@overload copy_stream(src, dst)
@overload copy_stream(src, dst, copy_length)
@overload copy_stream(src, dst, copy_length, src_offset);T;#0;$@dP;.F;/o;0;1T;2i/;3i/;%@kL;9I"static VALUE
rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io)
{
VALUE src, dst, length, src_offset;
struct copy_stream_struct st;
MEMZERO(&st, struct copy_stream_struct, 1);
rb_scan_args(argc, argv, "22", &src, &dst, &length, &src_offset);
st.src = src;
st.dst = dst;
st.src_fptr = NULL;
st.dst_fptr = NULL;
if (NIL_P(length))
st.copy_length = (off_t)-1;
else
st.copy_length = NUM2OFFT(length);
if (NIL_P(src_offset))
st.src_offset = (off_t)-1;
else
st.src_offset = NUM2OFFT(src_offset);
rb_ensure(copy_stream_body, (VALUE)&st, copy_stream_finalize, (VALUE)&st);
return OFFT2NUM(st.total);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#initialize;F;7[[@90;[[@Ti>";T;;D;0; [ ; { ; IC; "Returns a new IO object (a stream) for the given integer file descriptor
+fd+ and +mode+ string. +opt+ may be used to specify parts of +mode+ in a
more readable fashion. See also IO.sysopen and IO.for_fd.
IO.new is called by various File and IO opening methods such as IO::open,
Kernel#open, and File::open.
=== Open Mode
When +mode+ is an integer it must be combination of the modes defined in
File::Constants (+File::RDONLY+,
f2.readlines[0] #=> "This is line one\n"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"reopen(other_IO);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@P;![ ;"I"@return [IO];T;#0;$@P;.F;Bi ;C0;7[[I"
other_IO;T0;$@Po;=
;>I"
overload;F;?0;;;@0;:I" reopen(path, mode [, opt]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@P;![ ;"I"@return [IO];T;#0;$@P;.F;Bi ;C0;7[[I" path;T0[I"mode[, opt];T0;$@P;![ ;"I"Reassociates ios with the I/O stream given in
other_IO or to a new stream opened on path. This may
dynamically change the actual class of this stream.
The +mode+ and +opt+ parameters accept the same values as IO.open.
f1 = File.new("testfile")
f2 = File.new("testfile")
f2.readlines[0] #=> "This is line one\n"
f2.reopen(f1) #=> #
f2.readlines[0] #=> "This is line one\n"
@overload reopen(other_IO)
@return [IO]
@overload reopen(path, mode [, opt])
@return [IO];T;#0;$@P;.F;/o;0;1T;2iz ;3i ;%@kL;9I" static VALUE
rb_io_reopen(int argc, VALUE *argv, VALUE file)
{
VALUE fname, nmode, opt;
int oflags;
rb_io_t *fptr;
if (rb_scan_args(argc, argv, "11:", &fname, &nmode, &opt) == 1) {
VALUE tmp = rb_io_check_io(fname);
if (!NIL_P(tmp)) {
return io_reopen(file, tmp);
}
}
FilePathValue(fname);
rb_io_taint_check(file);
fptr = RFILE(file)->fptr;
if (!fptr) {
fptr = RFILE(file)->fptr = ZALLOC(rb_io_t);
}
if (!NIL_P(nmode) || !NIL_P(opt)) {
int fmode;
convconfig_t convconfig;
rb_io_extract_modeenc(&nmode, 0, opt, &oflags, &fmode, &convconfig);
if (IS_PREP_STDIO(fptr) &&
((fptr->mode & FMODE_READWRITE) & (fmode & FMODE_READWRITE)) !=
(fptr->mode & FMODE_READWRITE)) {
rb_raise(rb_eArgError,
"%s can't change access mode from \"%s\" to \"%s\"",
PREP_STDIO_NAME(fptr), rb_io_fmode_modestr(fptr->mode),
rb_io_fmode_modestr(fmode));
}
fptr->mode = fmode;
fptr->encs = convconfig;
}
else {
oflags = rb_io_fmode_oflags(fptr->mode);
}
fptr->pathv = fname;
if (fptr->fd < 0) {
fptr->fd = rb_sysopen(fptr->pathv, oflags, 0666);
fptr->stdio_file = 0;
return file;
}
if (fptr->mode & FMODE_WRITABLE) {
if (io_fflush(fptr) < 0)
rb_sys_fail_on_write(fptr);
}
fptr->rbuf.off = fptr->rbuf.len = 0;
if (fptr->stdio_file) {
int e = rb_freopen(rb_str_encode_ospath(fptr->pathv),
rb_io_oflags_modestr(oflags),
fptr->stdio_file);
if (e) rb_syserr_fail_path(e, fptr->pathv);
fptr->fd = fileno(fptr->stdio_file);
rb_fd_fix_cloexec(fptr->fd);
#ifdef USE_SETVBUF
if (setvbuf(fptr->stdio_file, NULL, _IOFBF, 0) != 0)
rb_warn("setvbuf() can't be honoured for %"PRIsVALUE, fptr->pathv);
#endif
if (fptr->stdio_file == stderr) {
if (setvbuf(fptr->stdio_file, NULL, _IONBF, BUFSIZ) != 0)
rb_warn("setvbuf() can't be honoured for %"PRIsVALUE, fptr->pathv);
}
else if (fptr->stdio_file == stdout && isatty(fptr->fd)) {
if (setvbuf(fptr->stdio_file, NULL, _IOLBF, BUFSIZ) != 0)
rb_warn("setvbuf() can't be honoured for %"PRIsVALUE, fptr->pathv);
}
}
else {
int tmpfd = rb_sysopen(fptr->pathv, oflags, 0666);
int err = 0;
if (rb_cloexec_dup2(tmpfd, fptr->fd) < 0)
err = errno;
(void)close(tmpfd);
if (err) {
rb_syserr_fail_path(err, fptr->pathv);
}
}
return file;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#print;F;7[[@90;[[@Ti] ;T;;;0; [ ; { ; IC; "&Writes the given object(s) to ios. Returns +nil+.
The stream must be opened for writing.
Each given object that isn't a string will be converted by calling
its 0) {
rb_io_write(out, rb_output_fs);
}
rb_io_write(out, argv[i]);
}
if (argc > 0 && !NIL_P(rb_output_rs)) {
rb_io_write(out, rb_output_rs);
}
return Qnil;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" IO#putc;F;7[[I"ch;T0;[[@Ti ;T;;;0; [ ; { ; IC; "If obj is Numeric, write the character whose code is the
least-significant byte of obj. If obj is String,
write the first character of obj to ios. Otherwise,
raise TypeError.
$stdout.putc "A"
$stdout.putc 65
produces:
AA
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"putc(obj);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Object;T;$@'Q;![ ;"I"@return [Object];T;#0;$@'Q;.F;Bi ;C0;7[[I"obj;T0;$@'Q;![ ;"I"AIf obj is Numeric, write the character whose code is the
least-significant byte of obj. If obj is String,
write the first character of obj to ios. Otherwise,
raise TypeError.
$stdout.putc "A"
$stdout.putc 65
produces:
AA
@overload putc(obj)
@return [Object];T;#0;$@'Q;.F;/o;0;1T;2i ;3i ;%@kL;9I"static VALUE
rb_io_putc(VALUE io, VALUE ch)
{
VALUE str;
if (RB_TYPE_P(ch, T_STRING)) {
str = rb_str_substr(ch, 0, 1);
}
else {
char c = NUM2CHR(ch);
str = rb_str_new(&c, 1);
}
rb_io_write(io, str);
return ch;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#puts;F;7[[@90;[[@Ti ;T;;;0; [ ; { ; IC; "UWrites the given object(s) to ios.
Writes a newline after any that do not already end
with a newline sequence. Returns +nil+.
The stream must be opened for writing.
If called with an array argument, writes each element on a new line.
Each given object that isn't a string or array will be converted
by calling its +to_s+ method.
If called without arguments, outputs a single newline.
$stdout.puts("this", "is", ["a", "test"])
produces:
this
is
a
test
Note that +puts+ always uses newlines and is not affected
by the output record separator (ios, converting parameters under
control of the format string. See Kernel#sprintf for details.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"'printf(format_string [, obj, ...]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@fQ;![ ;"I"@return [nil];T;#0;$@fQ;.F;Bi ;C0;7[[I" format_string[, obj, ...];T0;$@fQ;![ ;"I"Formats and writes to ios, converting parameters under
control of the format string. See Kernel#sprintf for details.
@overload printf(format_string [, obj, ...])
@return [nil];T;#0;$@fQ;.F;/o;0;1T;2i ;3i ;%@kL;9I"VALUE
rb_io_printf(int argc, const VALUE *argv, VALUE out)
{
rb_io_write(out, rb_f_sprintf(argc, argv));
return Qnil;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" IO#each;F;7[[@90;[[@Tiy;T;;;0; [ ; { ; IC; "ios.each_line(sep=$/ [, getline_args]) {|line| block } -> ios
ios.each_line(limit [, getline_args]) {|line| block } -> ios
ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios
ios.each_line(...) -> an_enumerator
Executes the block for every line in ios, where lines are
separated by sep. ios must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
f.each {|line| puts "#{f.lineno}: #{line}" }
produces:
1: This is line one
2: This is line two
3: This is line three
4: And so on...
See IO.readlines for details about getline_args.
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I""each(sep=$/ [, getline_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Qo;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@Q;![ ;"I" @yield [line]
@return [IO];T;#0;$@Q;.F;Bi ;C0;7[[I"sep;TI"$/[, getline_args];T;$@Qo;=
;>I"
overload;F;?0;;;@0;:I"!each(limit [, getline_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Qo;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@Q;![ ;"I" @yield [line]
@return [IO];T;#0;$@Q;.F;Bi ;C0;7[[I"limit[, getline_args];T0;$@Qo;=
;>I"
overload;F;?0;;;@0;:I"&each(sep, limit [, getline_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Qo;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@Q;![ ;"I" @yield [line]
@return [IO];T;#0;$@Q;.F;Bi ;C0;7[[I"sep;T0[I"limit[, getline_args];T0;$@Qo;=
;>I"
overload;F;?0;;;@0;:I"each(...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@Q;.F;Bi ;C0;7[[I"...;T0;$@Q;![ ;"I" ios.each_line(sep=$/ [, getline_args]) {|line| block } -> ios
ios.each_line(limit [, getline_args]) {|line| block } -> ios
ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios
ios.each_line(...) -> an_enumerator
Executes the block for every line in ios, where lines are
separated by sep. ios must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
f.each {|line| puts "#{f.lineno}: #{line}" }
produces:
1: This is line one
2: This is line two
3: This is line three
4: And so on...
See IO.readlines for details about getline_args.
@overload each(sep=$/ [, getline_args])
@yield [line]
@return [IO]
@overload each(limit [, getline_args])
@yield [line]
@return [IO]
@overload each(sep, limit [, getline_args])
@yield [line]
@return [IO]
@overload each(...);T;#0;$@Q;.F;/o;0;1T;2iZ;3i{;%@kL;9I"static VALUE
rb_io_each_line(int argc, VALUE *argv, VALUE io)
{
VALUE str;
struct getline_arg args;
RETURN_ENUMERATOR(io, argc, argv);
prepare_getline_args(argc, argv, &args, io);
if (args.limit == 0)
rb_raise(rb_eArgError, "invalid limit: 0 for each_line");
while (!NIL_P(str = rb_io_getline_1(args.rs, args.limit, args.chomp, io))) {
rb_yield(str);
}
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#each_line;F;7[[@90;[[@Tiy;T;:each_line;0; [ ; { ; IC; "ios.each_line(sep=$/ [, getline_args]) {|line| block } -> ios
ios.each_line(limit [, getline_args]) {|line| block } -> ios
ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios
ios.each_line(...) -> an_enumerator
Executes the block for every line in ios, where lines are
separated by sep. ios must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
f.each {|line| puts "#{f.lineno}: #{line}" }
produces:
1: This is line one
2: This is line two
3: This is line three
4: And so on...
See IO.readlines for details about getline_args.
;T; [ o;=
;>I"
overload;F;?0;;;@0;:I""each(sep=$/ [, getline_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Qo;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@Q;![ ;"I" @yield [line]
@return [IO];T;#0;$@Q;.F;Bi ;C0;7[[I"sep;TI"$/[, getline_args];T;$@Qo;=
;>I"
overload;F;?0;;;@0;:I"!each(limit [, getline_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Qo;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@Q;![ ;"I" @yield [line]
@return [IO];T;#0;$@Q;.F;Bi ;C0;7[[I"limit[, getline_args];T0;$@Qo;=
;>I"
overload;F;?0;;;@0;:I"&each(sep, limit [, getline_args]);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" line;T;$@Qo;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@Q;![ ;"I" @yield [line]
@return [IO];T;#0;$@Q;.F;Bi ;C0;7[[I"sep;T0[I"limit[, getline_args];T0;$@Qo;=
;>I"
overload;F;?0;;;@0;:I"each(...);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@Q;.F;Bi ;C0;7[[I"...;T0;$@Q;![ ;"@Q;#0;$@Q;.F;/o;0;1T;2iZ;3i{;%@kL;9I"static VALUE
rb_io_each_line(int argc, VALUE *argv, VALUE io)
{
VALUE str;
struct getline_arg args;
RETURN_ENUMERATOR(io, argc, argv);
prepare_getline_args(argc, argv, &args, io);
if (args.limit == 0)
rb_raise(rb_eArgError, "invalid limit: 0 for each_line");
while (!NIL_P(str = rb_io_getline_1(args.rs, args.limit, args.chomp, io))) {
rb_yield(str);
}
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#each_byte;F;7[ ;[[@Ti;T;:each_byte;0; [ ; { ; IC; "vCalls the given block once for each byte (0..255) in ios,
passing the byte as an argument. The stream must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
checksum = 0
f.each_byte {|x| checksum ^= x } #=> #
checksum #=> 12
;T; [o;=
;>I"
overload;F;?0;;y;@0;:I"each_byte;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I" byte;T;$@3Ro;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@3R;![ ;"I" @yield [byte]
@return [IO];T;#0;$@3R;.F;Bi ;C0;7[ ;$@3Ro;=
;>I"
overload;F;?0;;y;@0;:I"each_byte;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@3R;.F;Bi ;C0;7[ ;$@3R;![ ;"I"Calls the given block once for each byte (0..255) in ios,
passing the byte as an argument. The stream must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
checksum = 0
f.each_byte {|x| checksum ^= x } #=> #
checksum #=> 12
@overload each_byte
@yield [byte]
@return [IO]
@overload each_byte;T;#0;$@3R;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_each_byte(VALUE io)
{
rb_io_t *fptr;
RETURN_ENUMERATOR(io, 0, 0);
GetOpenFile(io, fptr);
do {
while (fptr->rbuf.len > 0) {
char *p = fptr->rbuf.ptr + fptr->rbuf.off++;
fptr->rbuf.len--;
rb_yield(INT2FIX(*p & 0xff));
rb_io_check_byte_readable(fptr);
errno = 0;
}
READ_CHECK(fptr);
} while (io_fillbuf(fptr) >= 0);
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#each_char;F;7[ ;[[@Ti);T;:each_char;0; [ ; { ; IC; "9Calls the given block once for each character in ios,
passing the character as an argument. The stream must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
f.each_char {|c| print c, ' ' } #=> #
;T; [o;=
;>I"
overload;F;?0;;z;@0;:I"each_char;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"c;T;$@[Ro;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@[R;![ ;"I" @yield [c]
@return [IO];T;#0;$@[R;.F;Bi ;C0;7[ ;$@[Ro;=
;>I"
overload;F;?0;;z;@0;:I"each_char;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@[R;.F;Bi ;C0;7[ ;$@[R;![ ;"I"Calls the given block once for each character in ios,
passing the character as an argument. The stream must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
f = File.new("testfile")
f.each_char {|c| print c, ' ' } #=> #
@overload each_char
@yield [c]
@return [IO]
@overload each_char;T;#0;$@[R;.F;/o;0;1T;2i;3i';%@kL;9I"Sstatic VALUE
rb_io_each_char(VALUE io)
{
rb_io_t *fptr;
rb_encoding *enc;
VALUE c;
RETURN_ENUMERATOR(io, 0, 0);
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
enc = io_input_encoding(fptr);
READ_CHECK(fptr);
while (!NIL_P(c = io_getc(fptr, enc))) {
rb_yield(c);
}
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#each_codepoint;F;7[ ;[[@TiI;T;:each_codepoint;0; [ ; { ; IC; "Passes the Integer ordinal of each character in ios,
passing the codepoint as an argument. The stream must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
;T; [o;=
;>I"
overload;F;?0;;{;@0;:I"each_codepoint;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"c;T;$@Ro;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@R;![ ;"I" @yield [c]
@return [IO];T;#0;$@R;.F;Bi ;C0;7[ ;$@Ro;=
;>I"
overload;F;?0;;{;@0;:I"each_codepoint;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@R;.F;Bi ;C0;7[ ;$@R;![ ;"I"0Passes the Integer ordinal of each character in ios,
passing the codepoint as an argument. The stream must be opened for
reading or an IOError will be raised.
If no block is given, an enumerator is returned instead.
@overload each_codepoint
@yield [c]
@return [IO]
@overload each_codepoint;T;#0;$@R;.F;/o;0;1T;2i<;3iG;%@kL;9I"$ static VALUE
rb_io_each_codepoint(VALUE io)
{
rb_io_t *fptr;
rb_encoding *enc;
unsigned int c;
int r, n;
RETURN_ENUMERATOR(io, 0, 0);
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
READ_CHECK(fptr);
if (NEED_READCONV(fptr)) {
SET_BINARY_MODE(fptr);
r = 1; /* no invalid char yet */
for (;;) {
make_readconv(fptr, 0);
for (;;) {
if (fptr->cbuf.len) {
if (fptr->encs.enc)
r = rb_enc_precise_mbclen(fptr->cbuf.ptr+fptr->cbuf.off,
fptr->cbuf.ptr+fptr->cbuf.off+fptr->cbuf.len,
fptr->encs.enc);
else
r = ONIGENC_CONSTRUCT_MBCLEN_CHARFOUND(1);
if (!MBCLEN_NEEDMORE_P(r))
break;
if (fptr->cbuf.len == fptr->cbuf.capa) {
rb_raise(rb_eIOError, "too long character");
}
}
if (more_char(fptr) == MORE_CHAR_FINISHED) {
clear_readconv(fptr);
if (!MBCLEN_CHARFOUND_P(r)) {
enc = fptr->encs.enc;
goto invalid;
}
return io;
}
}
if (MBCLEN_INVALID_P(r)) {
enc = fptr->encs.enc;
goto invalid;
}
n = MBCLEN_CHARFOUND_LEN(r);
if (fptr->encs.enc) {
c = rb_enc_codepoint(fptr->cbuf.ptr+fptr->cbuf.off,
fptr->cbuf.ptr+fptr->cbuf.off+fptr->cbuf.len,
fptr->encs.enc);
}
else {
c = (unsigned char)fptr->cbuf.ptr[fptr->cbuf.off];
}
fptr->cbuf.off += n;
fptr->cbuf.len -= n;
rb_yield(UINT2NUM(c));
rb_io_check_byte_readable(fptr);
}
}
NEED_NEWLINE_DECORATOR_ON_READ_CHECK(fptr);
enc = io_input_encoding(fptr);
while (io_fillbuf(fptr) >= 0) {
r = rb_enc_precise_mbclen(fptr->rbuf.ptr+fptr->rbuf.off,
fptr->rbuf.ptr+fptr->rbuf.off+fptr->rbuf.len, enc);
if (MBCLEN_CHARFOUND_P(r) &&
(n = MBCLEN_CHARFOUND_LEN(r)) <= fptr->rbuf.len) {
c = rb_enc_codepoint(fptr->rbuf.ptr+fptr->rbuf.off,
fptr->rbuf.ptr+fptr->rbuf.off+fptr->rbuf.len, enc);
fptr->rbuf.off += n;
fptr->rbuf.len -= n;
rb_yield(UINT2NUM(c));
}
else if (MBCLEN_INVALID_P(r)) {
goto invalid;
}
else if (MBCLEN_NEEDMORE_P(r)) {
char cbuf[8], *p = cbuf;
int more = MBCLEN_NEEDMORE_LEN(r);
if (more > numberof(cbuf)) goto invalid;
more += n = fptr->rbuf.len;
if (more > numberof(cbuf)) goto invalid;
while ((n = (int)read_buffered_data(p, more, fptr)) > 0 &&
(p += n, (more -= n) > 0)) {
if (io_fillbuf(fptr) < 0) goto invalid;
if ((n = fptr->rbuf.len) > more) n = more;
}
r = rb_enc_precise_mbclen(cbuf, p, enc);
if (!MBCLEN_CHARFOUND_P(r)) goto invalid;
c = rb_enc_codepoint(cbuf, p, enc);
rb_yield(UINT2NUM(c));
}
else {
continue;
}
rb_io_check_byte_readable(fptr);
}
return io;
invalid:
rb_raise(rb_eArgError, "invalid byte sequence in %s", rb_enc_name(enc));
UNREACHABLE_RETURN(Qundef);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#syswrite;F;7[[I"str;T0;[[@Ti;T;:
syswrite;0; [ ; { ; IC; ""Writes the given string to ios using a low-level write.
Returns the number of bytes written. Do not mix with other methods
that write to ios or you may get unpredictable results.
Raises SystemCallError on error.
f = File.new("out", "w")
f.syswrite("ABCDEF") #=> 6
;T; [o;=
;>I"
overload;F;?0;;|;@0;:I"syswrite(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@R;![ ;"I"@return [Integer];T;#0;$@R;.F;Bi ;C0;7[[I" string;T0;$@R;![ ;"I"SWrites the given string to ios using a low-level write.
Returns the number of bytes written. Do not mix with other methods
that write to ios or you may get unpredictable results.
Raises SystemCallError on error.
f = File.new("out", "w")
f.syswrite("ABCDEF") #=> 6
@overload syswrite(string)
@return [Integer];T;#0;$@R;.F;/o;0;1T;2iv;3i;%@kL;9I"Cstatic VALUE
rb_io_syswrite(VALUE io, VALUE str)
{
VALUE tmp;
rb_io_t *fptr;
long n, len;
const char *ptr;
if (!RB_TYPE_P(str, T_STRING))
str = rb_obj_as_string(str);
io = GetWriteIO(io);
GetOpenFile(io, fptr);
rb_io_check_writable(fptr);
if (fptr->wbuf.len) {
rb_warn("syswrite for buffered IO");
}
tmp = rb_str_tmp_frozen_acquire(str);
RSTRING_GETMEM(tmp, ptr, len);
n = rb_write_internal(fptr, ptr, len);
if (n < 0) rb_sys_fail_path(fptr->pathv);
rb_str_tmp_frozen_release(str, tmp);
return LONG2FIX(n);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#sysread;F;7[[@90;[[@Ti;T;: sysread;0; [ ; { ; IC; " Reads maxlen bytes from ios using a low-level
read and returns them as a string. Do not mix with other methods
that read from ios or you may get unpredictable results.
If the optional _outbuf_ argument is present,
it must reference a String, which will receive the data.
The _outbuf_ will contain only the received data after the method call
even if it is not empty at the beginning.
Raises SystemCallError on error and EOFError at end of file.
f = File.new("testfile")
f.sysread(16) #=> "This is line one"
;T; [o;=
;>I"
overload;F;?0;;};@0;:I" sysread(maxlen[, outbuf]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@R;![ ;"I"@return [String];T;#0;$@R;.F;Bi ;C0;7[[I"maxlen[, outbuf];T0;$@R;![ ;"I"XReads maxlen bytes from ios using a low-level
read and returns them as a string. Do not mix with other methods
that read from ios or you may get unpredictable results.
If the optional _outbuf_ argument is present,
it must reference a String, which will receive the data.
The _outbuf_ will contain only the received data after the method call
even if it is not empty at the beginning.
Raises SystemCallError on error and EOFError at end of file.
f = File.new("testfile")
f.sysread(16) #=> "This is line one"
@overload sysread(maxlen[, outbuf])
@return [String];T;#0;$@R;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_sysread(int argc, VALUE *argv, VALUE io)
{
VALUE len, str;
rb_io_t *fptr;
long n, ilen;
struct io_internal_read_struct iis;
int shrinkable;
rb_scan_args(argc, argv, "11", &len, &str);
ilen = NUM2LONG(len);
shrinkable = io_setstrbuf(&str, ilen);
if (ilen == 0) return str;
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
if (READ_DATA_BUFFERED(fptr)) {
rb_raise(rb_eIOError, "sysread for buffered IO");
}
rb_io_check_closed(fptr);
io_setstrbuf(&str, ilen);
iis.th = rb_thread_current();
iis.fptr = fptr;
iis.nonblock = 0;
iis.buf = RSTRING_PTR(str);
iis.capa = ilen;
n = read_internal_locktmp(str, &iis);
if (n < 0) {
rb_sys_fail_path(fptr->pathv);
}
io_set_read_length(str, n, shrinkable);
if (n == 0 && ilen > 0) {
rb_eof_error();
}
return str;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#pread;F;7[[@90;[[@Ti
;T;:
pread;0; [ ; { ; IC; "Reads maxlen bytes from ios using the pread system call
and returns them as a string without modifying the underlying
descriptor offset. This is advantageous compared to combining IO#seek
and IO#read in that it is atomic, allowing multiple threads/process to
share the same IO object for reading the file at various locations.
This bypasses any userspace buffering of the IO layer.
If the optional outbuf argument is present, it must
reference a String, which will receive the data.
Raises SystemCallError on error, EOFError at end of file and
NotImplementedError if platform does not implement the system call.
File.write("testfile", "This is line one\nThis is line two\n")
File.open("testfile") do |f|
p f.read # => "This is line one\nThis is line two\n"
p f.pread(12, 0) # => "This is line"
p f.pread(9, 8) # => "line one\n"
end
;T; [o;=
;>I"
overload;F;?0;;~;@0;:I"$pread(maxlen, offset[, outbuf]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@R;![ ;"I"@return [String];T;#0;$@R;.F;Bi ;C0;7[[I" maxlen;T0[I"offset[, outbuf];T0;$@R;![ ;"I"Reads maxlen bytes from ios using the pread system call
and returns them as a string without modifying the underlying
descriptor offset. This is advantageous compared to combining IO#seek
and IO#read in that it is atomic, allowing multiple threads/process to
share the same IO object for reading the file at various locations.
This bypasses any userspace buffering of the IO layer.
If the optional outbuf argument is present, it must
reference a String, which will receive the data.
Raises SystemCallError on error, EOFError at end of file and
NotImplementedError if platform does not implement the system call.
File.write("testfile", "This is line one\nThis is line two\n")
File.open("testfile") do |f|
p f.read # => "This is line one\nThis is line two\n"
p f.pread(12, 0) # => "This is line"
p f.pread(9, 8) # => "line one\n"
end
@overload pread(maxlen, offset[, outbuf])
@return [String];T;#0;$@R;.F;/o;0;1T;2i;3i ;%@kL;9I"?static VALUE
rb_io_pread(int argc, VALUE *argv, VALUE io)
{
VALUE len, offset, str;
rb_io_t *fptr;
ssize_t n;
struct prdwr_internal_arg arg;
int shrinkable;
rb_scan_args(argc, argv, "21", &len, &offset, &str);
arg.count = NUM2SIZET(len);
arg.offset = NUM2OFFT(offset);
shrinkable = io_setstrbuf(&str, (long)arg.count);
if (arg.count == 0) return str;
arg.buf = RSTRING_PTR(str);
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
arg.fd = fptr->fd;
rb_io_check_closed(fptr);
rb_str_locktmp(str);
n = (ssize_t)rb_ensure(pread_internal_call, (VALUE)&arg, rb_str_unlocktmp, str);
if (n < 0) {
rb_sys_fail_path(fptr->pathv);
}
io_set_read_length(str, n, shrinkable);
if (n == 0 && arg.count > 0) {
rb_eof_error();
}
return str;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#pwrite;F;7[[I"str;T0[I" offset;T0;[[@TiQ;T;: pwrite;0; [ ; { ; IC; "WWrites the given string to ios at offset using pwrite()
system call. This is advantageous to combining IO#seek and IO#write
in that it is atomic, allowing multiple threads/process to share the
same IO object for reading the file at various locations.
This bypasses any userspace buffering of the IO layer.
Returns the number of bytes written.
Raises SystemCallError on error and NotImplementedError
if platform does not implement the system call.
File.open("out", "w") do |f|
f.pwrite("ABCDEF", 3) #=> 6
end
File.read("out") #=> "\u0000\u0000\u0000ABCDEF"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"pwrite(string, offset);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@S;![ ;"I"@return [Integer];T;#0;$@S;.F;Bi ;C0;7[[I" string;T0[I" offset;T0;$@S;![ ;"I"Writes the given string to ios at offset using pwrite()
system call. This is advantageous to combining IO#seek and IO#write
in that it is atomic, allowing multiple threads/process to share the
same IO object for reading the file at various locations.
This bypasses any userspace buffering of the IO layer.
Returns the number of bytes written.
Raises SystemCallError on error and NotImplementedError
if platform does not implement the system call.
File.open("out", "w") do |f|
f.pwrite("ABCDEF", 3) #=> 6
end
File.read("out") #=> "\u0000\u0000\u0000ABCDEF"
@overload pwrite(string, offset)
@return [Integer];T;#0;$@S;.F;/o;0;1T;2i>;3iO;%@kL;9I"static VALUE
rb_io_pwrite(VALUE io, VALUE str, VALUE offset)
{
rb_io_t *fptr;
ssize_t n;
struct prdwr_internal_arg arg;
VALUE tmp;
if (!RB_TYPE_P(str, T_STRING))
str = rb_obj_as_string(str);
arg.offset = NUM2OFFT(offset);
io = GetWriteIO(io);
GetOpenFile(io, fptr);
rb_io_check_writable(fptr);
arg.fd = fptr->fd;
tmp = rb_str_tmp_frozen_acquire(str);
arg.buf = RSTRING_PTR(tmp);
arg.count = (size_t)RSTRING_LEN(tmp);
n = (ssize_t)rb_thread_io_blocking_region(internal_pwrite_func, &arg, fptr->fd);
if (n < 0) rb_sys_fail_path(fptr->pathv);
rb_str_tmp_frozen_release(str, tmp);
return SSIZET2NUM(n);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#fileno;F;7[ ;[[@TiR
;T;: fileno;0; [ ; { ; IC; "Returns the integer file descriptor for the stream:
$stdin.fileno # => 0
$stdout.fileno # => 1
$stderr.fileno # => 2
File.open('t.txt').fileno # => 10
IO#to_i is an alias for IO#fileno.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" fileno;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@+S;![ ;"I"@return [Integer];T;#0;$@+S;.F;Bi ;C0;7[ ;$@+S;![ ;"I"
Returns the integer file descriptor for the stream:
$stdin.fileno # => 0
$stdout.fileno # => 1
$stderr.fileno # => 2
File.open('t.txt').fileno # => 10
IO#to_i is an alias for IO#fileno.
@overload fileno
@return [Integer];T;#0;$o;4;5F;6;;; ;&I" IO#to_i;F;7[ ;[[@Ti7;F;: to_i;;; [ ; { ; @2S;%@kL;9I"static VALUE
rb_io_fileno(VALUE io)
{
rb_io_t *fptr = RFILE(io)->fptr;
int fd;
rb_io_check_closed(fptr);
fd = fptr->fd;
return INT2FIX(fd);
};T;:I"static VALUE;T;.F;/o;0;1T;2iC
;3iO
;%@kL;9I"static VALUE
rb_io_fileno(VALUE io)
{
rb_io_t *fptr = RFILE(io)->fptr;
int fd;
rb_io_check_closed(fptr);
fd = fptr->fd;
return INT2FIX(fd);
};T;:@KS;;T@CSo;4;5F;6;;; ;&I"
IO#to_io;F;7[ ;[[@Ti
;T;:
to_io;0; [ ; { ; IC; "Returns +self+.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
to_io;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@NS;![ ;"I"@return [self];T;#0;$@NS;.F;Bi ;C0;7[ ;$@NS;![ ;"I"8Returns +self+.
@overload to_io
@return [self];T;#0;$@NS;.F;/o;0;1T;2i
;3i
;%@kL;9I":static VALUE
rb_io_to_io(VALUE io)
{
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#fsync;F;7[ ;[[@Ti ;T;:
fsync;0; [ ; { ; IC; "Immediately writes to disk all data buffered in the stream,
via the operating system's fsync(2).
Note this difference:
- IO#sync=: Ensures that data is flushed from the stream's internal buffers,
but does not guarantee that the operating system actually writes the data to disk.
- IO#fsync: Ensures both that data is flushed from internal buffers,
and that data is written to disk.
Raises an exception if the operating system does not support fsync(2).
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
fsync;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"0;T;$@iS;![ ;"I"@return [0];T;#0;$@iS;.F;Bi ;C0;7[ ;$@iS;![ ;"I"Immediately writes to disk all data buffered in the stream,
via the operating system's fsync(2).
Note this difference:
- IO#sync=: Ensures that data is flushed from the stream's internal buffers,
but does not guarantee that the operating system actually writes the data to disk.
- IO#fsync: Ensures both that data is flushed from internal buffers,
and that data is written to disk.
Raises an exception if the operating system does not support fsync(2).
@overload fsync
@return [0];T;#0;$@iS;.F;/o;0;1T;2i ;3i ;%@kL;9I"3static VALUE
rb_io_fsync(VALUE io)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
if (io_fflush(fptr) < 0)
rb_sys_fail_on_write(fptr);
if ((int)rb_thread_io_blocking_region(nogvl_fsync, fptr, fptr->fd) < 0)
rb_sys_fail_path(fptr->pathv);
return INT2FIX(0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#fdatasync;F;7[ ;[[@Ti.
;T;:fdatasync;0; [ ; { ; IC; "Immediately writes to disk all data buffered in the stream,
via the operating system's: fdatasync(2), if supported,
otherwise via fsync(2), if supported;
otherwise raises an exception.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"fdatasync;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"0;T;$@S;![ ;"I"@return [0];T;#0;$@S;.F;Bi ;C0;7[ ;$@S;![ ;"I"Immediately writes to disk all data buffered in the stream,
via the operating system's: fdatasync(2), if supported,
otherwise via fsync(2), if supported;
otherwise raises an exception.
@overload fdatasync
@return [0];T;#0;$@S;.F;/o;0;1T;2i#
;3i+
;%@kL;9I"Kstatic VALUE
rb_io_fdatasync(VALUE io)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
if (io_fflush(fptr) < 0)
rb_sys_fail_on_write(fptr);
if ((int)rb_thread_io_blocking_region(nogvl_fdatasync, fptr, fptr->fd) == 0)
return INT2FIX(0);
/* fall back */
return rb_io_fsync(io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#sync;F;7[ ;[[@Ti ;T;: sync;0; [ ; { ; IC; "Returns the current sync mode of the stream.
When sync mode is true, all output is immediately flushed to the underlying
operating system and is not buffered by Ruby internally. See also #fsync.
f = File.open('t.tmp', 'w')
f.sync # => false
f.sync = true
f.sync # => true
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" sync;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@S;![ ;"I"@return [Boolean];T;#0;$@S;.F;Bi ;C0;7[ ;$@S;![ ;"I">Returns the current sync mode of the stream.
When sync mode is true, all output is immediately flushed to the underlying
operating system and is not buffered by Ruby internally. See also #fsync.
f = File.open('t.tmp', 'w')
f.sync # => false
f.sync = true
f.sync # => true
@overload sync
@return [Boolean];T;#0;$@S;.F;/o;0;1T;2i ;3i ;%@kL;9I"static VALUE
rb_io_sync(VALUE io)
{
rb_io_t *fptr;
io = GetWriteIO(io);
GetOpenFile(io, fptr);
return RBOOL(fptr->mode & FMODE_SYNC);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#sync=;F;7[[I" sync;T0;[[@Ti
;T;:
sync=;0; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@S;%@kL;9I"bstatic VALUE
rb_io_set_sync(VALUE io, VALUE sync)
{
rb_notimplement();
UNREACHABLE;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#lineno;F;7[ ;[[@Ti;T;;L;0; [ ; { ; IC; ">Returns the current line number in ios. The stream must be
opened for reading. #lineno counts the number of times #gets is called
rather than the number of newlines encountered. The two values will
differ if #gets is called with a separator other than newline.
Methods that use
b = f.getbyte #=> 0x38
f.ungetbyte(b) #=> nil
f.getbyte #=> 0x38
If given an integer, only uses the lower 8 bits of the integer as the byte
to push.
f = File.new("testfile") #=> #
f.ungetbyte(0x102) #=> nil
f.getbyte #=> 0x2
Calling this method prepends to the existing buffer, even if the method
has already been called previously:
f = File.new("testfile") #=> #
f.ungetbyte("ab") #=> nil
f.ungetbyte("cd") #=> nil
f.read(5) #=> "cdab8"
Has no effect with unbuffered reads (such as IO#sysread).
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"ungetbyte(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@U;![ ;"I"@return [nil];T;#0;$@U;.F;Bi ;C0;7[[I" string;T0;$@Uo;=
;>I"
overload;F;?0;;;@0;:I"ungetbyte(integer);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@U;![ ;"I"@return [nil];T;#0;$@U;.F;Bi ;C0;7[[I" integer;T0;$@U;![ ;"I"Pushes back bytes (passed as a parameter) onto ios,
such that a subsequent buffered read will return it.
It is only guaranteed to support a single byte, and only if ungetbyte
or ungetc has not already been called on ios since the previous
read of at least a single byte from ios.
However, it can support additional bytes if there is space in the
internal buffer to allow for it.
f = File.new("testfile") #=> #
b = f.getbyte #=> 0x38
f.ungetbyte(b) #=> nil
f.getbyte #=> 0x38
If given an integer, only uses the lower 8 bits of the integer as the byte
to push.
f = File.new("testfile") #=> #
f.ungetbyte(0x102) #=> nil
f.getbyte #=> 0x2
Calling this method prepends to the existing buffer, even if the method
has already been called previously:
f = File.new("testfile") #=> #
f.ungetbyte("ab") #=> nil
f.ungetbyte("cd") #=> nil
f.read(5) #=> "cdab8"
Has no effect with unbuffered reads (such as IO#sysread).
@overload ungetbyte(string)
@return [nil]
@overload ungetbyte(integer)
@return [nil];T;#0;$@U;.F;/o;0;1T;2i;3i=;%@kL;9I"VALUE
rb_io_ungetbyte(VALUE io, VALUE b)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
switch (TYPE(b)) {
case T_NIL:
return Qnil;
case T_FIXNUM:
case T_BIGNUM: ;
VALUE v = rb_int_modulo(b, INT2FIX(256));
unsigned char c = NUM2INT(v) & 0xFF;
b = rb_str_new((const char *)&c, 1);
break;
default:
SafeStringValue(b);
}
io_ungetbyte(b, fptr);
return Qnil;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO#ungetc;F;7[[I"c;T0;[[@Tiv;T;: ungetc;0; [ ; { ; IC; "Pushes back characters (passed as a parameter) onto ios,
such that a subsequent buffered read will return it.
It is only guaranteed to support a single byte, and only if ungetbyte
or ungetc has not already been called on ios since the previous
read of at least a single byte from ios.
However, it can support additional bytes if there is space in the
internal buffer to allow for it.
f = File.new("testfile") #=> #
c = f.getc #=> "8"
f.ungetc(c) #=> nil
f.getc #=> "8"
If given an integer, the integer must represent a valid codepoint in the
external encoding of ios.
Calling this method prepends to the existing buffer, even if the method
has already been called previously:
f = File.new("testfile") #=> #
f.ungetc("ab") #=> nil
f.ungetc("cd") #=> nil
f.read(5) #=> "cdab8"
Has no effect with unbuffered reads (such as IO#sysread).
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"ungetc(integer);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@U;![ ;"I"@return [nil];T;#0;$@U;.F;Bi ;C0;7[[I" integer;T0;$@Uo;=
;>I"
overload;F;?0;;;@0;:I"ungetc(string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@U;![ ;"I"@return [nil];T;#0;$@U;.F;Bi ;C0;7[[I" string;T0;$@U;![ ;"I"TPushes back characters (passed as a parameter) onto ios,
such that a subsequent buffered read will return it.
It is only guaranteed to support a single byte, and only if ungetbyte
or ungetc has not already been called on ios since the previous
read of at least a single byte from ios.
However, it can support additional bytes if there is space in the
internal buffer to allow for it.
f = File.new("testfile") #=> #
c = f.getc #=> "8"
f.ungetc(c) #=> nil
f.getc #=> "8"
If given an integer, the integer must represent a valid codepoint in the
external encoding of ios.
Calling this method prepends to the existing buffer, even if the method
has already been called previously:
f = File.new("testfile") #=> #
f.ungetc("ab") #=> nil
f.ungetc("cd") #=> nil
f.read(5) #=> "cdab8"
Has no effect with unbuffered reads (such as IO#sysread).
@overload ungetc(integer)
@return [nil]
@overload ungetc(string)
@return [nil];T;#0;$@U;.F;/o;0;1T;2iV;3it;%@kL;9I"VALUE
rb_io_ungetc(VALUE io, VALUE c)
{
rb_io_t *fptr;
long len;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
if (FIXNUM_P(c)) {
c = rb_enc_uint_chr(FIX2UINT(c), io_read_encoding(fptr));
}
else if (RB_BIGNUM_TYPE_P(c)) {
c = rb_enc_uint_chr(NUM2UINT(c), io_read_encoding(fptr));
}
else {
SafeStringValue(c);
}
if (NEED_READCONV(fptr)) {
SET_BINARY_MODE(fptr);
len = RSTRING_LEN(c);
#if SIZEOF_LONG > SIZEOF_INT
if (len > INT_MAX)
rb_raise(rb_eIOError, "ungetc failed");
#endif
make_readconv(fptr, (int)len);
if (fptr->cbuf.capa - fptr->cbuf.len < len)
rb_raise(rb_eIOError, "ungetc failed");
if (fptr->cbuf.off < len) {
MEMMOVE(fptr->cbuf.ptr+fptr->cbuf.capa-fptr->cbuf.len,
fptr->cbuf.ptr+fptr->cbuf.off,
char, fptr->cbuf.len);
fptr->cbuf.off = fptr->cbuf.capa-fptr->cbuf.len;
}
fptr->cbuf.off -= (int)len;
fptr->cbuf.len += (int)len;
MEMMOVE(fptr->cbuf.ptr+fptr->cbuf.off, RSTRING_PTR(c), char, len);
}
else {
NEED_NEWLINE_DECORATOR_ON_READ_CHECK(fptr);
io_ungetbyte(c, fptr);
}
return Qnil;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"
IO#<<;F;7[[I"str;T0;[[@Ti=;T;;;0; [ ; { ; IC; "9Writes the given +object+ to +self+,
which must be opened for writing (see {Modes}[#class-IO-label-Modes]);
returns +self+;
if +object+ is not a string, it is converted via method +to_s+:
$stdout << 'Hello' << ', ' << 'World!' << "\n"
$stdout << 'foo' << :bar << 2 << "\n"
Output:
Hello, World!
foobar2
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"<<(object);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@ V;![ ;"I"@return [self];T;#0;$@ V;.F;Bi ;C0;7[[I" object;T0;$@ V;![ ;"I"bWrites the given +object+ to +self+,
which must be opened for writing (see {Modes}[#class-IO-label-Modes]);
returns +self+;
if +object+ is not a string, it is converted via method +to_s+:
$stdout << 'Hello' << ', ' << 'World!' << "\n"
$stdout << 'foo' << :bar << 2 << "\n"
Output:
Hello, World!
foobar2
@overload <<(object)
@return [self];T;#0;$@ V;.F;/o;0;1T;2i);3i9;%@kL;9I"YVALUE
rb_io_addstr(VALUE io, VALUE str)
{
rb_io_write(io, str);
return io;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"
IO#flush;F;7[ ;[[@Tiu;T;:
flush;0; [ ; { ; IC; "Flushes data buffered in +self+ to the operating system
(but does not necessarily flush data buffered in the operating system):
$stdout.print 'no newline' # Not necessarily flushed.
$stdout.flush # Flushed.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
flush;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" self;T;$@+V;![ ;"I"@return [self];T;#0;$@+V;.F;Bi ;C0;7[ ;$@+V;![ ;"I"Flushes data buffered in +self+ to the operating system
(but does not necessarily flush data buffered in the operating system):
$stdout.print 'no newline' # Not necessarily flushed.
$stdout.flush # Flushed.
@overload flush
@return [self];T;#0;$@+V;.F;/o;0;1T;2ii;3ir;%@kL;9I"GVALUE
rb_io_flush(VALUE io)
{
return rb_io_flush_raw(io, 1);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" IO#tell;F;7[ ;[[@Ti;T;: tell;0; [ ; { ; IC; "Returns the current position (in bytes) in +self+
(see {Position}[#class-IO-label-Position]):
f = File.new('t.txt')
f.tell # => 0
f.readline # => "This is line one.\n"
f.tell # => 19
Related: IO#pos=, IO#seek.
IO#pos is an alias for IO#tell.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" tell;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@FV;![ ;"I"@return [Integer];T;#0;$@FV;.F;Bi ;C0;7[ ;$@FV;![ ;"I"*Returns the current position (in bytes) in +self+
(see {Position}[#class-IO-label-Position]):
f = File.new('t.txt')
f.tell # => 0
f.readline # => "This is line one.\n"
f.tell # => 19
Related: IO#pos=, IO#seek.
IO#pos is an alias for IO#tell.
@overload tell
@return [Integer];T;#0;$@FV;.F;/o;0;1T;2i{;3i;%@kL;9I"static VALUE
rb_io_tell(VALUE io)
{
rb_io_t *fptr;
off_t pos;
GetOpenFile(io, fptr);
pos = io_tell(fptr);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
pos -= fptr->rbuf.len;
return OFFT2NUM(pos);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#seek;F;7[[@90;[[@Ti;T;: seek;0; [ ; { ; IC; ""Seeks to the position given by integer +offset+
(see {Position}[#class-IO-label-Position])
and constant +whence+, which is one of:
- +:CUR+ or IO::SEEK_CUR:
Repositions the stream to its current position plus the given +offset+:
f = File.open('t.txt')
f.tell # => 0
f.seek(20, :CUR) # => 0
f.tell # => 20
f.seek(-10, :CUR) # => 0
f.tell # => 10
- +:END+ or IO::SEEK_END:
Repositions the stream to its end plus the given +offset+:
f = File.open('t.txt')
f.tell # => 0
f.seek(0, :END) # => 0 # Repositions to stream end.
f.tell # => 70
f.seek(-20, :END) # => 0
f.tell # => 50
f.seek(-40, :END) # => 0
f.tell # => 30
- +:SET+ or IO:SEEK_SET:
Repositions the stream to the given +offset+:
f = File.open('t.txt')
f.tell # => 0
f.seek(20, :SET) # => 0
f.tell # => 20
f.seek(40, :SET) # => 0
f.tell # => 40
Related: IO#pos=, IO#tell.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"(seek(offset, whence = IO::SEEK_SET);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"0;T;$@aV;![ ;"I"@return [0];T;#0;$@aV;.F;Bi ;C0;7[[I" offset;T0[I" whence;TI"IO::SEEK_SET;T;$@aV;![ ;"I"aSeeks to the position given by integer +offset+
(see {Position}[#class-IO-label-Position])
and constant +whence+, which is one of:
- +:CUR+ or IO::SEEK_CUR:
Repositions the stream to its current position plus the given +offset+:
f = File.open('t.txt')
f.tell # => 0
f.seek(20, :CUR) # => 0
f.tell # => 20
f.seek(-10, :CUR) # => 0
f.tell # => 10
- +:END+ or IO::SEEK_END:
Repositions the stream to its end plus the given +offset+:
f = File.open('t.txt')
f.tell # => 0
f.seek(0, :END) # => 0 # Repositions to stream end.
f.tell # => 70
f.seek(-20, :END) # => 0
f.tell # => 50
f.seek(-40, :END) # => 0
f.tell # => 30
- +:SET+ or IO:SEEK_SET:
Repositions the stream to the given +offset+:
f = File.open('t.txt')
f.tell # => 0
f.seek(20, :SET) # => 0
f.tell # => 20
f.seek(40, :SET) # => 0
f.tell # => 40
Related: IO#pos=, IO#tell.
@overload seek(offset, whence = IO::SEEK_SET)
@return [0];T;#0;$@aV;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_seek_m(int argc, VALUE *argv, VALUE io)
{
VALUE offset, ptrname;
int whence = SEEK_SET;
if (rb_scan_args(argc, argv, "11", &offset, &ptrname) == 2) {
whence = interpret_seek_whence(ptrname);
}
return rb_io_seek(io, offset, whence);
};T;:I"static VALUE;T;;To;u;[[@Ti7;F;:
SEEK_SET;;w;; ; [ ; { ; IC; "(Set I/O position from the beginning
;T; [ ;![ ;"I"(Set I/O position from the beginning;T;#0;$@V;.F;/o;0;1T;2i7;3i7;%@kL;&I"IO::SEEK_SET;F;xI"INT2FIX(SEEK_SET);To;u;[[@Ti7;F;:
SEEK_CUR;;w;; ; [ ; { ; IC; "/Set I/O position from the current position
;T; [ ;![ ;"I"/Set I/O position from the current position;T;#0;$@V;.F;/o;0;1T;2i7;3i7;%@kL;&I"IO::SEEK_CUR;F;xI"INT2FIX(SEEK_CUR);To;u;[[@Ti7;F;:
SEEK_END;;w;; ; [ ; { ; IC; ""Set I/O position from the end
;T; [ ;![ ;"I""Set I/O position from the end;T;#0;$@V;.F;/o;0;1T;2i7;3i7;%@kL;&I"IO::SEEK_END;F;xI"INT2FIX(SEEK_END);To;u;[[@Ti7;F;:SEEK_DATA;;w;; ; [ ; { ; IC; ":Set I/O position to the next location containing data
;T; [ ;![ ;"I":Set I/O position to the next location containing data;T;#0;$@V;.F;/o;0;1T;2i7;3i7;%@kL;&I"IO::SEEK_DATA;F;xI"INT2FIX(SEEK_DATA);To;u;[[@Ti7;F;:SEEK_HOLE;;w;; ; [ ; { ; IC; "&Set I/O position to the next hole
;T; [ ;![ ;"I"&Set I/O position to the next hole;T;#0;$@V;.F;/o;0;1T;2i7;3i7;%@kL;&I"IO::SEEK_HOLE;F;xI"INT2FIX(SEEK_HOLE);To;4;5F;6;;; ;&I"IO#rewind;F;7[ ;[[@Ti, ;T;: rewind;0; [ ; { ; IC; "Repositions the stream to its beginning,
setting both the position and the line number to zero;
see {Position}[#class-IO-label-Position]
and {Line Number}[#class-IO-label-Line+Number]:
f = File.open('t.txt')
f.tell # => 0
f.lineno # => 0
f.readline # => "This is line one.\n"
f.tell # => 19
f.lineno # => 1
f.rewind # => 0
f.tell # => 0
f.lineno # => 0
Note that this method cannot be used with streams such as pipes, ttys, and sockets.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" rewind;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"0;T;$@V;![ ;"I"@return [0];T;#0;$@V;.F;Bi ;C0;7[ ;$@V;![ ;"I"Repositions the stream to its beginning,
setting both the position and the line number to zero;
see {Position}[#class-IO-label-Position]
and {Line Number}[#class-IO-label-Line+Number]:
f = File.open('t.txt')
f.tell # => 0
f.lineno # => 0
f.readline # => "This is line one.\n"
f.tell # => 19
f.lineno # => 1
f.rewind # => 0
f.tell # => 0
f.lineno # => 0
Note that this method cannot be used with streams such as pipes, ttys, and sockets.
@overload rewind
@return [0];T;#0;$@V;.F;/o;0;1T;2i ;3i) ;%@kL;9I"Lstatic VALUE
rb_io_rewind(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (io_seek(fptr, 0L, 0) < 0 && errno) rb_sys_fail_path(fptr->pathv);
if (io == ARGF.current_file) {
ARGF.lineno -= fptr->lineno;
}
fptr->lineno = 0;
if (fptr->readconv) {
clear_readconv(fptr);
}
return INT2FIX(0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#pos;F;7[ ;[[@Ti;T;;;0; [ ; { ; IC; "Returns the current position (in bytes) in +self+
(see {Position}[#class-IO-label-Position]):
f = File.new('t.txt')
f.tell # => 0
f.readline # => "This is line one.\n"
f.tell # => 19
Related: IO#pos=, IO#seek.
IO#pos is an alias for IO#tell.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" tell;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@V;![ ;"I"@return [Integer];T;#0;$@V;.F;Bi ;C0;7[ ;$@V;![ ;"@]V;#0;$@V;.F;/o;0;1T;2i{;3i;%@kL;9I"static VALUE
rb_io_tell(VALUE io)
{
rb_io_t *fptr;
off_t pos;
GetOpenFile(io, fptr);
pos = io_tell(fptr);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
pos -= fptr->rbuf.len;
return OFFT2NUM(pos);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#pos=;F;7[[I" offset;T0;[[@Ti ;T;;;0; [ ; { ; IC; "Seeks to the given +new_position+ (in bytes);
see {Position}[#class-IO-label-Position]:
f = File.open('t.txt')
f.tell # => 0
f.pos = 20 # => 20
f.tell # => 20
Related: IO#seek, IO#tell.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"pos=(new_position);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@V;.F;Bi ;C0;7[[I"new_position;T0;$@V;![ ;"I"Seeks to the given +new_position+ (in bytes);
see {Position}[#class-IO-label-Position]:
f = File.open('t.txt')
f.tell # => 0
f.pos = 20 # => 20
f.tell # => 20
Related: IO#seek, IO#tell.
@overload pos=(new_position);T;#0;$@V;.F;/o;0;1T;2i;3i ;%@kL;9I" static VALUE
rb_io_set_pos(VALUE io, VALUE offset)
{
rb_io_t *fptr;
off_t pos;
pos = NUM2OFFT(offset);
GetOpenFile(io, fptr);
pos = io_seek(fptr, pos, SEEK_SET);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
return OFFT2NUM(pos);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#eof;F;7[ ;[[@Ti ;T;:eof;0; [ ; { ; IC; "Returns +true+ if the stream is positioned at its end, +false+ otherwise;
see {Position}[#class-IO-label-Position]:
f = File.open('t.txt')
f.eof # => false
f.seek(0, :END) # => 0
f.eof # => true
Raises an exception unless the stream is opened for reading;
see {Mode}[#class-IO-label-Mode].
If +self+ is a stream such as pipe or socket, this method
blocks until the other end sends some data or closes it:
r, w = IO.pipe
Thread.new { sleep 1; w.close }
r.eof? # => true # After 1-second wait.
r, w = IO.pipe
Thread.new { sleep 1; w.puts "a" }
r.eof? # => false # After 1-second wait.
r, w = IO.pipe
r.eof? # blocks forever
Note that this method reads data to the input byte buffer. So
IO#sysread may not behave as you intend with IO#eof?, unless you
call IO#rewind first (which is not available for some streams).
I#eof? is an alias for IO#eof.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"eof;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@
W;![ ;"I"@return [Boolean];T;#0;$@
W;.F;Bi ;C0;7[ ;$@
W;![ ;"I"Returns +true+ if the stream is positioned at its end, +false+ otherwise;
see {Position}[#class-IO-label-Position]:
f = File.open('t.txt')
f.eof # => false
f.seek(0, :END) # => 0
f.eof # => true
Raises an exception unless the stream is opened for reading;
see {Mode}[#class-IO-label-Mode].
If +self+ is a stream such as pipe or socket, this method
blocks until the other end sends some data or closes it:
r, w = IO.pipe
Thread.new { sleep 1; w.close }
r.eof? # => true # After 1-second wait.
r, w = IO.pipe
Thread.new { sleep 1; w.puts "a" }
r.eof? # => false # After 1-second wait.
r, w = IO.pipe
r.eof? # blocks forever
Note that this method reads data to the input byte buffer. So
IO#sysread may not behave as you intend with IO#eof?, unless you
call IO#rewind first (which is not available for some streams).
I#eof? is an alias for IO#eof.
@overload eof
@return [Boolean];T;#0;$@
W;.F;/o;0;1T;2ip ;3i ;%@kL;9I"VALUE
rb_io_eof(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
if (READ_CHAR_PENDING(fptr)) return Qfalse;
if (READ_DATA_PENDING(fptr)) return Qfalse;
READ_CHECK(fptr);
#if RUBY_CRLF_ENVIRONMENT
if (!NEED_READCONV(fptr) && NEED_NEWLINE_DECORATOR_ON_READ(fptr)) {
return RBOOL(eof(fptr->fd));;
}
#endif
return RBOOL(io_fillbuf(fptr) < 0);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I" IO#eof?;F;7[ ;[[@Ti ;T;: eof?;0; [ ; { ; IC; "Returns +true+ if the stream is positioned at its end, +false+ otherwise;
see {Position}[#class-IO-label-Position]:
f = File.open('t.txt')
f.eof # => false
f.seek(0, :END) # => 0
f.eof # => true
Raises an exception unless the stream is opened for reading;
see {Mode}[#class-IO-label-Mode].
If +self+ is a stream such as pipe or socket, this method
blocks until the other end sends some data or closes it:
r, w = IO.pipe
Thread.new { sleep 1; w.close }
r.eof? # => true # After 1-second wait.
r, w = IO.pipe
Thread.new { sleep 1; w.puts "a" }
r.eof? # => false # After 1-second wait.
r, w = IO.pipe
r.eof? # blocks forever
Note that this method reads data to the input byte buffer. So
IO#sysread may not behave as you intend with IO#eof?, unless you
call IO#rewind first (which is not available for some streams).
I#eof? is an alias for IO#eof.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"eof;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@(W;![ ;"I"@return [Boolean];T;#0;$@(W;.F;Bi ;C0;7[ ;$@(W;![ ;"@$W;#0;$@(W;.F;/o;0;1T;2ip ;3i ;Bi ;%@kL;9I"VALUE
rb_io_eof(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
if (READ_CHAR_PENDING(fptr)) return Qfalse;
if (READ_DATA_PENDING(fptr)) return Qfalse;
READ_CHECK(fptr);
#if RUBY_CRLF_ENVIRONMENT
if (!NEED_READCONV(fptr) && NEED_NEWLINE_DECORATOR_ON_READ(fptr)) {
return RBOOL(eof(fptr->fd));;
}
#endif
return RBOOL(io_fillbuf(fptr) < 0);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO#close_on_exec?;F;7[ ;[[@Ti;T;:close_on_exec?;0; [ ; { ; IC; "Returns "
;T; [o;=
;>I"
overload;F;?0;;J;@0;:I" inspect;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@Y;![ ;"I"@return [String];T;#0;$@Y;.F;Bi ;C0;7[ ;$@Y;![ ;"I"Returns a string representation of +self+:
f = File.open('t.txt')
f.inspect # => "#"
@overload inspect
@return [String];T;#0;$@Y;.F;/o;0;1T;2i
;3i
;%@kL;9I"static VALUE
rb_io_inspect(VALUE obj)
{
rb_io_t *fptr;
VALUE result;
static const char closed[] = " (closed)";
fptr = RFILE(obj)->fptr;
if (!fptr) return rb_any_to_s(obj);
result = rb_str_new_cstr("#<");
rb_str_append(result, rb_class_name(CLASS_OF(obj)));
rb_str_cat2(result, ":");
if (NIL_P(fptr->pathv)) {
if (fptr->fd < 0) {
rb_str_cat(result, closed+1, strlen(closed)-1);
}
else {
rb_str_catf(result, "fd %d", fptr->fd);
}
}
else {
rb_str_append(result, fptr->pathv);
if (fptr->fd < 0) {
rb_str_cat(result, closed, strlen(closed));
}
}
return rb_str_cat2(result, ">");
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#external_encoding;F;7[ ;[[@Ti 0;T;:external_encoding;0; [ ; { ; IC; "Returns the Encoding object that represents the encoding of the file.
If _io_ is in write mode and no encoding is specified, returns +nil+.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"external_encoding;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Encoding;T;$@)Y;![ ;"I"@return [Encoding];T;#0;$@)Y;.F;Bi ;C0;7[ ;$@)Y;![ ;"I"Returns the Encoding object that represents the encoding of the file.
If _io_ is in write mode and no encoding is specified, returns +nil+.
@overload external_encoding
@return [Encoding];T;#0;$@)Y;.F;/o;0;1T;2i0;3i 0;%@kL;9I"vstatic VALUE
rb_io_external_encoding(VALUE io)
{
rb_io_t *fptr = RFILE(rb_io_taint_check(io))->fptr;
if (fptr->encs.enc2) {
return rb_enc_from_encoding(fptr->encs.enc2);
}
if (fptr->mode & FMODE_WRITABLE) {
if (fptr->encs.enc)
return rb_enc_from_encoding(fptr->encs.enc);
return Qnil;
}
return rb_enc_from_encoding(io_read_encoding(fptr));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#internal_encoding;F;7[ ;[[@Ti$0;T;:internal_encoding;0; [ ; { ; IC; "fReturns the Encoding of the internal string if conversion is
specified. Otherwise returns +nil+.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"internal_encoding;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Encoding;T;$@DY;![ ;"I"@return [Encoding];T;#0;$@DY;.F;Bi ;C0;7[ ;$@DY;![ ;"I"Returns the Encoding of the internal string if conversion is
specified. Otherwise returns +nil+.
@overload internal_encoding
@return [Encoding];T;#0;$@DY;.F;/o;0;1T;2i 0;3i!0;%@kL;9I"static VALUE
rb_io_internal_encoding(VALUE io)
{
rb_io_t *fptr = RFILE(rb_io_taint_check(io))->fptr;
if (!fptr->encs.enc2) return Qnil;
return rb_enc_from_encoding(io_read_encoding(fptr));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#set_encoding;F;7[[@90;[[@Ti@0;T;:set_encoding;0; [ ; { ; IC; "2If single argument is specified, read string from io is tagged
with the encoding specified. If encoding is a colon separated two
encoding names "A:B", the read string is converted from encoding A
(external encoding) to encoding B (internal encoding), then tagged
with B. If two arguments are specified, those must be encoding
objects or encoding names, and the first one is the external encoding, and the
second one is the internal encoding.
If the external encoding and the internal encoding is specified,
optional hash argument specify the conversion option.
;T; [
o;=
;>I"
overload;F;?0;;;@0;:I"set_encoding(ext_enc);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@_Y;![ ;"I"@return [IO];T;#0;$@_Y;.F;Bi ;C0;7[[I" ext_enc;T0;$@_Yo;=
;>I"
overload;F;?0;;;@0;:I"$set_encoding("ext_enc:int_enc");T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@_Y;![ ;"I"@return [IO];T;#0;$@_Y;.F;Bi ;C0;7[[""ext_enc:"
int_enc";$@_Yo;=
;>I"
overload;F;?0;;;@0;:I"#set_encoding(ext_enc, int_enc);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@_Y;![ ;"I"@return [IO];T;#0;$@_Y;.F;Bi ;C0;7[[I" ext_enc;T0[I" int_enc;T0;$@_Yo;=
;>I"
overload;F;?0;;;@0;:I")set_encoding("ext_enc:int_enc", opt);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@_Y;![ ;"I"@return [IO];T;#0;$@_Y;.F;Bi ;C0;7[[""ext_enc:"
int_enc"[I"opt;T0;$@_Yo;=
;>I"
overload;F;?0;;;@0;:I"(set_encoding(ext_enc, int_enc, opt);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@_Y;![ ;"I"@return [IO];T;#0;$@_Y;.F;Bi ;C0;7[[I" ext_enc;T0[I" int_enc;T0[I"opt;T0;$@_Y;![ ;"I"OIf single argument is specified, read string from io is tagged
with the encoding specified. If encoding is a colon separated two
encoding names "A:B", the read string is converted from encoding A
(external encoding) to encoding B (internal encoding), then tagged
with B. If two arguments are specified, those must be encoding
objects or encoding names, and the first one is the external encoding, and the
second one is the internal encoding.
If the external encoding and the internal encoding is specified,
optional hash argument specify the conversion option.
@overload set_encoding(ext_enc)
@return [IO]
@overload set_encoding("ext_enc:int_enc")
@return [IO]
@overload set_encoding(ext_enc, int_enc)
@return [IO]
@overload set_encoding("ext_enc:int_enc", opt)
@return [IO]
@overload set_encoding(ext_enc, int_enc, opt)
@return [IO];T;#0;$@_Y;.F;/o;0;1T;2i-0;3iA0;%@kL;9I"_static VALUE
rb_io_set_encoding(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
VALUE v1, v2, opt;
if (!RB_TYPE_P(io, T_FILE)) {
return forward(io, id_set_encoding, argc, argv);
}
argc = rb_scan_args(argc, argv, "11:", &v1, &v2, &opt);
GetOpenFile(io, fptr);
io_encoding_set(fptr, v1, v2, opt);
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#set_encoding_by_bom;F;7[ ;[[@Ti";T;:set_encoding_by_bom;0; [ ; { ; IC; "Checks if +ios+ starts with a BOM, and then consumes it and sets
the external encoding. Returns the result encoding if found, or
nil. If +ios+ is not binmode or its encoding has been set
already, an exception will be raised.
File.write("bom.txt", "\u{FEFF}abc")
ios = File.open("bom.txt", "rb")
ios.set_encoding_by_bom #=> #
File.write("nobom.txt", "abc")
ios = File.open("nobom.txt", "rb")
ios.set_encoding_by_bom #=> nil
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"set_encoding_by_bom;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Encoding;TI"nil;T;$@Y;![ ;"I" @return [Encoding, nil];T;#0;$@Y;.F;Bi ;C0;7[ ;$@Y;![ ;"I"Checks if +ios+ starts with a BOM, and then consumes it and sets
the external encoding. Returns the result encoding if found, or
nil. If +ios+ is not binmode or its encoding has been set
already, an exception will be raised.
File.write("bom.txt", "\u{FEFF}abc")
ios = File.open("bom.txt", "rb")
ios.set_encoding_by_bom #=> #
File.write("nobom.txt", "abc")
ios = File.open("nobom.txt", "rb")
ios.set_encoding_by_bom #=> nil
@overload set_encoding_by_bom
@return [Encoding, nil];T;#0;$@Y;.F;/o;0;1T;2iz";3i";%@kL;9I"bstatic VALUE
rb_io_set_encoding_by_bom(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!(fptr->mode & FMODE_BINMODE)) {
rb_raise(rb_eArgError, "ASCII incompatible encoding needs binmode");
}
if (fptr->encs.enc2) {
rb_raise(rb_eArgError, "encoding conversion is set");
}
else if (fptr->encs.enc && fptr->encs.enc != rb_ascii8bit_encoding()) {
rb_raise(rb_eArgError, "encoding is set to %s already",
rb_enc_name(fptr->encs.enc));
}
if (!io_set_encoding_by_bom(io)) return Qnil;
return rb_enc_from_encoding(fptr->encs.enc);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#autoclose?;F;7[ ;[[@Ti";T;:autoclose?;0; [ ; { ; IC; "~Returns +true+ if the underlying file descriptor of _ios_ will be
closed automatically at its finalization, otherwise +false+.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"autoclose?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Y;![ ;"I"@return [Boolean];T;#0;$@Y;.F;Bi ;C0;7[ ;$@Y;![ ;"I"Returns +true+ if the underlying file descriptor of _ios_ will be
closed automatically at its finalization, otherwise +false+.
@overload autoclose?
@return [Boolean];T;#0;$@Y;.F;/o;0;1T;2i";3i";Bi ;%@kL;9I"static VALUE
rb_io_autoclose_p(VALUE io)
{
rb_io_t *fptr = RFILE(io)->fptr;
rb_io_check_closed(fptr);
return (fptr->mode & FMODE_PREP) ? Qfalse : Qtrue;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#autoclose=;F;7[[I"autoclose;T0;[[@Ti #;T;:autoclose=;0; [ ; { ; IC; "Sets auto-close flag.
f = open("/dev/null")
IO.for_fd(f.fileno)
# ...
f.gets # may cause Errno::EBADF
f = open("/dev/null")
IO.for_fd(f.fileno).autoclose = false
# ...
f.gets # won't cause Errno::EBADF
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"autoclose=(bool);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Y;![ ;"I"@return [Boolean];T;#0;$@Y;.F;Bi ;C0;7[[I" bool;T0;$@Y;![ ;"I"Sets auto-close flag.
f = open("/dev/null")
IO.for_fd(f.fileno)
# ...
f.gets # may cause Errno::EBADF
f = open("/dev/null")
IO.for_fd(f.fileno).autoclose = false
# ...
f.gets # won't cause Errno::EBADF
@overload autoclose=(bool)
@return [Boolean];T;#0;$@Y;.F;/o;0;1T;2i";3i#;%@kL;9I"static VALUE
rb_io_set_autoclose(VALUE io, VALUE autoclose)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!RTEST(autoclose))
fptr->mode |= FMODE_PREP;
else
fptr->mode &= ~FMODE_PREP;
return autoclose;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#nread;F;7[ ;[[I"ext/io/wait/wait.c;TiW;T;:
nread;0; [ ; { ; IC; "iReturns number of bytes that can be read without blocking.
Returns zero if no information available.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
nread;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@Z;![ ;"I"@return [Integer];T;#0;$@Z;.F;Bi ;C0;7[ ;$@Z;![ ;"I"Returns number of bytes that can be read without blocking.
Returns zero if no information available.
@overload nread
@return [Integer];T;#0;$@Z;.F;/o;0;1T;2iO;3iT;%@kL;9I"static VALUE
io_nread(VALUE io)
{
rb_io_t *fptr;
int len;
ioctl_arg n;
GetOpenFile(io, fptr);
rb_io_check_readable(fptr);
len = rb_io_read_pending(fptr);
if (len > 0) return INT2FIX(len);
if (!FIONREAD_POSSIBLE_P(fptr->fd)) return INT2FIX(0);
if (ioctl(fptr->fd, FIONREAD, &n)) return INT2FIX(0);
if (n > 0) return ioctl_arg2num(n);
return INT2FIX(0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#ready?;F;7[ ;[[@ Zi;T;: ready?;0; [ ; { ; IC; "DReturns +true+ if input available without blocking, or +false+.;T; [o;=
;>I"
overload;F;?0;;;@0;:I" ready?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@5Z;![ ;"I"@return [Boolean];T;#0;$@5Z;.F;Bi ;C0;7[ ;$@5Z;![ ;"I"kReturns +true+ if input available without blocking, or +false+.
@overload ready?
@return [Boolean];T;#0;$@5Z;.F;/o;0;1T;2i};3i|;Bi ;%@kL;9I"static VALUE
io_ready_p(VALUE io)
{
rb_io_t *fptr;
#ifndef HAVE_RB_IO_WAIT
struct timeval tv = {0, 0};
#endif
GetOpenFile(io, fptr);
rb_io_check_readable(fptr);
if (rb_io_read_pending(fptr)) return Qtrue;
#ifndef HAVE_RB_IO_WAIT
if (wait_for_single_fd(fptr, RB_WAITFD_IN, &tv))
return Qtrue;
#else
if (RTEST(io_wait_event(io, RUBY_IO_READABLE, RB_INT2NUM(0))))
return Qtrue;
#endif
return Qfalse;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#wait;F;7[[@90;[[@ Zi,;T;;h;0; [ ; { ; IC; "bWaits until the IO becomes ready for the specified events and returns the
subset of events that become ready, or +false+ when times out.
The events can be a bit mask of +IO::READABLE+, +IO::WRITABLE+ or
+IO::PRIORITY+.
Returns +true+ immediately when buffered data is available.
Optional parameter +mode+ is one of +:read+, +:write+, or
+:read_write+.
;T; [o;=
;>I"
overload;F;?0;;h;@0;:I"wait(events, timeout);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@PZ;.F;Bi ;C0;7[[I" events;T0[I" timeout;T0;$@PZo;=
;>I"
overload;F;?0;;h;@0;:I"&wait(timeout = nil, mode = :read);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@PZ;.F;Bi ;C0;7[[I" timeout;TI"nil;T[I" mode;TI"
:read;T;$@PZ;![ ;"I"Waits until the IO becomes ready for the specified events and returns the
subset of events that become ready, or +false+ when times out.
The events can be a bit mask of +IO::READABLE+, +IO::WRITABLE+ or
+IO::PRIORITY+.
Returns +true+ immediately when buffered data is available.
Optional parameter +mode+ is one of +:read+, +:write+, or
+:read_write+.
@overload wait(events, timeout)
@overload wait(timeout = nil, mode = :read);T;#0;$@PZ;.F;/o;0;1T;2i;3i(;%@kL;9I"static VALUE
io_wait(int argc, VALUE *argv, VALUE io)
{
#ifndef HAVE_RB_IO_WAIT
rb_io_t *fptr;
struct timeval timerec;
struct timeval *tv = NULL;
int event = 0;
int i;
GetOpenFile(io, fptr);
for (i = 0; i < argc; ++i) {
if (SYMBOL_P(argv[i])) {
event |= wait_mode_sym(argv[i]);
}
else {
*(tv = &timerec) = rb_time_interval(argv[i]);
}
}
/* rb_time_interval() and might_mode() might convert the argument */
rb_io_check_closed(fptr);
if (!event) event = RB_WAITFD_IN;
if ((event & RB_WAITFD_IN) && rb_io_read_pending(fptr))
return Qtrue;
if (wait_for_single_fd(fptr, event, tv))
return io;
return Qnil;
#else
VALUE timeout = Qundef;
rb_io_event_t events = 0;
if (argc != 2 || (RB_SYMBOL_P(argv[0]) || RB_SYMBOL_P(argv[1]))) {
for (int i = 0; i < argc; i += 1) {
if (RB_SYMBOL_P(argv[i])) {
events |= wait_mode_sym(argv[i]);
}
else if (timeout == Qundef) {
rb_time_interval(timeout = argv[i]);
}
else {
rb_raise(rb_eArgError, "timeout given more than once");
}
}
if (timeout == Qundef) timeout = Qnil;
}
else /* argc == 2 */ {
events = RB_NUM2UINT(argv[0]);
timeout = argv[1];
}
if (events == 0) {
events = RUBY_IO_READABLE;
}
if (events & RUBY_IO_READABLE) {
rb_io_t *fptr = NULL;
RB_IO_POINTER(io, fptr);
if (rb_io_read_pending(fptr)) {
return Qtrue;
}
}
return io_wait_event(io, events, timeout);
#endif
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#wait_readable;F;7[[@90;[[@ Zi;T;:wait_readable;0; [ ; { ; IC; "Waits until IO is readable and returns +true+, or
+false+ when times out.
Returns +true+ immediately when buffered data is available.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"wait_readable;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@yZ;![ ;"I"@return [Boolean];T;#0;$@yZ;.F;Bi ;C0;7[ ;$@yZo;=
;>I"
overload;F;?0;;;@0;:I"wait_readable(timeout);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@yZ;![ ;"I"@return [Boolean];T;#0;$@yZ;.F;Bi ;C0;7[[I" timeout;T0;$@yZ;![ ;"I"Waits until IO is readable and returns +true+, or
+false+ when times out.
Returns +true+ immediately when buffered data is available.
@overload wait_readable
@return [Boolean]
@overload wait_readable(timeout)
@return [Boolean];T;#0;$@yZ;.F;/o;0;1T;2i;3i;%@kL;9I"kstatic VALUE
io_wait_readable(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
#ifndef HAVE_RB_IO_WAIT
struct timeval timerec;
struct timeval *tv;
#endif
GetOpenFile(io, fptr);
rb_io_check_readable(fptr);
#ifndef HAVE_RB_IO_WAIT
tv = get_timeout(argc, argv, &timerec);
#endif
if (rb_io_read_pending(fptr)) return Qtrue;
#ifndef HAVE_RB_IO_WAIT
if (wait_for_single_fd(fptr, RB_WAITFD_IN, tv)) {
return io;
}
return Qnil;
#else
rb_check_arity(argc, 0, 1);
VALUE timeout = (argc == 1 ? argv[0] : Qnil);
return io_wait_event(io, RUBY_IO_READABLE, timeout);
#endif
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#wait_writable;F;7[[@90;[[@ Zi;T;:wait_writable;0; [ ; { ; IC; "MWaits until IO is writable and returns +true+ or
+false+ when times out.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"wait_writable;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Z;![ ;"I"@return [Boolean];T;#0;$@Z;.F;Bi ;C0;7[ ;$@Zo;=
;>I"
overload;F;?0;;;@0;:I"wait_writable(timeout);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Z;![ ;"I"@return [Boolean];T;#0;$@Z;.F;Bi ;C0;7[[I" timeout;T0;$@Z;![ ;"I"Waits until IO is writable and returns +true+ or
+false+ when times out.
@overload wait_writable
@return [Boolean]
@overload wait_writable(timeout)
@return [Boolean];T;#0;$@Z;.F;/o;0;1T;2i;3i;%@kL;9I" static VALUE
io_wait_writable(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
#ifndef HAVE_RB_IO_WAIT
struct timeval timerec;
struct timeval *tv;
#endif
GetOpenFile(io, fptr);
rb_io_check_writable(fptr);
#ifndef HAVE_RB_IO_WAIT
tv = get_timeout(argc, argv, &timerec);
if (wait_for_single_fd(fptr, RB_WAITFD_OUT, tv)) {
return io;
}
return Qnil;
#else
rb_check_arity(argc, 0, 1);
VALUE timeout = (argc == 1 ? argv[0] : Qnil);
return io_wait_event(io, RUBY_IO_WRITABLE, timeout);
#endif
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#wait_priority;F;7[[@90;[[@ Zi;T;:wait_priority;0; [ ; { ; IC; "MWaits until IO is priority and returns +true+ or
+false+ when times out.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"wait_priority;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Z;![ ;"I"@return [Boolean];T;#0;$@Z;.F;Bi ;C0;7[ ;$@Zo;=
;>I"
overload;F;?0;;;@0;:I"wait_priority(timeout);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Z;![ ;"I"@return [Boolean];T;#0;$@Z;.F;Bi ;C0;7[[I" timeout;T0;$@Z;![ ;"I"Waits until IO is priority and returns +true+ or
+false+ when times out.
@overload wait_priority
@return [Boolean]
@overload wait_priority(timeout)
@return [Boolean];T;#0;$@Z;.F;/o;0;1T;2i;3i;%@kL;9I"Vstatic VALUE
io_wait_priority(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr = NULL;
RB_IO_POINTER(io, fptr);
rb_io_check_readable(fptr);
if (rb_io_read_pending(fptr)) return Qtrue;
rb_check_arity(argc, 0, 1);
VALUE timeout = argc == 1 ? argv[0] : Qnil;
return io_wait_event(io, RUBY_IO_PRIORITY, timeout);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#nonblock?;F;7[ ;[[I" ext/io/nonblock/nonblock.c;Ti,;T;:nonblock?;0; [ ; { ; IC; "I"
overload;F;?0;;;@0;:I"nonblock?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Z;![ ;"I"@return [Boolean];T;#0;$@Z;.F;Bi ;C0;7[ ;$@Z;![ ;"I"fReturns +true+ if an IO object is in non-blocking mode.
@overload nonblock?
@return [Boolean];T;#0;$@Z;.F;/o;0;1T;2i&;3i*;Bi ;%@kL;9I"static VALUE
rb_io_nonblock_p(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (io_nonblock_mode(fptr->fd) & O_NONBLOCK)
return Qtrue;
return Qfalse;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#nonblock=;F;7[[I"nb;T0;[[@ZiS;T;:nonblock=;0; [ ; { ; IC; "eEnables non-blocking mode on a stream when set to
+true+, and blocking mode when set to +false+.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"nonblock=(boolean);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@[;![ ;"I"@return [Boolean];T;#0;$@[;.F;Bi ;C0;7[[I" boolean;T0;$@[;![ ;"I"Enables non-blocking mode on a stream when set to
+true+, and blocking mode when set to +false+.
@overload nonblock=(boolean)
@return [Boolean];T;#0;$@[;.F;/o;0;1T;2iL;3iQ;%@kL;9I"static VALUE
rb_io_nonblock_set(VALUE io, VALUE nb)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (RTEST(nb))
rb_io_set_nonblock(fptr);
else
io_nonblock_set(fptr->fd, io_nonblock_mode(fptr->fd), RTEST(nb));
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#nonblock;F;7[[@90;[[@Zir;T;:
nonblock;0; [ ; { ; IC; "Yields +self+ in non-blocking mode.
When +false+ is given as an argument, +self+ is yielded in blocking mode.
The original mode is restored after the block is executed.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
nonblock;T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"io;T;$@5[o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@5[;![ ;"I" @yield [io]
@return [IO];T;#0;$@5[;.F;Bi ;C0;7[ ;$@5[o;=
;>I"
overload;F;?0;;;@0;:I"nonblock(boolean);T; IC; " ;T; [o;A
;>I"
yield;F;?I" ;T;0;@[I"io;T;$@5[o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@5[;![ ;"I" @yield [io]
@return [IO];T;#0;$@5[;.F;Bi ;C0;7[[I" boolean;T0;$@5[;![ ;"I"Yields +self+ in non-blocking mode.
When +false+ is given as an argument, +self+ is yielded in blocking mode.
The original mode is restored after the block is executed.
@overload nonblock
@yield [io]
@return [IO]
@overload nonblock(boolean)
@yield [io]
@return [IO];T;#0;$@5[;.F;/o;0;1T;2ih;3is;%@kL;9I"static VALUE
rb_io_nonblock_block(int argc, VALUE *argv, VALUE io)
{
int nb = 1;
rb_io_t *fptr;
int f, restore[2];
GetOpenFile(io, fptr);
if (argc > 0) {
VALUE v;
rb_scan_args(argc, argv, "01", &v);
nb = RTEST(v);
}
f = io_nonblock_mode(fptr->fd);
restore[0] = fptr->fd;
restore[1] = f;
if (!io_nonblock_set(fptr->fd, f, nb))
return rb_yield(io);
return rb_ensure(rb_yield, io, io_nonblock_restore, (VALUE)restore);
};T;:I"static VALUE;T;;To; ;IC;[4o; ;IC;[ ;
@l[; IC;[ ;
@l[; IC;[ ;
@l[;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[I"io_buffer.c;TiI;F;:LockedError;;;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@l[;%@j[;&I" IO::Buffer::LockedError;F;'o;( ;)0;*0;+0;:RuntimeError;%@;-o; ;IC;[ ;
@[; IC;[ ;
@[; IC;[ ;
@[;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[@)ie
[@)iw ;T;;;;;; ; [ ; { ; IC; "A generic error class raised when an invalid operation is attempted.
Kernel#raise will raise a RuntimeError if no Exception class is
specified.
raise "ouch"
raises the exception:
RuntimeError: ouch
;T; [ ;![ ;"I"
A generic error class raised when an invalid operation is attempted.
Kernel#raise will raise a RuntimeError if no Exception class is
specified.
raise "ouch"
raises the exception:
RuntimeError: ouch
;T;#0;$@[;.F;/o;0;1T;2ie
;3io
;%@;&I"RuntimeError;F;'@ ;;o; ;IC;[ ;
@[; IC;[ ;
@[; IC;[ ;
@[;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[@w[iJ;F;:AllocationError;;;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@[;%@j[;&I" IO::Buffer::AllocationError;F;'o;( ;)0;*0;+0;;;%@;-@[;;o; ;IC;[ ;
@[; IC;[ ;
@[; IC;[ ;
@[;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[@w[iK;F;:AccessError;;;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@[;%@j[;&I" IO::Buffer::AccessError;F;'o;( ;)0;*0;+0;;;%@;-@[;;o; ;IC;[ ;
@[; IC;[ ;
@[; IC;[ ;
@[;
IC;{;IC;{ ;T;IC;{ ;T;T;{ ;[ ;[[@w[iL;F;:InvalidatedError;;;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@[;%@j[;&I"!IO::Buffer::InvalidatedError;F;'o;( ;)0;*0;+0;;;%@;-@[;;o;4;5F;6;;; ;&I"IO::Buffer.for;F;7[[I" string;T0;[[@w[i6;T;:for;0; [ ; { ; IC; "oCreates a IO::Buffer from the given string's memory. The buffer remains
associated with the string, and writing to a buffer will update the string's
contents.
Until #free is invoked on the buffer, either explicitly or via the garbage
collector, the source string will be locked and cannot be modified.
If the string is frozen, it will create a read-only buffer which cannot be
modified.
string = 'test'
buffer = IO::Buffer.for(str)
buffer.external? #=> true
buffer.get_string(0, 1)
# => "t"
string
# => "best"
buffer.resize(100)
# in `resize': Cannot resize external buffer! (IO::Buffer::AccessError)
;T; [o;=
;>I"
overload;F;?0;:IO::Buffer.for;@0;:I"IO::Buffer.for(string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@[;.F;Bi ;C0;7[[I" string;T0;$@[;![ ;"I"Creates a IO::Buffer from the given string's memory. The buffer remains
associated with the string, and writing to a buffer will update the string's
contents.
Until #free is invoked on the buffer, either explicitly or via the garbage
collector, the source string will be locked and cannot be modified.
If the string is frozen, it will create a read-only buffer which cannot be
modified.
string = 'test'
buffer = IO::Buffer.for(str)
buffer.external? #=> true
buffer.get_string(0, 1)
# => "t"
string
# => "best"
buffer.resize(100)
# in `resize': Cannot resize external buffer! (IO::Buffer::AccessError)
@overload IO::Buffer.for(string);T;#0;$@[;.F;/o;0;1T;2i ;3i4;%@j[;9I"6VALUE
rb_io_buffer_type_for(VALUE klass, VALUE string)
{
io_buffer_experimental();
StringValue(string);
VALUE instance = rb_io_buffer_type_allocate(klass);
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, data);
rb_str_locktmp(string);
enum rb_io_buffer_flags flags = RB_IO_BUFFER_EXTERNAL;
if (RB_OBJ_FROZEN(string))
flags |= RB_IO_BUFFER_READONLY;
io_buffer_initialize(data, RSTRING_PTR(string), RSTRING_LEN(string), flags, string);
return instance;
};T;:I"
VALUE;T;;To;u;[[@w[i\;F;:PAGE_SIZE;;w;; ; [ ; { ; IC; "(Efficient sizing of mapped buffers:
;T; [ ;![ ;"I"(Efficient sizing of mapped buffers:;T;#0;$@[;.F;/o;0;1T;2i[;3i[;%@j[;&I"IO::Buffer::PAGE_SIZE;F;xI"(SIZET2NUM(RUBY_IO_BUFFER_PAGE_SIZE);To;u;[[@w[i];F;:DEFAULT_SIZE;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@[;%@j[;&I" IO::Buffer::DEFAULT_SIZE;F;xI"+SIZET2NUM(RUBY_IO_BUFFER_DEFAULT_SIZE);To;4;5F;6;;; ;&I"IO::Buffer.map;F;7[[@90;[[@w[i;T;;;0; [ ; { ; IC; "!Create an IO::Buffer for reading from +file+ by memory-mapping the file.
+file_io+ should be a +File+ instance, opened for reading.
Optional +size+ and +offset+ of mapping can be specified.
By default, the buffer would be immutable (read only); to create a writable
mapping, you need to open a file in read-write mode, and explicitly pass
+flags+ argument without IO::Buffer::IMMUTABLE.
File.write('test.txt', 'test')
buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
# => #
buffer.readonly? # => true
buffer.get_string
# => "test"
buffer.set_string('b', 0)
# `set_string': Buffer is not writable! (IO::Buffer::AccessError)
# create read/write mapping: length 4 bytes, offset 0, flags 0
buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0)
buffer.set_string('b', 0)
# => 1
# Check it
File.read('test.txt')
# => "best"
Note that some operating systems may not have cache coherency between mapped
buffers and file reads.
;T; [o;=
;>I"
overload;F;?0;:IO::Buffer.map;@0;:I"4IO::Buffer.map(file, [size, [offset, [flags]]]);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@[;.F;Bi ;C0;7[[I" file;T0[I" [size, [offset, [flags]]];T0;$@[;![ ;"I"^Create an IO::Buffer for reading from +file+ by memory-mapping the file.
+file_io+ should be a +File+ instance, opened for reading.
Optional +size+ and +offset+ of mapping can be specified.
By default, the buffer would be immutable (read only); to create a writable
mapping, you need to open a file in read-write mode, and explicitly pass
+flags+ argument without IO::Buffer::IMMUTABLE.
File.write('test.txt', 'test')
buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
# => #
buffer.readonly? # => true
buffer.get_string
# => "test"
buffer.set_string('b', 0)
# `set_string': Buffer is not writable! (IO::Buffer::AccessError)
# create read/write mapping: length 4 bytes, offset 0, flags 0
buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0)
buffer.set_string('b', 0)
# => 1
# Check it
File.read('test.txt')
# => "best"
Note that some operating systems may not have cache coherency between mapped
buffers and file reads.
@overload IO::Buffer.map(file, [size, [offset, [flags]]]);T;#0;$@[;.F;/o;0;1T;2il;3i;%@j[;9I"Gstatic VALUE
io_buffer_map(int argc, VALUE *argv, VALUE klass)
{
if (argc < 1 || argc > 4) {
rb_error_arity(argc, 2, 4);
}
// We might like to handle a string path?
VALUE io = argv[0];
size_t size;
if (argc >= 2 && !RB_NIL_P(argv[1])) {
size = RB_NUM2SIZE(argv[1]);
}
else {
off_t file_size = rb_file_size(io);
// Compiler can confirm that we handled file_size < 0 case:
if (file_size < 0) {
rb_raise(rb_eArgError, "Invalid negative file size!");
}
// Here, we assume that file_size is positive:
else if ((uintmax_t)file_size > SIZE_MAX) {
rb_raise(rb_eArgError, "File larger than address space!");
}
else {
// This conversion should be safe:
size = (size_t)file_size;
}
}
off_t offset = 0;
if (argc >= 3) {
offset = NUM2OFFT(argv[2]);
}
enum rb_io_buffer_flags flags = 0;
if (argc >= 4) {
flags = RB_NUM2UINT(argv[3]);
}
return rb_io_buffer_map(io, size, offset, flags);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#initialize;F;7[[@90;[[@w[i;T;;D;0; [ ; { ; IC; "
Create a new zero-filled IO::Buffer of +size+ bytes.
By default, the buffer will be _internal_: directly allocated chunk
of the memory. But if the requested +size+ is more than OS-specific
IO::Bufer::PAGE_SIZE, the buffer would be allocated using the
virtual memory mechanism (anonymous +mmap+ on Unix, +VirtualAlloc+
on Windows). The behavior can be forced by passing IO::Buffer::MAPPED
as a second parameter.
Examples
buffer = IO::Buffer.new(4)
# =>
# #
# 0x00000000 00 00 00 00 ....
buffer.get_string(0, 1) # => "\x00"
buffer.set_string("test")
buffer
# =>
# #
# 0x00000000 74 65 73 74 test
;T; [o;=
;>I"
overload;F;?0;:IO::Buffer.new;@0;:I"7IO::Buffer.new([size = DEFAULT_SIZE, [flags = 0]]);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@\;.F;Bi ;C0;7[[I"
[size;TI" DEFAULT_SIZE, [flags = 0]];T;$@\;![ ;"I"JCreate a new zero-filled IO::Buffer of +size+ bytes.
By default, the buffer will be _internal_: directly allocated chunk
of the memory. But if the requested +size+ is more than OS-specific
IO::Bufer::PAGE_SIZE, the buffer would be allocated using the
virtual memory mechanism (anonymous +mmap+ on Unix, +VirtualAlloc+
on Windows). The behavior can be forced by passing IO::Buffer::MAPPED
as a second parameter.
Examples
buffer = IO::Buffer.new(4)
# =>
# #
# 0x00000000 00 00 00 00 ....
buffer.get_string(0, 1) # => "\x00"
buffer.set_string("test")
buffer
# =>
# #
# 0x00000000 74 65 73 74 test
@overload IO::Buffer.new([size = DEFAULT_SIZE, [flags = 0]]);T;#0;$@\;.F;/o;0;1T;2i;3i;%@j[;9I"VALUE
rb_io_buffer_initialize(int argc, VALUE *argv, VALUE self)
{
io_buffer_experimental();
if (argc < 0 || argc > 2) {
rb_error_arity(argc, 0, 2);
}
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
size_t size;
if (argc > 0) {
size = RB_NUM2SIZE(argv[0]);
} else {
size = RUBY_IO_BUFFER_DEFAULT_SIZE;
}
enum rb_io_buffer_flags flags = 0;
if (argc >= 2) {
flags = RB_NUM2UINT(argv[1]);
}
else {
flags |= io_flags_for_size(size);
}
io_buffer_initialize(data, NULL, size, flags, Qnil);
return self;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#inspect;F;7[ ;[[@w[i;T;;J;0; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@.\;%@j[;9I"VALUE
rb_io_buffer_inspect(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
VALUE result = rb_io_buffer_to_s(self);
if (io_buffer_validate(data)) {
// Limit the maximum size genearted by inspect.
if (data->size <= 256) {
io_buffer_hexdump(result, 16, data->base, data->size, 0);
}
}
return result;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#hexdump;F;7[ ;[[@w[i;T;: hexdump;0; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@:\;%@j[;9I"static VALUE
rb_io_buffer_hexdump(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
VALUE result = Qnil;
if (io_buffer_validate(data) && data->base) {
result = rb_str_buf_new(data->size*3 + (data->size/16)*12 + 1);
io_buffer_hexdump(result, 16, data->base, data->size, 1);
}
return result;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#to_s;F;7[ ;[[@w[i8;T;;G;0; [ ; { ; IC; "Short representation of the buffer. It includes the address, size and
symbolic flags. This format is subject to change.
puts IO::Buffer.new(4) # uses to_s internally
# #
;T; [o;=
;>I"
overload;F;?0;;G;@0;:I" to_s;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@F\;![ ;"I"@return [String];T;#0;$@F\;.F;Bi ;C0;7[ ;$@F\;![ ;"I"Short representation of the buffer. It includes the address, size and
symbolic flags. This format is subject to change.
puts IO::Buffer.new(4) # uses to_s internally
# #
@overload to_s
@return [String];T;#0;$@F\;.F;/o;0;1T;2i.;3i7;%@j[;9I"0VALUE
rb_io_buffer_to_s(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
VALUE result = rb_str_new_cstr("#<");
rb_str_append(result, rb_class_name(CLASS_OF(self)));
rb_str_catf(result, " %p+%"PRIdSIZE, data->base, data->size);
if (data->base == NULL) {
rb_str_cat2(result, " NULL");
}
if (data->flags & RB_IO_BUFFER_EXTERNAL) {
rb_str_cat2(result, " EXTERNAL");
}
if (data->flags & RB_IO_BUFFER_INTERNAL) {
rb_str_cat2(result, " INTERNAL");
}
if (data->flags & RB_IO_BUFFER_MAPPED) {
rb_str_cat2(result, " MAPPED");
}
if (data->flags & RB_IO_BUFFER_LOCKED) {
rb_str_cat2(result, " LOCKED");
}
if (data->flags & RB_IO_BUFFER_READONLY) {
rb_str_cat2(result, " READONLY");
}
if (data->source != Qnil) {
rb_str_cat2(result, " SLICE");
}
if (!io_buffer_validate(data)) {
rb_str_cat2(result, " INVALID");
}
return rb_str_cat2(result, ">");
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#size;F;7[ ;[[@w[i;T;;;0; [ ; { ; IC; "Returns the size of the buffer that was explicitly set (on creation with ::new
or on #resize), or deduced on buffer's creation from string or file.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" size;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@a\;![ ;"I"@return [Integer];T;#0;$@a\;.F;Bi ;C0;7[ ;$@a\;![ ;"I"Returns the size of the buffer that was explicitly set (on creation with ::new
or on #resize), or deduced on buffer's creation from string or file.
@overload size
@return [Integer];T;#0;$@a\;.F;/o;0;1T;2i;3i;%@j[;9I"VALUE
rb_io_buffer_size(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return SIZET2NUM(data->size);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#valid?;F;7[ ;[[@w[i;T;: valid?;0; [ ; { ; IC; "Returns whether the buffer data is accessible.
A buffer becomes invalid if it is a slice of another buffer which has been
freed.;T; [o;=
;>I"
overload;F;?0;;;@0;:I" valid?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@|\;![ ;"I"@return [Boolean];T;#0;$@|\;.F;Bi ;C0;7[ ;$@|\;![ ;"I"Returns whether the buffer data is accessible.
A buffer becomes invalid if it is a slice of another buffer which has been
freed.
@overload valid?
@return [Boolean];T;#0;$@|\;.F;/o;0;1T;2i;3i;Bi ;%@j[;9I"static VALUE
rb_io_buffer_valid_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(io_buffer_validate(data));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#transfer;F;7[ ;[[@w[i;T;:
transfer;0; [ ; { ; IC; "dTransfers ownership to a new buffer, deallocating the current one.
buffer = IO::Buffer.new('test')
other = buffer.transfer
other
# =>
# #
# 0x00000000 74 65 73 74 test
buffer
# =>
# #
buffer.null?
# => true
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
transfer;T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@\;.F;Bi ;C0;7[ ;$@\;![ ;"I"zTransfers ownership to a new buffer, deallocating the current one.
buffer = IO::Buffer.new('test')
other = buffer.transfer
other
# =>
# #
# 0x00000000 74 65 73 74 test
buffer
# =>
# #
buffer.null?
# => true
@overload transfer;T;#0;$@\;.F;/o;0;1T;2i~;3i;%@j[;9I">VALUE
rb_io_buffer_transfer(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
if (data->flags & RB_IO_BUFFER_LOCKED) {
rb_raise(rb_eIOBufferLockedError, "Cannot transfer ownership of locked buffer!");
}
VALUE instance = rb_io_buffer_type_allocate(rb_class_of(self));
struct rb_io_buffer *transferred;
TypedData_Get_Struct(instance, struct rb_io_buffer, &rb_io_buffer_type, transferred);
*transferred = *data;
io_buffer_zero(data);
return instance;
};T;:I"
VALUE;T;;To;u;[[@w[im;F;:
EXTERNAL;;w;; ; [ ; { ; IC; " Flags:
;T; [ ;![ ;"I" Flags:;T;#0;$@\;.F;/o;0;1T;2il;3il;%@j[;&I"IO::Buffer::EXTERNAL;F;xI"&RB_INT2NUM(RB_IO_BUFFER_EXTERNAL);To;u;[[@w[in;F;:
INTERNAL;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\;%@j[;&I"IO::Buffer::INTERNAL;F;xI"&RB_INT2NUM(RB_IO_BUFFER_INTERNAL);To;u;[[@w[io;F;: MAPPED;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\;%@j[;&I"IO::Buffer::MAPPED;F;xI"$RB_INT2NUM(RB_IO_BUFFER_MAPPED);To;u;[[@w[ip;F;: LOCKED;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\;%@j[;&I"IO::Buffer::LOCKED;F;xI"$RB_INT2NUM(RB_IO_BUFFER_LOCKED);To;u;[[@w[iq;F;: PRIVATE;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\;%@j[;&I"IO::Buffer::PRIVATE;F;xI"%RB_INT2NUM(RB_IO_BUFFER_PRIVATE);To;u;[[@w[ir;F;:
READONLY;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\;%@j[;&I"IO::Buffer::READONLY;F;xI"&RB_INT2NUM(RB_IO_BUFFER_READONLY);To;u;[[@w[iu;F;:LITTLE_ENDIAN;;w;; ; [ ; { ; IC; " Endian:
;T; [ ;![ ;"I" Endian:;T;#0;$@\;.F;/o;0;1T;2it;3it;%@j[;&I" IO::Buffer::LITTLE_ENDIAN;F;xI"+RB_INT2NUM(RB_IO_BUFFER_LITTLE_ENDIAN);To;u;[[@w[iv;F;:BIG_ENDIAN;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@\;%@j[;&I"IO::Buffer::BIG_ENDIAN;F;xI"(RB_INT2NUM(RB_IO_BUFFER_BIG_ENDIAN);To;u;[[@w[iw;F;:HOST_ENDIAN;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@];%@j[;&I" IO::Buffer::HOST_ENDIAN;F;xI")RB_INT2NUM(RB_IO_BUFFER_HOST_ENDIAN);To;u;[[@w[ix;F;:NETWORK_ENDIAN;;w;; ; [ ; { ; IC; " ;T; [ ;![ ;"@;#0;$@ ];%@j[;&I" IO::Buffer::NETWORK_ENDIAN;F;xI",RB_INT2NUM(RB_IO_BUFFER_NETWORK_ENDIAN);To;4;5F;6;;; ;&I"IO::Buffer#null?;F;7[ ;[[@w[i;T;:
null?;0; [ ; { ; IC; "RIf the buffer was freed with #free or was never allocated in the first
place.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
null?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@];![ ;"I"@return [Boolean];T;#0;$@];.F;Bi ;C0;7[ ;$@];![ ;"I"yIf the buffer was freed with #free or was never allocated in the first
place.
@overload null?
@return [Boolean];T;#0;$@];.F;/o;0;1T;2i;3i;Bi ;%@j[;9I"static VALUE
rb_io_buffer_null_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(data->base == NULL);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#empty?;F;7[ ;[[@w[i;T;;;0; [ ; { ; IC; "If the buffer is _external_, meaning it references from memory which is not
allocated or mapped by the buffer itself.
A buffer created using ::for has an external reference to the string's
memory.
External buffer can't be resized.;T; [o;=
;>I"
overload;F;?0;:external?;@0;:I"external?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@0];![ ;"I"@return [Boolean];T;#0;$@0];.F;Bi ;C0;7[ ;$@0];![ ;"I"If the buffer is _external_, meaning it references from memory which is not
allocated or mapped by the buffer itself.
A buffer created using ::for has an external reference to the string's
memory.
External buffer can't be resized.
@overload external?
@return [Boolean];T;#0;$@0];.F;/o;0;1T;2i;3i;Bi ;%@j[;9I"static VALUE
rb_io_buffer_empty_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(data->size == 0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#external?;F;7[ ;[[@w[i;T;;;0; [ ; { ; IC; " ;T; [o;A
;>I" return;F;?@;0;@[@L;$@K];![ ;"@;#0;$@K];Bi ;%@j[;9I"static VALUE
rb_io_buffer_external_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(data->flags & RB_IO_BUFFER_EXTERNAL);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#internal?;F;7[ ;[[@w[i;T;:internal?;0; [ ; { ; IC; "If the buffer is _internal_, meaning it references memory allocated by the
buffer itself.
An internal buffer is not associated with any external memory (e.g. string)
or file mapping.
Internal buffers are created using ::new and is the default when the
requested size is less than the IO::Buffer::PAGE_SIZE and it was not
requested to be mapped on creation.
Internal buffers can be resized, and such an operation will typically
invalidate all slices, but not always.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"internal?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@Z];![ ;"I"@return [Boolean];T;#0;$@Z];.F;Bi ;C0;7[ ;$@Z];![ ;"I"If the buffer is _internal_, meaning it references memory allocated by the
buffer itself.
An internal buffer is not associated with any external memory (e.g. string)
or file mapping.
Internal buffers are created using ::new and is the default when the
requested size is less than the IO::Buffer::PAGE_SIZE and it was not
requested to be mapped on creation.
Internal buffers can be resized, and such an operation will typically
invalidate all slices, but not always.
@overload internal?
@return [Boolean];T;#0;$@Z];.F;/o;0;1T;2i ;3i;Bi ;%@j[;9I"static VALUE
rb_io_buffer_internal_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(data->flags & RB_IO_BUFFER_INTERNAL);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#mapped?;F;7[ ;[[@w[i(;T;: mapped?;0; [ ; { ; IC; "zIf the buffer is _mapped_, meaning it references memory mapped by the
buffer.
Mapped buffers are either anonymous, if created by ::new with the
IO::Buffer::MAPPED flag or if the size was at least IO::Buffer::PAGE_SIZE,
or backed by a file if created with ::map.
Mapped buffers can usually be resized, and such an operation will typically
invalidate all slices, but not always.;T; [o;=
;>I"
overload;F;?0;;;@0;:I" mapped?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@u];![ ;"I"@return [Boolean];T;#0;$@u];.F;Bi ;C0;7[ ;$@u];![ ;"I"If the buffer is _mapped_, meaning it references memory mapped by the
buffer.
Mapped buffers are either anonymous, if created by ::new with the
IO::Buffer::MAPPED flag or if the size was at least IO::Buffer::PAGE_SIZE,
or backed by a file if created with ::map.
Mapped buffers can usually be resized, and such an operation will typically
invalidate all slices, but not always.
@overload mapped?
@return [Boolean];T;#0;$@u];.F;/o;0;1T;2i;3i';Bi ;%@j[;9I"static VALUE
rb_io_buffer_mapped_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(data->flags & RB_IO_BUFFER_MAPPED);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#locked?;F;7[ ;[[@w[i@;T;;T;0; [ ; { ; IC; "bIf the buffer is _locked_, meaning it is inside #locked block execution.
Locked buffer can't be resized or freed, and another lock can't be acquired
on it.
Locking is not thread safe, but is a semantic used to ensure buffers don't
move while being used by a system call.
buffer.locked do
buffer.write(io) # theoretical system call interface
end;T; [o;=
;>I"
overload;F;?0;;T;@0;:I" locked?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@];![ ;"I"@return [Boolean];T;#0;$@];.F;Bi ;C0;7[ ;$@];![ ;"I"If the buffer is _locked_, meaning it is inside #locked block execution.
Locked buffer can't be resized or freed, and another lock can't be acquired
on it.
Locking is not thread safe, but is a semantic used to ensure buffers don't
move while being used by a system call.
buffer.locked do
buffer.write(io) # theoretical system call interface
end
@overload locked?
@return [Boolean];T;#0;$@];.F;/o;0;1T;2i1;3i?;Bi ;%@j[;9I"static VALUE
rb_io_buffer_locked_p(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
return RBOOL(data->flags & RB_IO_BUFFER_LOCKED);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#readonly?;F;7[ ;[[@w[i[;T;:readonly?;0; [ ; { ; IC; " ;T; [o;A
;>I" return;F;?@;0;@[@L;$@];![ ;"@;#0;$@];Bi ;%@j[;9I"gstatic VALUE
io_buffer_readonly_p(VALUE self)
{
return RBOOL(rb_io_buffer_readonly_p(self));
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#locked;F;7[ ;[[@w[i;T;: locked;0; [ ; { ; IC; "Allows to process a buffer in exclusive way, for concurrency-safety. While
the block is performed, the buffer is considered locked, and no other code
can enter the lock. Also, locked buffer can't be changed with #resize or
#free.
buffer = IO::Buffer.new(4)
buffer.locked? #=> false
Fiber.schedule do
buffer.locked do
buffer.write(io) # theoretical system call interface
end
end
Fiber.schedule do
# in `locked': Buffer already locked! (IO::Buffer::LockedError)
buffer.locked do
buffer.set_string(...)
end
end
The following operations acquire a lock: #resize, #free.
Locking is not thread safe. It is designed as a safety net around
non-blocking system calls. You can only share a buffer between threads with
appropriate synchronisation techniques.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" locked;T; IC; " ;T; [o;A
;>I"
yield;F;?I"[];T;0;@0;$@];![ ;"I"@yield [];T;#0;$@];.F;Bi ;C0;7[ ;$@];![ ;"I":Allows to process a buffer in exclusive way, for concurrency-safety. While
the block is performed, the buffer is considered locked, and no other code
can enter the lock. Also, locked buffer can't be changed with #resize or
#free.
buffer = IO::Buffer.new(4)
buffer.locked? #=> false
Fiber.schedule do
buffer.locked do
buffer.write(io) # theoretical system call interface
end
end
Fiber.schedule do
# in `locked': Buffer already locked! (IO::Buffer::LockedError)
buffer.locked do
buffer.set_string(...)
end
end
The following operations acquire a lock: #resize, #free.
Locking is not thread safe. It is designed as a safety net around
non-blocking system calls. You can only share a buffer between threads with
appropriate synchronisation techniques.
@overload locked
@yield [];T;#0;$@];.F;/o;0;1T;2i;3i;%@j[;9I"VALUE
rb_io_buffer_locked(VALUE self)
{
struct rb_io_buffer *data = NULL;
TypedData_Get_Struct(self, struct rb_io_buffer, &rb_io_buffer_type, data);
if (data->flags & RB_IO_BUFFER_LOCKED) {
rb_raise(rb_eIOBufferLockedError, "Buffer already locked!");
}
data->flags |= RB_IO_BUFFER_LOCKED;
VALUE result = rb_yield(self);
data->flags &= ~RB_IO_BUFFER_LOCKED;
return result;
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO::Buffer#slice;F;7[[I" _offset;T0[I" _length;T0;[[@w[i;T;:
slice;0; [ ; { ; IC; "Produce another IO::Buffer which is a slice (or view into) the current one
starting at +offset+ bytes and going for +length+ bytes.
The slicing happens without copying of memory, and the slice keeps being
associated with the original buffer's source (string, or file), if any.
Raises RuntimeError if the offset+length is out of the current
buffer's bounds.
string = 'test'
buffer = IO::Buffer.for(string)
slice = buffer.slice(1, 2)
# =>
# #
# 0x00000000 65 73 es
# Put "o" into 0s position of the slice
slice.set_string('o', 0)
slice
# =>
# #
# 0x00000000 6f 73 os
# it is also visible at position 1 of the original buffer
buffer
# =>
# #
# 0x00000000 74 6f 73 74 tost
# ...and original string
string
# => tost
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"slice(offset, length);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@];.F;Bi ;C0;7[[I" offset;T0[I" length;T0;$@];![ ;"I"+Produce another IO::Buffer which is a slice (or view into) the current one
starting at +offset+ bytes and going for +length+ bytes.
The slicing happens without copying of memory, and the slice keeps being
associated with the original buffer's source (string, or file), if any.
Raises RuntimeError if the offset+length is out of the current
buffer's bounds.
string = 'test'
buffer = IO::Buffer.for(string)
slice = buffer.slice(1, 2)
# =>
# #
# 0x00000000 65 73 es
# Put "o" into 0s position of the slice
slice.set_string('o', 0)
slice
# =>
# # File::WRONLY|File::CREAT).
See the open(2) man page for more information.
When +mode+ is a string it must be in one of the following forms:
fmode
fmode ":" ext_enc
fmode ":" ext_enc ":" int_enc
fmode ":" "BOM|UTF-*"
+fmode+ is an IO open mode string, +ext_enc+ is the external encoding for
the IO and +int_enc+ is the internal encoding.
==== IO Open Mode
Ruby allows the following open modes:
"r" Read-only, starts at beginning of file (default mode).
"r+" Read-write, starts at beginning of file.
"w" Write-only, truncates existing file
to zero length or creates a new file for writing.
"w+" Read-write, truncates existing file to zero length
or creates a new file for reading and writing.
"a" Write-only, each write call appends data at end of file.
Creates a new file for writing if file does not exist.
"a+" Read-write, each write call appends data at end of file.
Creates a new file for reading and writing if file does
not exist.
The following modes must be used separately, and along with one or more of
the modes seen above.
"b" Binary file mode
Suppresses EOL <-> CRLF conversion on Windows. And
sets external encoding to ASCII-8BIT unless explicitly
specified.
"t" Text file mode
The exclusive access mode ("x") can be used together with "w" to ensure
the file is created. Errno::EEXIST is raised when it already exists.
It may not be supported with all kinds of streams (e.g. pipes).
When the open mode of original IO is read only, the mode cannot be
changed to be writable. Similarly, the open mode cannot be changed from
write only to readable.
When such a change is attempted the error is raised in different locations
according to the platform.
=== IO Encoding
When +ext_enc+ is specified, strings read will be tagged by the encoding
when reading, and strings output will be converted to the specified
encoding when writing.
When +ext_enc+ and +int_enc+ are specified read strings will be converted
from +ext_enc+ to +int_enc+ upon input, and written strings will be
converted from +int_enc+ to +ext_enc+ upon output. See Encoding for
further details of transcoding on input and output.
If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, Ruby checks for
a Unicode BOM in the input document to help determine the encoding. For
UTF-16 encodings the file open mode must be binary. When present, the BOM
is stripped and the external encoding from the BOM is used. When the BOM
is missing the given Unicode encoding is used as +ext_enc+. (The BOM-set
encoding option is case insensitive, so "bom|utf-8" is also valid.)
=== Options
+opt+ can be used instead of +mode+ for improved readability. The
following keys are supported:
:mode ::
Same as +mode+ parameter
:flags ::
Specifies file open flags as integer.
If +mode+ parameter is given, this parameter will be bitwise-ORed.
:\external_encoding ::
External encoding for the IO.
:\internal_encoding ::
Internal encoding for the IO. "-" is a synonym for the default internal
encoding.
If the value is +nil+ no conversion occurs.
:encoding ::
Specifies external and internal encodings as "extern:intern".
:textmode ::
If the value is truth value, same as "t" in argument +mode+.
:binmode ::
If the value is truth value, same as "b" in argument +mode+.
:autoclose ::
If the value is +false+, the +fd+ will be kept open after this IO
instance gets finalized.
Also, +opt+ can have same keys in String#encode for controlling conversion
between the external encoding and the internal encoding.
=== Example 1
fd = IO.sysopen("/dev/tty", "w")
a = IO.new(fd,"w")
$stderr.puts "Hello"
a.puts "World"
Produces:
Hello
World
=== Example 2
require 'fcntl'
fd = STDERR.fcntl(Fcntl::F_DUPFD)
io = IO.new(fd, mode: 'w:UTF-16LE', cr_newline: true)
io.puts "Hello, World!"
fd = STDERR.fcntl(Fcntl::F_DUPFD)
io = IO.new(fd, mode: 'w', cr_newline: true,
external_encoding: Encoding::UTF_16LE)
io.puts "Hello, World!"
Both of above print "Hello, World!" in UTF-16LE to standard error output
with converting EOL generated by #puts to CR.
;T; [o;=
;>I"
overload;F;?0;;E;@0;:I" new(fd [, mode] [, opt]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@P;![ ;"I"@return [IO];T;#0;$@P;.F;Bi ;C0;7[[I"fd[, mode][, opt];T0;$@P;![ ;"I"3Returns a new IO object (a stream) for the given integer file descriptor
+fd+ and +mode+ string. +opt+ may be used to specify parts of +mode+ in a
more readable fashion. See also IO.sysopen and IO.for_fd.
IO.new is called by various File and IO opening methods such as IO::open,
Kernel#open, and File::open.
=== Open Mode
When +mode+ is an integer it must be combination of the modes defined in
File::Constants (+File::RDONLY+, File::WRONLY|File::CREAT).
See the open(2) man page for more information.
When +mode+ is a string it must be in one of the following forms:
fmode
fmode ":" ext_enc
fmode ":" ext_enc ":" int_enc
fmode ":" "BOM|UTF-*"
+fmode+ is an IO open mode string, +ext_enc+ is the external encoding for
the IO and +int_enc+ is the internal encoding.
==== IO Open Mode
Ruby allows the following open modes:
"r" Read-only, starts at beginning of file (default mode).
"r+" Read-write, starts at beginning of file.
"w" Write-only, truncates existing file
to zero length or creates a new file for writing.
"w+" Read-write, truncates existing file to zero length
or creates a new file for reading and writing.
"a" Write-only, each write call appends data at end of file.
Creates a new file for writing if file does not exist.
"a+" Read-write, each write call appends data at end of file.
Creates a new file for reading and writing if file does
not exist.
The following modes must be used separately, and along with one or more of
the modes seen above.
"b" Binary file mode
Suppresses EOL <-> CRLF conversion on Windows. And
sets external encoding to ASCII-8BIT unless explicitly
specified.
"t" Text file mode
The exclusive access mode ("x") can be used together with "w" to ensure
the file is created. Errno::EEXIST is raised when it already exists.
It may not be supported with all kinds of streams (e.g. pipes).
When the open mode of original IO is read only, the mode cannot be
changed to be writable. Similarly, the open mode cannot be changed from
write only to readable.
When such a change is attempted the error is raised in different locations
according to the platform.
=== IO Encoding
When +ext_enc+ is specified, strings read will be tagged by the encoding
when reading, and strings output will be converted to the specified
encoding when writing.
When +ext_enc+ and +int_enc+ are specified read strings will be converted
from +ext_enc+ to +int_enc+ upon input, and written strings will be
converted from +int_enc+ to +ext_enc+ upon output. See Encoding for
further details of transcoding on input and output.
If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, Ruby checks for
a Unicode BOM in the input document to help determine the encoding. For
UTF-16 encodings the file open mode must be binary. When present, the BOM
is stripped and the external encoding from the BOM is used. When the BOM
is missing the given Unicode encoding is used as +ext_enc+. (The BOM-set
encoding option is case insensitive, so "bom|utf-8" is also valid.)
=== Options
+opt+ can be used instead of +mode+ for improved readability. The
following keys are supported:
:mode ::
Same as +mode+ parameter
:flags ::
Specifies file open flags as integer.
If +mode+ parameter is given, this parameter will be bitwise-ORed.
:\external_encoding ::
External encoding for the IO.
:\internal_encoding ::
Internal encoding for the IO. "-" is a synonym for the default internal
encoding.
If the value is +nil+ no conversion occurs.
:encoding ::
Specifies external and internal encodings as "extern:intern".
:textmode ::
If the value is truth value, same as "t" in argument +mode+.
:binmode ::
If the value is truth value, same as "b" in argument +mode+.
:autoclose ::
If the value is +false+, the +fd+ will be kept open after this IO
instance gets finalized.
Also, +opt+ can have same keys in String#encode for controlling conversion
between the external encoding and the internal encoding.
=== Example 1
fd = IO.sysopen("/dev/tty", "w")
a = IO.new(fd,"w")
$stderr.puts "Hello"
a.puts "World"
Produces:
Hello
World
=== Example 2
require 'fcntl'
fd = STDERR.fcntl(Fcntl::F_DUPFD)
io = IO.new(fd, mode: 'w:UTF-16LE', cr_newline: true)
io.puts "Hello, World!"
fd = STDERR.fcntl(Fcntl::F_DUPFD)
io = IO.new(fd, mode: 'w', cr_newline: true,
external_encoding: Encoding::UTF_16LE)
io.puts "Hello, World!"
Both of above print "Hello, World!" in UTF-16LE to standard error output
with converting EOL generated by #puts to CR.
@overload new(fd [, mode] [, opt])
@return [IO];T;#0;$@P;.F;/o;0;1T;2i!;3i;";%@kL;9I"*static VALUE
rb_io_initialize(int argc, VALUE *argv, VALUE io)
{
VALUE fnum, vmode;
rb_io_t *fp;
int fd, fmode, oflags = O_RDONLY;
convconfig_t convconfig;
VALUE opt;
#if defined(HAVE_FCNTL) && defined(F_GETFL)
int ofmode;
#else
struct stat st;
#endif
argc = rb_scan_args(argc, argv, "11:", &fnum, &vmode, &opt);
rb_io_extract_modeenc(&vmode, 0, opt, &oflags, &fmode, &convconfig);
fd = NUM2INT(fnum);
if (rb_reserved_fd_p(fd)) {
rb_raise(rb_eArgError, "The given fd is not accessible because RubyVM reserves it");
}
#if defined(HAVE_FCNTL) && defined(F_GETFL)
oflags = fcntl(fd, F_GETFL);
if (oflags == -1) rb_sys_fail(0);
#else
if (fstat(fd, &st) < 0) rb_sys_fail(0);
#endif
rb_update_max_fd(fd);
#if defined(HAVE_FCNTL) && defined(F_GETFL)
ofmode = rb_io_oflags_fmode(oflags);
if (NIL_P(vmode)) {
fmode = ofmode;
}
else if ((~ofmode & fmode) & FMODE_READWRITE) {
VALUE error = INT2FIX(EINVAL);
rb_exc_raise(rb_class_new_instance(1, &error, rb_eSystemCallError));
}
#endif
if (!NIL_P(opt) && rb_hash_aref(opt, sym_autoclose) == Qfalse) {
fmode |= FMODE_PREP;
}
MakeOpenFile(io, fp);
fp->self = io;
fp->fd = fd;
fp->mode = fmode;
fp->encs = convconfig;
clear_codeconv(fp);
io_check_tty(fp);
if (fileno(stdin) == fd)
fp->stdio_file = stdin;
else if (fileno(stdout) == fd)
fp->stdio_file = stdout;
else if (fileno(stderr) == fd)
fp->stdio_file = stderr;
if (fmode & FMODE_SETENC_BY_BOM) io_set_encoding_by_bom(io);
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#initialize_copy;F;7[[I"io;T0;[[@Ti ;T;;];0; [ ; { ; IC; " :nodoc:
;T; [ ;![ ;"I" :nodoc:;T;#0;$@P;.F;/o;0;1T;2i ;3i ;%@kL;9I"static VALUE
rb_io_init_copy(VALUE dest, VALUE io)
{
rb_io_t *fptr, *orig;
int fd;
VALUE write_io;
off_t pos;
io = rb_io_get_io(io);
if (!OBJ_INIT_COPY(dest, io)) return dest;
GetOpenFile(io, orig);
MakeOpenFile(dest, fptr);
rb_io_flush(io);
/* copy rb_io_t structure */
fptr->mode = orig->mode & ~FMODE_PREP;
fptr->encs = orig->encs;
fptr->pid = orig->pid;
fptr->lineno = orig->lineno;
if (!NIL_P(orig->pathv)) fptr->pathv = orig->pathv;
fptr_copy_finalizer(fptr, orig);
fd = ruby_dup(orig->fd);
fptr->fd = fd;
pos = io_tell(orig);
if (0 <= pos)
io_seek(fptr, pos, SEEK_SET);
if (fptr->mode & FMODE_BINMODE) {
rb_io_binmode(dest);
}
write_io = GetWriteIO(io);
if (io != write_io) {
write_io = rb_obj_dup(write_io);
fptr->tied_io_for_writing = write_io;
rb_ivar_set(dest, rb_intern("@tied_io_for_writing"), write_io);
}
return dest;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#reopen;F;7[[@90;[[@Ti ;T;;;0; [ ; { ; IC; "Reassociates ios with the I/O stream given in
other_IO or to a new stream opened on path. This may
dynamically change the actual class of this stream.
The +mode+ and +opt+ parameters accept the same values as IO.open.
f1 = File.new("testfile")
f2 = File.new("testfile")
f2.readlines[0] #=> "This is line one\n"
f2.reopen(f1) #=> #to_s method.
When called without arguments, prints the contents of $_.
If the output field separator ($,) is not +nil+,
it is inserted between objects.
If the output record separator ($\\) is not +nil+,
it is appended to the output.
$stdout.print("This is ", 100, " percent.\n")
produces:
This is 100 percent.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
print;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@P;![ ;"I"@return [nil];T;#0;$@P;.F;Bi ;C0;7[ ;$@Po;=
;>I"
overload;F;?0;;;@0;:I"print(obj, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@P;![ ;"I"@return [nil];T;#0;$@P;.F;Bi ;C0;7[[I"obj;T0[I"...;T0;$@P;![ ;"I"rWrites the given object(s) to ios. Returns +nil+.
The stream must be opened for writing.
Each given object that isn't a string will be converted by calling
its to_s method.
When called without arguments, prints the contents of $_.
If the output field separator ($,) is not +nil+,
it is inserted between objects.
If the output record separator ($\\) is not +nil+,
it is appended to the output.
$stdout.print("This is ", 100, " percent.\n")
produces:
This is 100 percent.
@overload print
@return [nil]
@overload print(obj, ...)
@return [nil];T;#0;$@P;.F;/o;0;1T;2iE ;3i[ ;%@kL;9I"KVALUE
rb_io_print(int argc, const VALUE *argv, VALUE out)
{
int i;
VALUE line;
/* if no argument given, print `$_' */
if (argc == 0) {
argc = 1;
line = rb_lastline_get();
argv = &line;
}
if (argc > 1 && !NIL_P(rb_output_fs)) {
rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "$, is set to non-nil value");
}
for (i=0; i$\\).
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"puts(obj, ...);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@FQ;![ ;"I"@return [nil];T;#0;$@FQ;.F;Bi ;C0;7[[I"obj;T0[I"...;T0;$@FQ;![ ;"I"Writes the given object(s) to ios.
Writes a newline after any that do not already end
with a newline sequence. Returns +nil+.
The stream must be opened for writing.
If called with an array argument, writes each element on a new line.
Each given object that isn't a string or array will be converted
by calling its +to_s+ method.
If called without arguments, outputs a single newline.
$stdout.puts("this", "is", ["a", "test"])
produces:
this
is
a
test
Note that +puts+ always uses newlines and is not affected
by the output record separator ($\\).
@overload puts(obj, ...)
@return [nil];T;#0;$@FQ;.F;/o;0;1T;2i ;3i ;%@kL;9I"VALUE
rb_io_puts(int argc, const VALUE *argv, VALUE out)
{
int i, n;
VALUE line, args[2];
/* if no argument given, print newline. */
if (argc == 0) {
rb_io_write(out, rb_default_rs);
return Qnil;
}
for (i=0; i$/ like #each, #lines and #readline will
also increment #lineno.
See also the $. variable.
f = File.new("testfile")
f.lineno #=> 0
f.gets #=> "This is line one\n"
f.lineno #=> 1
f.gets #=> "This is line two\n"
f.lineno #=> 2
;T; [o;=
;>I"
overload;F;?0;;L;@0;:I" lineno;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@S;![ ;"I"@return [Integer];T;#0;$@S;.F;Bi ;C0;7[ ;$@S;![ ;"I"eReturns the current line number in ios. The stream must be
opened for reading. #lineno counts the number of times #gets is called
rather than the number of newlines encountered. The two values will
differ if #gets is called with a separator other than newline.
Methods that use $/ like #each, #lines and #readline will
also increment #lineno.
See also the $. variable.
f = File.new("testfile")
f.lineno #=> 0
f.gets #=> "This is line one\n"
f.lineno #=> 1
f.gets #=> "This is line two\n"
f.lineno #=> 2
@overload lineno
@return [Integer];T;#0;$@S;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_lineno(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
return INT2NUM(fptr->lineno);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#lineno=;F;7[[I" lineno;T0;[[@Ti
;T;: lineno=;0; [ ; { ; IC; "Manually sets the current line number to the given value.
$. is updated only on the next read.
f = File.new("testfile")
f.gets #=> "This is line one\n"
$. #=> 1
f.lineno = 1000
f.lineno #=> 1000
$. #=> 1 # lineno of last read
f.gets #=> "This is line two\n"
$. #=> 1001 # lineno of last read
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"lineno=(integer);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@S;![ ;"I"@return [Integer];T;#0;$@S;.F;Bi ;C0;7[[I" integer;T0;$@S;![ ;"I" Manually sets the current line number to the given value.
$. is updated only on the next read.
f = File.new("testfile")
f.gets #=> "This is line one\n"
$. #=> 1
f.lineno = 1000
f.lineno #=> 1000
$. #=> 1 # lineno of last read
f.gets #=> "This is line two\n"
$. #=> 1001 # lineno of last read
@overload lineno=(integer)
@return [Integer];T;#0;$@S;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_set_lineno(VALUE io, VALUE lineno)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
fptr->lineno = NUM2INT(lineno);
return lineno;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#readlines;F;7[[@90;[[@TiC;T;;;0; [ ; { ; IC; "oReads all of the lines in ios, and returns them in
an array. Lines are separated by the optional sep. If
sep is +nil+, the rest of the stream is returned
as a single record.
If the first argument is an integer, or an
optional second argument is given, the returning string would not be
longer than the given value in bytes. The stream must be opened for
reading or an IOError will be raised.
f = File.new("testfile")
f.readlines[0] #=> "This is line one\n"
f = File.new("testfile", chomp: true)
f.readlines[0] #=> "This is line one"
See IO.readlines for details about getline_args.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"'readlines(sep=$/ [, getline_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@T;![ ;"I"@return [Array];T;#0;$@T;.F;Bi ;C0;7[[I"sep;TI"$/[, getline_args];T;$@To;=
;>I"
overload;F;?0;;;@0;:I"&readlines(limit [, getline_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@T;![ ;"I"@return [Array];T;#0;$@T;.F;Bi ;C0;7[[I"limit[, getline_args];T0;$@To;=
;>I"
overload;F;?0;;;@0;:I"+readlines(sep, limit [, getline_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"
Array;T;$@T;![ ;"I"@return [Array];T;#0;$@T;.F;Bi ;C0;7[[I"sep;T0[I"limit[, getline_args];T0;$@T;![ ;"I"1Reads all of the lines in ios, and returns them in
an array. Lines are separated by the optional sep. If
sep is +nil+, the rest of the stream is returned
as a single record.
If the first argument is an integer, or an
optional second argument is given, the returning string would not be
longer than the given value in bytes. The stream must be opened for
reading or an IOError will be raised.
f = File.new("testfile")
f.readlines[0] #=> "This is line one\n"
f = File.new("testfile", chomp: true)
f.readlines[0] #=> "This is line one"
See IO.readlines for details about getline_args.
@overload readlines(sep=$/ [, getline_args])
@return [Array]
@overload readlines(limit [, getline_args])
@return [Array]
@overload readlines(sep, limit [, getline_args])
@return [Array];T;#0;$@T;.F;/o;0;1T;2i+;3iB;%@kL;9I"static VALUE
rb_io_readlines(int argc, VALUE *argv, VALUE io)
{
struct getline_arg args;
prepare_getline_args(argc, argv, &args, io);
return io_readlines(&args, io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#readpartial;F;7[[@90;[[@Ti ;T;:readpartial;0; [ ; { ; IC; " Reads up to +maxlen+ bytes from the stream;
returns a string (either a new string or the given +out_string+).
Its encoding is:
- The unchanged encoding of +out_string+, if +out_string+ is given.
- ASCII-8BIT, otherwise.
- Contains +maxlen+ bytes from the stream, if available.
- Otherwise contains all available bytes, if any available.
- Otherwise is an empty string.
With the single non-negative integer argument +maxlen+ given,
returns a new string:
f = File.new('t.txt')
f.readpartial(30) # => "This is line one.\nThis is the"
f.readpartial(30) # => " second line.\nThis is the thi"
f.readpartial(30) # => "rd line.\n"
f.eof # => true
f.readpartial(30) # Raises EOFError.
With both argument +maxlen+ and string argument +out_string+ given,
returns modified +out_string+:
f = File.new('t.txt')
s = 'foo'
f.readpartial(30, s) # => "This is line one.\nThis is the"
s = 'bar'
f.readpartial(0, s) # => ""
This method is useful for a stream such as a pipe, a socket, or a tty.
It blocks only when no data is immediately available.
This means that it blocks only when _all_ of the following are true:
- The byte buffer in the stream is empty.
- The content of the stream is empty.
- The stream is not at EOF.
When blocked, the method waits for either more data or EOF on the stream:
- If more data is read, the method returns the data.
- If EOF is reached, the method raises EOFError.
When not blocked, the method responds immediately:
- Returns data from the buffer if there is any.
- Otherwise returns data from the stream if there is any.
- Otherwise raises EOFError if the stream has reached EOF.
Note that this method is similar to sysread. The differences are:
- If the byte buffer is not empty, read from the byte buffer
instead of "sysread for buffered IO (IOError)".
- It doesn't cause Errno::EWOULDBLOCK and Errno::EINTR. When
readpartial meets EWOULDBLOCK and EINTR by read system call,
readpartial retries the system call.
The latter means that readpartial is non-blocking-flag insensitive.
It blocks on the situation IO#sysread causes Errno::EWOULDBLOCK as
if the fd is blocking mode.
Examples:
# # Returned Buffer Content Pipe Content
r, w = IO.pipe #
w << 'abc' # "" "abc".
r.readpartial(4096) # => "abc" "" ""
r.readpartial(4096) # (Blocks because buffer and pipe are empty.)
# # Returned Buffer Content Pipe Content
r, w = IO.pipe #
w << 'abc' # "" "abc"
w.close # "" "abc" EOF
r.readpartial(4096) # => "abc" "" EOF
r.readpartial(4096) # raises EOFError
# # Returned Buffer Content Pipe Content
r, w = IO.pipe #
w << "abc\ndef\n" # "" "abc\ndef\n"
r.gets # => "abc\n" "def\n" ""
w << "ghi\n" # "def\n" "ghi\n"
r.readpartial(4096) # => "def\n" "" "ghi\n"
r.readpartial(4096) # => "ghi\n" "" ""
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"readpartial(maxlen);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@AT;![ ;"I"@return [String];T;#0;$@AT;.F;Bi ;C0;7[[I" maxlen;T0;$@ATo;=
;>I"
overload;F;?0;;;@0;:I"$readpartial(maxlen, out_string);T; IC; " ;T; [ ;![ ;"I" ;T;#0;$@AT;.F;Bi ;C0;7[[I" maxlen;T0[I"out_string;T0;$@AT;![ ;"I"4
Reads up to +maxlen+ bytes from the stream;
returns a string (either a new string or the given +out_string+).
Its encoding is:
- The unchanged encoding of +out_string+, if +out_string+ is given.
- ASCII-8BIT, otherwise.
- Contains +maxlen+ bytes from the stream, if available.
- Otherwise contains all available bytes, if any available.
- Otherwise is an empty string.
With the single non-negative integer argument +maxlen+ given,
returns a new string:
f = File.new('t.txt')
f.readpartial(30) # => "This is line one.\nThis is the"
f.readpartial(30) # => " second line.\nThis is the thi"
f.readpartial(30) # => "rd line.\n"
f.eof # => true
f.readpartial(30) # Raises EOFError.
With both argument +maxlen+ and string argument +out_string+ given,
returns modified +out_string+:
f = File.new('t.txt')
s = 'foo'
f.readpartial(30, s) # => "This is line one.\nThis is the"
s = 'bar'
f.readpartial(0, s) # => ""
This method is useful for a stream such as a pipe, a socket, or a tty.
It blocks only when no data is immediately available.
This means that it blocks only when _all_ of the following are true:
- The byte buffer in the stream is empty.
- The content of the stream is empty.
- The stream is not at EOF.
When blocked, the method waits for either more data or EOF on the stream:
- If more data is read, the method returns the data.
- If EOF is reached, the method raises EOFError.
When not blocked, the method responds immediately:
- Returns data from the buffer if there is any.
- Otherwise returns data from the stream if there is any.
- Otherwise raises EOFError if the stream has reached EOF.
Note that this method is similar to sysread. The differences are:
- If the byte buffer is not empty, read from the byte buffer
instead of "sysread for buffered IO (IOError)".
- It doesn't cause Errno::EWOULDBLOCK and Errno::EINTR. When
readpartial meets EWOULDBLOCK and EINTR by read system call,
readpartial retries the system call.
The latter means that readpartial is non-blocking-flag insensitive.
It blocks on the situation IO#sysread causes Errno::EWOULDBLOCK as
if the fd is blocking mode.
Examples:
# # Returned Buffer Content Pipe Content
r, w = IO.pipe #
w << 'abc' # "" "abc".
r.readpartial(4096) # => "abc" "" ""
r.readpartial(4096) # (Blocks because buffer and pipe are empty.)
# # Returned Buffer Content Pipe Content
r, w = IO.pipe #
w << 'abc' # "" "abc"
w.close # "" "abc" EOF
r.readpartial(4096) # => "abc" "" EOF
r.readpartial(4096) # raises EOFError
# # Returned Buffer Content Pipe Content
r, w = IO.pipe #
w << "abc\ndef\n" # "" "abc\ndef\n"
r.gets # => "abc\n" "def\n" ""
w << "ghi\n" # "def\n" "ghi\n"
r.readpartial(4096) # => "def\n" "" "ghi\n"
r.readpartial(4096) # => "ghi\n" "" ""
@overload readpartial(maxlen)
@return [String]
@overload readpartial(maxlen, out_string);T;#0;$@AT;.F;/o;0;1T;2i ;3i ;%@kL;9I"static VALUE
io_readpartial(int argc, VALUE *argv, VALUE io)
{
VALUE ret;
ret = io_getpartial(argc, argv, io, Qnil, 0);
if (NIL_P(ret))
rb_eof_error();
return ret;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#read;F;7[[@90;[[@Ti
;T;;q;0; [ ; { ; IC; "oReads bytes from the stream (in binary mode):
- If +maxlen+ is +nil+, reads all bytes.
- Otherwise reads +maxlen+ bytes, if available.
- Otherwise reads all bytes.
Returns a string (either a new string or the given +out_string+)
containing the bytes read.
The encoding of the string depends on both +maxLen+ and +out_string+:
- +maxlen+ is +nil+: uses internal encoding of +self+
(regardless of whether +out_string+ was given).
- +maxlen+ not +nil+:
- +out_string+ given: encoding of +out_string+ not modified.
- +out_string+ not given: ASCII-8BIT is used.
Without Argument +out_string+
When argument +out_string+ is omitted,
the returned value is a new string:
f = File.new('t.txt')
f.read
# => "This is line one.\nThis is the second line.\nThis is the third line.\n"
f.rewind
f.read(40) # => "This is line one.\r\nThis is the second li"
f.read(40) # => "ne.\r\nThis is the third line.\r\n"
f.read(40) # => nil
If +maxlen+ is zero, returns an empty string.
With Argument +out_string+
When argument +out_string+ is given,
the returned value is +out_string+, whose content is replaced:
f = File.new('t.txt')
s = 'foo' # => "foo"
f.read(nil, s) # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
s # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
f.rewind
s = 'bar'
f.read(40, s) # => "This is line one.\r\nThis is the second li"
s # => "This is line one.\r\nThis is the second li"
s = 'baz'
f.read(40, s) # => "ne.\r\nThis is the third line.\r\n"
s # => "ne.\r\nThis is the third line.\r\n"
s = 'bat'
f.read(40, s) # => nil
s # => ""
Note that this method behaves like the fread() function in C.
This means it retries to invoke read(2) system calls to read data
with the specified maxlen (or until EOF).
This behavior is preserved even if the stream is in non-blocking mode.
(This method is non-blocking-flag insensitive as other methods.)
If you need the behavior like a single read(2) system call,
consider #readpartial, #read_nonblock, and #sysread.
;T; [o;=
;>I"
overload;F;?0;;q;@0;:I"read(maxlen = nil);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;TI"nil;T;$@kT;![ ;"I"@return [String, nil];T;#0;$@kT;.F;Bi ;C0;7[[I" maxlen;TI"nil;T;$@kTo;=
;>I"
overload;F;?0;;q;@0;:I"#read(maxlen = nil, out_string);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@kT;![ ;"I"@return [nil];T;#0;$@kT;.F;Bi ;C0;7[[I" maxlen;TI"nil;T[I"out_string;T0;$@kT;![ ;"I"Reads bytes from the stream (in binary mode):
- If +maxlen+ is +nil+, reads all bytes.
- Otherwise reads +maxlen+ bytes, if available.
- Otherwise reads all bytes.
Returns a string (either a new string or the given +out_string+)
containing the bytes read.
The encoding of the string depends on both +maxLen+ and +out_string+:
- +maxlen+ is +nil+: uses internal encoding of +self+
(regardless of whether +out_string+ was given).
- +maxlen+ not +nil+:
- +out_string+ given: encoding of +out_string+ not modified.
- +out_string+ not given: ASCII-8BIT is used.
Without Argument +out_string+
When argument +out_string+ is omitted,
the returned value is a new string:
f = File.new('t.txt')
f.read
# => "This is line one.\nThis is the second line.\nThis is the third line.\n"
f.rewind
f.read(40) # => "This is line one.\r\nThis is the second li"
f.read(40) # => "ne.\r\nThis is the third line.\r\n"
f.read(40) # => nil
If +maxlen+ is zero, returns an empty string.
With Argument +out_string+
When argument +out_string+ is given,
the returned value is +out_string+, whose content is replaced:
f = File.new('t.txt')
s = 'foo' # => "foo"
f.read(nil, s) # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
s # => "This is line one.\nThis is the second line.\nThis is the third line.\n"
f.rewind
s = 'bar'
f.read(40, s) # => "This is line one.\r\nThis is the second li"
s # => "This is line one.\r\nThis is the second li"
s = 'baz'
f.read(40, s) # => "ne.\r\nThis is the third line.\r\n"
s # => "ne.\r\nThis is the third line.\r\n"
s = 'bat'
f.read(40, s) # => nil
s # => ""
Note that this method behaves like the fread() function in C.
This means it retries to invoke read(2) system calls to read data
with the specified maxlen (or until EOF).
This behavior is preserved even if the stream is in non-blocking mode.
(This method is non-blocking-flag insensitive as other methods.)
If you need the behavior like a single read(2) system call,
consider #readpartial, #read_nonblock, and #sysread.
@overload read(maxlen = nil)
@return [String, nil]
@overload read(maxlen = nil, out_string)
@return [nil];T;#0;$@kT;.F;/o;0;1T;2i^
;3i
;%@kL;9I"static VALUE
io_read(int argc, VALUE *argv, VALUE io)
{
rb_io_t *fptr;
long n, len;
VALUE length, str;
int shrinkable;
#if RUBY_CRLF_ENVIRONMENT
int previous_mode;
#endif
rb_scan_args(argc, argv, "02", &length, &str);
if (NIL_P(length)) {
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
return read_all(fptr, remain_size(fptr), str);
}
len = NUM2LONG(length);
if (len < 0) {
rb_raise(rb_eArgError, "negative length %ld given", len);
}
shrinkable = io_setstrbuf(&str,len);
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
if (len == 0) {
io_set_read_length(str, 0, shrinkable);
return str;
}
READ_CHECK(fptr);
#if RUBY_CRLF_ENVIRONMENT
previous_mode = set_binary_mode_with_seek_cur(fptr);
#endif
n = io_fread(str, 0, len, fptr);
io_set_read_length(str, n, shrinkable);
#if RUBY_CRLF_ENVIRONMENT
if (previous_mode == O_TEXT) {
setmode(fptr->fd, O_TEXT);
}
#endif
if (n == 0) return Qnil;
return str;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#write;F;7[[@90;[[@Ti;T;;s;0; [ ; { ; IC; "uWrites each of the given +objects+ to +self+,
which must be opened for writing (see {Modes}[#class-IO-label-Modes]);
returns the total number bytes written;
each of +objects+ that is not a string is converted via method +to_s+:
$stdout.write('Hello', ', ', 'World!', "\n") # => 14
$stdout.write('foo', :bar, 2, "\n") # => 8
Output:
Hello, World!
foobar2
;T; [o;=
;>I"
overload;F;?0;;s;@0;:I"write(*objects);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@T;![ ;"I"@return [Integer];T;#0;$@T;.F;Bi ;C0;7[[I"
*objects;T0;$@T;![ ;"I"Writes each of the given +objects+ to +self+,
which must be opened for writing (see {Modes}[#class-IO-label-Modes]);
returns the total number bytes written;
each of +objects+ that is not a string is converted via method +to_s+:
$stdout.write('Hello', ', ', 'World!', "\n") # => 14
$stdout.write('foo', :bar, 2, "\n") # => 8
Output:
Hello, World!
foobar2
@overload write(*objects)
@return [Integer];T;#0;$@T;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
io_write_m(int argc, VALUE *argv, VALUE io)
{
if (argc != 1) {
return io_writev(argc, argv, io);
}
else {
VALUE str = argv[0];
return io_write(io, str, 0);
}
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#gets;F;7[[@90;[[@Ti;T;;;0; [ ; { ; IC; " Reads and returns data from the stream;
assigns the return value to $_.
With no arguments given, returns the next line
as determined by line separator $/, or +nil+ if none:
f = File.open('t.txt')
f.gets # => "This is line one.\n"
$_ # => "This is line one.\n"
f.gets # => "This is the second line.\n"
f.gets # => "This is the third line.\n"
f.gets # => nil
With string argument +sep+ given, but not argument +limit+,
returns the next line as determined by line separator +sep+,
or +nil+ if none:
f = File.open('t.txt')
f.gets(' is') # => "This is"
f.gets(' is') # => " line one.\nThis is"
f.gets(' is') # => " the second line.\nThis is"
f.gets(' is') # => " the third line.\n"
f.gets(' is') # => nil
Note two special values for +sep+:
- +nil+: The entire stream is read and returned.
- '' (empty string): The next "paragraph" is read and returned,
the paragraph separator being two successive line separators.
With integer argument +limit+ given,
returns up to limit+1 bytes:
# Text with 1-byte characters.
File.open('t.txt') {|f| f.gets(1) } # => "T"
File.open('t.txt') {|f| f.gets(2) } # => "Th"
File.open('t.txt') {|f| f.gets(3) } # => "Thi"
File.open('t.txt') {|f| f.gets(4) } # => "This"
# No more than one line.
File.open('t.txt') {|f| f.gets(17) } # => "This is line one."
File.open('t.txt') {|f| f.gets(18) } # => "This is line one.\n"
File.open('t.txt') {|f| f.gets(19) } # => "This is line one.\n"
# Text with 2-byte characters, which will not be split.
File.open('t.rus') {|f| f.gets(1).size } # => 1
File.open('t.rus') {|f| f.gets(2).size } # => 1
File.open('t.rus') {|f| f.gets(3).size } # => 2
File.open('t.rus') {|f| f.gets(4).size } # => 2
With arguments +sep+ and +limit+,
combines the two behaviors above:
- Returns the next line as determined by line separator +sep+,
or +nil+ if none.
- But returns no more than limit+1 bytes.
For all forms above, trailing optional keyword arguments may be given;
see {Getline Options}[#class-IO-label-Getline+Options]:
f = File.open('t.txt')
# Chomp the lines.
f.gets(chomp: true) # => "This is line one."
f.gets(chomp: true) # => "This is the second line."
f.gets(chomp: true) # => "This is the third line."
f.gets(chomp: true) # => nil
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"#gets(sep = $/, **getline_opts);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;TI"nil;T;$@T;![ ;"I"@return [String, nil];T;#0;$@T;.F;Bi ;C0;7[[I"sep;TI"$/;T[I"**getline_opts;T0;$@To;=
;>I"
overload;F;?0;;;@0;:I" gets(limit, **getline_opts);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;TI"nil;T;$@T;![ ;"I"@return [String, nil];T;#0;$@T;.F;Bi ;C0;7[[I"
limit;T0[I"**getline_opts;T0;$@To;=
;>I"
overload;F;?0;;;@0;:I"%gets(sep, limit, **getline_opts);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;TI"nil;T;$@T;![ ;"I"@return [String, nil];T;#0;$@T;.F;Bi ;C0;7[[I"sep;T0[I"
limit;T0[I"**getline_opts;T0;$@T;![ ;"I" Reads and returns data from the stream;
assigns the return value to $_.
With no arguments given, returns the next line
as determined by line separator $/, or +nil+ if none:
f = File.open('t.txt')
f.gets # => "This is line one.\n"
$_ # => "This is line one.\n"
f.gets # => "This is the second line.\n"
f.gets # => "This is the third line.\n"
f.gets # => nil
With string argument +sep+ given, but not argument +limit+,
returns the next line as determined by line separator +sep+,
or +nil+ if none:
f = File.open('t.txt')
f.gets(' is') # => "This is"
f.gets(' is') # => " line one.\nThis is"
f.gets(' is') # => " the second line.\nThis is"
f.gets(' is') # => " the third line.\n"
f.gets(' is') # => nil
Note two special values for +sep+:
- +nil+: The entire stream is read and returned.
- '' (empty string): The next "paragraph" is read and returned,
the paragraph separator being two successive line separators.
With integer argument +limit+ given,
returns up to limit+1 bytes:
# Text with 1-byte characters.
File.open('t.txt') {|f| f.gets(1) } # => "T"
File.open('t.txt') {|f| f.gets(2) } # => "Th"
File.open('t.txt') {|f| f.gets(3) } # => "Thi"
File.open('t.txt') {|f| f.gets(4) } # => "This"
# No more than one line.
File.open('t.txt') {|f| f.gets(17) } # => "This is line one."
File.open('t.txt') {|f| f.gets(18) } # => "This is line one.\n"
File.open('t.txt') {|f| f.gets(19) } # => "This is line one.\n"
# Text with 2-byte characters, which will not be split.
File.open('t.rus') {|f| f.gets(1).size } # => 1
File.open('t.rus') {|f| f.gets(2).size } # => 1
File.open('t.rus') {|f| f.gets(3).size } # => 2
File.open('t.rus') {|f| f.gets(4).size } # => 2
With arguments +sep+ and +limit+,
combines the two behaviors above:
- Returns the next line as determined by line separator +sep+,
or +nil+ if none.
- But returns no more than limit+1 bytes.
For all forms above, trailing optional keyword arguments may be given;
see {Getline Options}[#class-IO-label-Getline+Options]:
f = File.open('t.txt')
# Chomp the lines.
f.gets(chomp: true) # => "This is line one."
f.gets(chomp: true) # => "This is the second line."
f.gets(chomp: true) # => "This is the third line."
f.gets(chomp: true) # => nil
@overload gets(sep = $/, **getline_opts)
@return [String, nil]
@overload gets(limit, **getline_opts)
@return [String, nil]
@overload gets(sep, limit, **getline_opts)
@return [String, nil];T;#0;$@T;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_gets_m(int argc, VALUE *argv, VALUE io)
{
VALUE str;
str = rb_io_getline(argc, argv, io);
rb_lastline_set(str);
return str;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#readline;F;7[[@90;[[@Ti ;T;;;0; [ ; { ; IC; "IReads a line as with IO#gets, but raises an EOFError on end of file.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"&readline(sep=$/ [, getline_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@U;![ ;"I"@return [String];T;#0;$@U;.F;Bi ;C0;7[[I"sep;TI"$/[, getline_args];T;$@Uo;=
;>I"
overload;F;?0;;;@0;:I"%readline(limit [, getline_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@U;![ ;"I"@return [String];T;#0;$@U;.F;Bi ;C0;7[[I"limit[, getline_args];T0;$@Uo;=
;>I"
overload;F;?0;;;@0;:I"*readline(sep, limit [, getline_args]);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@U;![ ;"I"@return [String];T;#0;$@U;.F;Bi ;C0;7[[I"sep;T0[I"limit[, getline_args];T0;$@U;![ ;"I"Reads a line as with IO#gets, but raises an EOFError on end of file.
@overload readline(sep=$/ [, getline_args])
@return [String]
@overload readline(limit [, getline_args])
@return [String]
@overload readline(sep, limit [, getline_args])
@return [String];T;#0;$@U;.F;/o;0;1T;2i;3i ;%@kL;9I"static VALUE
rb_io_readline(int argc, VALUE *argv, VALUE io)
{
VALUE line = rb_io_gets_m(argc, argv, io);
if (NIL_P(line)) {
rb_eof_error();
}
return line;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#getc;F;7[ ;[[@Ti;T;: getc;0; [ ; { ; IC; "Reads a one-character string from ios. Returns
+nil+ if called at end of file.
f = File.new("testfile")
f.getc #=> "h"
f.getc #=> "e"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" getc;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;TI"nil;T;$@BU;![ ;"I"@return [String, nil];T;#0;$@BU;.F;Bi ;C0;7[ ;$@BU;![ ;"I"Reads a one-character string from ios. Returns
+nil+ if called at end of file.
f = File.new("testfile")
f.getc #=> "h"
f.getc #=> "e"
@overload getc
@return [String, nil];T;#0;$@BU;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_getc(VALUE io)
{
rb_io_t *fptr;
rb_encoding *enc;
GetOpenFile(io, fptr);
rb_io_check_char_readable(fptr);
enc = io_input_encoding(fptr);
READ_CHECK(fptr);
return io_getc(fptr, enc);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#getbyte;F;7[ ;[[@Ti;T;;;0; [ ; { ; IC; "Gets the next 8-bit byte (0..255) from ios. Returns
+nil+ if called at end of file.
f = File.new("testfile")
f.getbyte #=> 84
f.getbyte #=> 104
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" getbyte;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;TI"nil;T;$@^U;![ ;"I"@return [Integer, nil];T;#0;$@^U;.F;Bi ;C0;7[ ;$@^U;![ ;"I"Gets the next 8-bit byte (0..255) from ios. Returns
+nil+ if called at end of file.
f = File.new("testfile")
f.getbyte #=> 84
f.getbyte #=> 104
@overload getbyte
@return [Integer, nil];T;#0;$@^U;.F;/o;0;1T;2i;3i;%@kL;9I"\VALUE
rb_io_getbyte(VALUE io)
{
rb_io_t *fptr;
int c;
GetOpenFile(io, fptr);
rb_io_check_byte_readable(fptr);
READ_CHECK(fptr);
VALUE r_stdout = rb_ractor_stdout();
if (fptr->fd == 0 && (fptr->mode & FMODE_TTY) && RB_TYPE_P(r_stdout, T_FILE)) {
rb_io_t *ofp;
GetOpenFile(r_stdout, ofp);
if (ofp->mode & FMODE_TTY) {
rb_io_flush(r_stdout);
}
}
if (io_fillbuf(fptr) < 0) {
return Qnil;
}
fptr->rbuf.off++;
fptr->rbuf.len--;
c = (unsigned char)fptr->rbuf.ptr[fptr->rbuf.off-1];
return INT2FIX(c & 0xff);
};T;:I"
VALUE;T;;To;4;5F;6;;; ;&I"IO#readchar;F;7[ ;[[@Ti;T;:
readchar;0; [ ; { ; IC; "Reads a one-character string from ios. Raises an
EOFError on end of file.
f = File.new("testfile")
f.readchar #=> "h"
f.readchar #=> "e"
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
readchar;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" String;T;$@zU;![ ;"I"@return [String];T;#0;$@zU;.F;Bi ;C0;7[ ;$@zU;![ ;"I"Reads a one-character string from ios. Raises an
EOFError on end of file.
f = File.new("testfile")
f.readchar #=> "h"
f.readchar #=> "e"
@overload readchar
@return [String];T;#0;$@zU;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_readchar(VALUE io)
{
VALUE c = rb_io_getc(io);
if (NIL_P(c)) {
rb_eof_error();
}
return c;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#readbyte;F;7[ ;[[@Ti;T;:
readbyte;0; [ ; { ; IC; "LReads a byte as with IO#getbyte, but raises an EOFError on end of
file.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
readbyte;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@U;![ ;"I"@return [Integer];T;#0;$@U;.F;Bi ;C0;7[ ;$@U;![ ;"I"uReads a byte as with IO#getbyte, but raises an EOFError on end of
file.
@overload readbyte
@return [Integer];T;#0;$@U;.F;/o;0;1T;2i;3i
;%@kL;9I"static VALUE
rb_io_readbyte(VALUE io)
{
VALUE c = rb_io_getbyte(io);
if (NIL_P(c)) {
rb_eof_error();
}
return c;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#ungetbyte;F;7[[I"b;T0;[[@Ti?;T;:ungetbyte;0; [ ; { ; IC; "dPushes back bytes (passed as a parameter) onto ios,
such that a subsequent buffered read will return it.
It is only guaranteed to support a single byte, and only if ungetbyte
or ungetc has not already been called on ios since the previous
read of at least a single byte from ios.
However, it can support additional bytes if there is space in the
internal buffer to allow for it.
f = File.new("testfile") #=> #true if ios will be closed on exec.
f = open("/dev/null")
f.close_on_exec? #=> false
f.close_on_exec = true
f.close_on_exec? #=> true
f.close_on_exec = false
f.close_on_exec? #=> false;T; [o;=
;>I"
overload;F;?0;;;@0;:I"close_on_exec?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@BW;![ ;"I"@return [Boolean];T;#0;$@BW;.F;Bi ;C0;7[ ;$@BW;![ ;"I"HReturns true if ios will be closed on exec.
f = open("/dev/null")
f.close_on_exec? #=> false
f.close_on_exec = true
f.close_on_exec? #=> true
f.close_on_exec = false
f.close_on_exec? #=> false
@overload close_on_exec?
@return [Boolean];T;#0;$@BW;.F;/o;0;1T;2i;3i;Bi ;%@kL;9I"astatic VALUE
rb_io_close_on_exec_p(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
int fd, ret;
write_io = GetWriteIO(io);
if (io != write_io) {
GetOpenFile(write_io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if (!(ret & FD_CLOEXEC)) return Qfalse;
}
}
GetOpenFile(io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if (!(ret & FD_CLOEXEC)) return Qfalse;
}
return Qtrue;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#close_on_exec=;F;7[[I"arg;T0;[[@Ti;T;:close_on_exec=;0; [ ; { ; IC; "FSets a close-on-exec flag.
f = open("/dev/null")
f.close_on_exec = true
system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
f.closed? #=> false
Ruby sets close-on-exec flags of all file descriptors by default
since Ruby 2.0.0.
So you don't need to set by yourself.
Also, unsetting a close-on-exec flag can cause file descriptor leak
if another thread use fork() and exec() (via system() method for example).
If you really needs file descriptor inheritance to child process,
use spawn()'s argument such as fd=>fd.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"close_on_exec=(bool);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@]W;![ ;"I"@return [Boolean];T;#0;$@]W;.F;Bi ;C0;7[[I" bool;T0;$@]W;![ ;"I"{Sets a close-on-exec flag.
f = open("/dev/null")
f.close_on_exec = true
system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
f.closed? #=> false
Ruby sets close-on-exec flags of all file descriptors by default
since Ruby 2.0.0.
So you don't need to set by yourself.
Also, unsetting a close-on-exec flag can cause file descriptor leak
if another thread use fork() and exec() (via system() method for example).
If you really needs file descriptor inheritance to child process,
use spawn()'s argument such as fd=>fd.
@overload close_on_exec=(bool)
@return [Boolean];T;#0;$@]W;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_set_close_on_exec(VALUE io, VALUE arg)
{
int flag = RTEST(arg) ? FD_CLOEXEC : 0;
rb_io_t *fptr;
VALUE write_io;
int fd, ret;
write_io = GetWriteIO(io);
if (io != write_io) {
GetOpenFile(write_io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fptr->fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if ((ret & FD_CLOEXEC) != flag) {
ret = (ret & ~FD_CLOEXEC) | flag;
ret = fcntl(fd, F_SETFD, ret);
if (ret != 0) rb_sys_fail_path(fptr->pathv);
}
}
}
GetOpenFile(io, fptr);
if (fptr && 0 <= (fd = fptr->fd)) {
if ((ret = fcntl(fd, F_GETFD)) == -1) rb_sys_fail_path(fptr->pathv);
if ((ret & FD_CLOEXEC) != flag) {
ret = (ret & ~FD_CLOEXEC) | flag;
ret = fcntl(fd, F_SETFD, ret);
if (ret != 0) rb_sys_fail_path(fptr->pathv);
}
}
return Qnil;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#close;F;7[ ;[[@Ti;T;;;0; [ ; { ; IC; "Closes ios and flushes any pending writes to the operating
system. The stream is unavailable for any further data operations;
an IOError is raised if such an attempt is made. I/O streams are
automatically closed when they are claimed by the garbage collector.
If ios is opened by IO.popen, #close sets
$?.
Calling this method on closed IO object is just ignored since Ruby 2.3.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
close;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@|W;![ ;"I"@return [nil];T;#0;$@|W;.F;Bi ;C0;7[ ;$@|W;![ ;"I"Closes ios and flushes any pending writes to the operating
system. The stream is unavailable for any further data operations;
an IOError is raised if such an attempt is made. I/O streams are
automatically closed when they are claimed by the garbage collector.
If ios is opened by IO.popen, #close sets
$?.
Calling this method on closed IO object is just ignored since Ruby 2.3.
@overload close
@return [nil];T;#0;$@|W;.F;/o;0;1T;2i};3i;%@kL;9I"static VALUE
rb_io_close_m(VALUE io)
{
rb_io_t *fptr = rb_io_get_fptr(io);
if (fptr->fd < 0) {
return Qnil;
}
rb_io_close(io);
return Qnil;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#closed?;F;7[ ;[[@Ti;T;;\;0; [ ; { ; IC; "mReturns true if ios is completely closed (for
duplex streams, both reader and writer), false
otherwise.
f = File.new("testfile")
f.close #=> nil
f.closed? #=> true
f = IO.popen("/bin/sh","r+")
f.close_write #=> nil
f.closed? #=> false
f.close_read #=> nil
f.closed? #=> true;T; [o;=
;>I"
overload;F;?0;;\;@0;:I" closed?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@W;![ ;"I"@return [Boolean];T;#0;$@W;.F;Bi ;C0;7[ ;$@W;![ ;"I"Returns true if ios is completely closed (for
duplex streams, both reader and writer), false
otherwise.
f = File.new("testfile")
f.close #=> nil
f.closed? #=> true
f = IO.popen("/bin/sh","r+")
f.close_write #=> nil
f.closed? #=> false
f.close_read #=> nil
f.closed? #=> true
@overload closed?
@return [Boolean];T;#0;$@W;.F;/o;0;1T;2i;3i;Bi ;%@kL;9I"istatic VALUE
rb_io_closed(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
rb_io_t *write_fptr;
write_io = GetWriteIO(io);
if (io != write_io) {
write_fptr = RFILE(write_io)->fptr;
if (write_fptr && 0 <= write_fptr->fd) {
return Qfalse;
}
}
fptr = rb_io_get_fptr(io);
return RBOOL(0 > fptr->fd);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#close_read;F;7[ ;[[@Ti;T;:close_read;0; [ ; { ; IC; "Closes the read end of a duplex I/O stream (i.e., one that contains
both a read and a write stream, such as a pipe). Will raise an
IOError if the stream is not duplexed.
f = IO.popen("/bin/sh","r+")
f.close_read
f.readlines
produces:
prog.rb:3:in `readlines': not opened for reading (IOError)
from prog.rb:3
Calling this method on closed IO object is just ignored since Ruby 2.3.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"close_read;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@W;![ ;"I"@return [nil];T;#0;$@W;.F;Bi ;C0;7[ ;$@W;![ ;"I"Closes the read end of a duplex I/O stream (i.e., one that contains
both a read and a write stream, such as a pipe). Will raise an
IOError if the stream is not duplexed.
f = IO.popen("/bin/sh","r+")
f.close_read
f.readlines
produces:
prog.rb:3:in `readlines': not opened for reading (IOError)
from prog.rb:3
Calling this method on closed IO object is just ignored since Ruby 2.3.
@overload close_read
@return [nil];T;#0;$@W;.F;/o;0;1T;2i;3i;%@kL;9I"cstatic VALUE
rb_io_close_read(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
fptr = rb_io_get_fptr(rb_io_taint_check(io));
if (fptr->fd < 0) return Qnil;
if (is_socket(fptr->fd, fptr->pathv)) {
#ifndef SHUT_RD
# define SHUT_RD 0
#endif
if (shutdown(fptr->fd, SHUT_RD) < 0)
rb_sys_fail_path(fptr->pathv);
fptr->mode &= ~FMODE_READABLE;
if (!(fptr->mode & FMODE_WRITABLE))
return rb_io_close(io);
return Qnil;
}
write_io = GetWriteIO(io);
if (io != write_io) {
rb_io_t *wfptr;
wfptr = rb_io_get_fptr(rb_io_taint_check(write_io));
wfptr->pid = fptr->pid;
fptr->pid = 0;
RFILE(io)->fptr = wfptr;
/* bind to write_io temporarily to get rid of memory/fd leak */
fptr->tied_io_for_writing = 0;
RFILE(write_io)->fptr = fptr;
rb_io_fptr_cleanup(fptr, FALSE);
/* should not finalize fptr because another thread may be reading it */
return Qnil;
}
if ((fptr->mode & (FMODE_DUPLEX|FMODE_WRITABLE)) == FMODE_WRITABLE) {
rb_raise(rb_eIOError, "closing non-duplex IO for reading");
}
return rb_io_close(io);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#close_write;F;7[ ;[[@Ti-;T;:close_write;0; [ ; { ; IC; "Closes the write end of a duplex I/O stream (i.e., one that contains
both a read and a write stream, such as a pipe). Will raise an
IOError if the stream is not duplexed.
f = IO.popen("/bin/sh","r+")
f.close_write
f.print "nowhere"
produces:
prog.rb:3:in `write': not opened for writing (IOError)
from prog.rb:3:in `print'
from prog.rb:3
Calling this method on closed IO object is just ignored since Ruby 2.3.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"close_write;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@W;![ ;"I"@return [nil];T;#0;$@W;.F;Bi ;C0;7[ ;$@W;![ ;"I"Closes the write end of a duplex I/O stream (i.e., one that contains
both a read and a write stream, such as a pipe). Will raise an
IOError if the stream is not duplexed.
f = IO.popen("/bin/sh","r+")
f.close_write
f.print "nowhere"
produces:
prog.rb:3:in `write': not opened for writing (IOError)
from prog.rb:3:in `print'
from prog.rb:3
Calling this method on closed IO object is just ignored since Ruby 2.3.
@overload close_write
@return [nil];T;#0;$@W;.F;/o;0;1T;2i;3i*;%@kL;9I"7static VALUE
rb_io_close_write(VALUE io)
{
rb_io_t *fptr;
VALUE write_io;
write_io = GetWriteIO(io);
fptr = rb_io_get_fptr(rb_io_taint_check(write_io));
if (fptr->fd < 0) return Qnil;
if (is_socket(fptr->fd, fptr->pathv)) {
#ifndef SHUT_WR
# define SHUT_WR 1
#endif
if (shutdown(fptr->fd, SHUT_WR) < 0)
rb_sys_fail_path(fptr->pathv);
fptr->mode &= ~FMODE_WRITABLE;
if (!(fptr->mode & FMODE_READABLE))
return rb_io_close(write_io);
return Qnil;
}
if ((fptr->mode & (FMODE_DUPLEX|FMODE_READABLE)) == FMODE_READABLE) {
rb_raise(rb_eIOError, "closing non-duplex IO for writing");
}
if (io != write_io) {
fptr = rb_io_get_fptr(rb_io_taint_check(io));
fptr->tied_io_for_writing = 0;
}
rb_io_close(write_io);
return Qnil;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#isatty;F;7[ ;[[@Ti;T;: isatty;0; [ ; { ; IC; "Returns true if ios is associated with a
terminal device (tty), false otherwise.
File.new("testfile").isatty #=> false
File.new("/dev/tty").isatty #=> true
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" isatty;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@W;![ ;"I"@return [Boolean];T;#0;$@W;.F;Bi ;C0;7[ ;$@Wo;=
;>I"
overload;F;?0;: tty?;@0;:I" tty?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@W;![ ;"I"@return [Boolean];T;#0;$@W;.F;Bi ;C0;7[ ;$@W;![ ;"I"Returns true if ios is associated with a
terminal device (tty), false otherwise.
File.new("testfile").isatty #=> false
File.new("/dev/tty").isatty #=> true
@overload isatty
@return [Boolean]
@overload tty?
@return [Boolean];T;#0;$@W;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_isatty(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
return RBOOL(isatty(fptr->fd) != 0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#tty?;F;7[ ;[[@Ti;T;;;0; [ ; { ; IC; "Returns true if ios is associated with a
terminal device (tty), false otherwise.
File.new("testfile").isatty #=> false
File.new("/dev/tty").isatty #=> true;T; [o;=
;>I"
overload;F;?0;;;@0;:I" isatty;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@X;![ ;"I"@return [Boolean];T;#0;$@X;.F;Bi ;C0;7[ ;$@Xo;=
;>I"
overload;F;?0;;;@0;:I" tty?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@X;![ ;"I"@return [Boolean];T;#0;$@X;.F;Bi ;C0;7[ ;$@X;![ ;"@ X;#0;$@X;.F;/o;0;1T;2i;3i;Bi ;%@kL;9I"static VALUE
rb_io_isatty(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
return RBOOL(isatty(fptr->fd) != 0);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#binmode;F;7[ ;[[@Ti;T;: binmode;0; [ ; { ; IC; "Puts ios into binary mode.
Once a stream is in binary mode, it cannot be reset to nonbinary mode.
- newline conversion disabled
- encoding conversion disabled
- content is treated as ASCII-8BIT
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" binmode;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"IO;T;$@7X;![ ;"I"@return [IO];T;#0;$@7X;.F;Bi ;C0;7[ ;$@7X;![ ;"I"Puts ios into binary mode.
Once a stream is in binary mode, it cannot be reset to nonbinary mode.
- newline conversion disabled
- encoding conversion disabled
- content is treated as ASCII-8BIT
@overload binmode
@return [IO];T;#0;$@7X;.F;/o;0;1T;2i;3i;%@kL;9I"static VALUE
rb_io_binmode_m(VALUE io)
{
VALUE write_io;
rb_io_ascii8bit_binmode(io);
write_io = GetWriteIO(io);
if (write_io != io)
rb_io_ascii8bit_binmode(write_io);
return io;
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#binmode?;F;7[ ;[[@Ti;T;:
binmode?;0; [ ; { ; IC; ":Returns true if ios is binmode.;T; [o;=
;>I"
overload;F;?0;;;@0;:I"
binmode?;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Boolean;T;$@RX;![ ;"I"@return [Boolean];T;#0;$@RX;.F;Bi ;C0;7[ ;$@RX;![ ;"I"cReturns true if ios is binmode.
@overload binmode?
@return [Boolean];T;#0;$@RX;.F;/o;0;1T;2i;3i;Bi ;%@kL;9I"static VALUE
rb_io_binmode_p(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
return RBOOL(fptr->mode & FMODE_BINMODE);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#sysseek;F;7[[@90;[[@Ti[;T;: sysseek;0; [ ; { ; IC; " Seeks to a given offset in the stream according to the value
of whence (see IO#seek for values of whence). Returns
the new offset into the file.
f = File.new("testfile")
f.sysseek(-13, IO::SEEK_END) #=> 53
f.sysread(10) #=> "And so on."
;T; [o;=
;>I"
overload;F;?0;;;@0;:I")sysseek(offset, whence=IO::SEEK_SET);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@mX;![ ;"I"@return [Integer];T;#0;$@mX;.F;Bi ;C0;7[[I" offset;T0[I" whence;TI"IO::SEEK_SET;T;$@mX;![ ;"I"cSeeks to a given offset in the stream according to the value
of whence (see IO#seek for values of whence). Returns
the new offset into the file.
f = File.new("testfile")
f.sysseek(-13, IO::SEEK_END) #=> 53
f.sysread(10) #=> "And so on."
@overload sysseek(offset, whence=IO::SEEK_SET)
@return [Integer];T;#0;$@mX;.F;/o;0;1T;2iN;3iX;%@kL;9I"static VALUE
rb_io_sysseek(int argc, VALUE *argv, VALUE io)
{
VALUE offset, ptrname;
int whence = SEEK_SET;
rb_io_t *fptr;
off_t pos;
if (rb_scan_args(argc, argv, "11", &offset, &ptrname) == 2) {
whence = interpret_seek_whence(ptrname);
}
pos = NUM2OFFT(offset);
GetOpenFile(io, fptr);
if ((fptr->mode & FMODE_READABLE) &&
(READ_DATA_BUFFERED(fptr) || READ_CHAR_PENDING(fptr))) {
rb_raise(rb_eIOError, "sysseek for buffered IO");
}
if ((fptr->mode & FMODE_WRITABLE) && fptr->wbuf.len) {
rb_warn("sysseek for buffered IO");
}
errno = 0;
pos = lseek(fptr->fd, pos, whence);
if (pos < 0 && errno) rb_sys_fail_path(fptr->pathv);
return OFFT2NUM(pos);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#advise;F;7[[@90;[[@Ti&;T;: advise;0; [ ; { ; IC; ";Announce an intention to access data from the current file in a
specific pattern. On platforms that do not support the
posix_fadvise(2) system call, this method is a no-op.
_advice_ is one of the following symbols:
:normal:: No advice to give; the default assumption for an open file.
:sequential:: The data will be accessed sequentially
with lower offsets read before higher ones.
:random:: The data will be accessed in random order.
:willneed:: The data will be accessed in the near future.
:dontneed:: The data will not be accessed in the near future.
:noreuse:: The data will only be accessed once.
The semantics of a piece of advice are platform-dependent. See
man 2 posix_fadvise for details.
"data" means the region of the current file that begins at
_offset_ and extends for _len_ bytes. If _len_ is 0, the region
ends at the last byte of the file. By default, both _offset_ and
_len_ are 0, meaning that the advice applies to the entire file.
If an error occurs, one of the following exceptions will be raised:
IOError:: The IO stream is closed.
Errno::EBADF::
The file descriptor of the current file is invalid.
Errno::EINVAL:: An invalid value for _advice_ was given.
Errno::ESPIPE::
The file descriptor of the current file refers to a FIFO or
pipe. (Linux raises Errno::EINVAL in this case).
TypeError::
Either _advice_ was not a Symbol, or one of the
other arguments was not an Integer.
RangeError:: One of the arguments given was too big/small.
This list is not exhaustive; other Errno:: exceptions are also possible.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"$advise(advice, offset=0, len=0);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I"nil;T;$@X;![ ;"I"@return [nil];T;#0;$@X;.F;Bi ;C0;7[[I" advice;T0[I" offset;TI"0;T[I"len;TI"0;T;$@X;![ ;"I"wAnnounce an intention to access data from the current file in a
specific pattern. On platforms that do not support the
posix_fadvise(2) system call, this method is a no-op.
_advice_ is one of the following symbols:
:normal:: No advice to give; the default assumption for an open file.
:sequential:: The data will be accessed sequentially
with lower offsets read before higher ones.
:random:: The data will be accessed in random order.
:willneed:: The data will be accessed in the near future.
:dontneed:: The data will not be accessed in the near future.
:noreuse:: The data will only be accessed once.
The semantics of a piece of advice are platform-dependent. See
man 2 posix_fadvise for details.
"data" means the region of the current file that begins at
_offset_ and extends for _len_ bytes. If _len_ is 0, the region
ends at the last byte of the file. By default, both _offset_ and
_len_ are 0, meaning that the advice applies to the entire file.
If an error occurs, one of the following exceptions will be raised:
IOError:: The IO stream is closed.
Errno::EBADF::
The file descriptor of the current file is invalid.
Errno::EINVAL:: An invalid value for _advice_ was given.
Errno::ESPIPE::
The file descriptor of the current file refers to a FIFO or
pipe. (Linux raises Errno::EINVAL in this case).
TypeError::
Either _advice_ was not a Symbol, or one of the
other arguments was not an Integer.
RangeError:: One of the arguments given was too big/small.
This list is not exhaustive; other Errno:: exceptions are also possible.
@overload advise(advice, offset=0, len=0)
@return [nil];T;#0;$@X;.F;/o;0;1T;2i&;3i&;%@kL;9I"static VALUE
rb_io_advise(int argc, VALUE *argv, VALUE io)
{
VALUE advice, offset, len;
off_t off, l;
rb_io_t *fptr;
rb_scan_args(argc, argv, "12", &advice, &offset, &len);
advice_arg_check(advice);
io = GetWriteIO(io);
GetOpenFile(io, fptr);
off = NIL_P(offset) ? 0 : NUM2OFFT(offset);
l = NIL_P(len) ? 0 : NUM2OFFT(len);
#ifdef HAVE_POSIX_FADVISE
return do_io_advise(fptr, advice, off, l);
#else
((void)off, (void)l); /* Ignore all hint */
return Qnil;
#endif
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#ioctl;F;7[[@90;[[@Ti(;T;:
ioctl;0; [ ; { ; IC; "[Provides a mechanism for issuing low-level commands to control or
query I/O devices. Arguments and results are platform dependent. If
arg is a number, its value is passed directly. If it is a
string, it is interpreted as a binary sequence of bytes. On Unix
platforms, see ioctl(2) for details. Not implemented on
all platforms.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" ioctl(integer_cmd, arg);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@X;![ ;"I"@return [Integer];T;#0;$@X;.F;Bi ;C0;7[[I"integer_cmd;T0[I"arg;T0;$@X;![ ;"I"Provides a mechanism for issuing low-level commands to control or
query I/O devices. Arguments and results are platform dependent. If
arg is a number, its value is passed directly. If it is a
string, it is interpreted as a binary sequence of bytes. On Unix
platforms, see ioctl(2) for details. Not implemented on
all platforms.
@overload ioctl(integer_cmd, arg)
@return [Integer];T;#0;$@X;.F;/o;0;1T;2i(;3i(;%@kL;9I"static VALUE
rb_io_ioctl(int argc, VALUE *argv, VALUE io)
{
VALUE req, arg;
rb_scan_args(argc, argv, "11", &req, &arg);
return rb_ioctl(io, req, arg);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"
IO#fcntl;F;7[[@90;[[@Ti(;T;:
fcntl;0; [ ; { ; IC; "Provides a mechanism for issuing low-level commands to control or
query file-oriented I/O streams. Arguments and results are platform
dependent. If arg is a number, its value is passed
directly. If it is a string, it is interpreted as a binary sequence
of bytes (Array#pack might be a useful way to build this string). On
Unix platforms, see fcntl(2) for details. Not
implemented on all platforms.
;T; [o;=
;>I"
overload;F;?0;;;@0;:I" fcntl(integer_cmd, arg);T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;T;$@X;![ ;"I"@return [Integer];T;#0;$@X;.F;Bi ;C0;7[[I"integer_cmd;T0[I"arg;T0;$@X;![ ;"I"Provides a mechanism for issuing low-level commands to control or
query file-oriented I/O streams. Arguments and results are platform
dependent. If arg is a number, its value is passed
directly. If it is a string, it is interpreted as a binary sequence
of bytes (Array#pack might be a useful way to build this string). On
Unix platforms, see fcntl(2) for details. Not
implemented on all platforms.
@overload fcntl(integer_cmd, arg)
@return [Integer];T;#0;$@X;.F;/o;0;1T;2i(;3i(;%@kL;9I"static VALUE
rb_io_fcntl(int argc, VALUE *argv, VALUE io)
{
VALUE req, arg;
rb_scan_args(argc, argv, "11", &req, &arg);
return rb_fcntl(io, req, arg);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I" IO#pid;F;7[ ;[[@Ti
;T;:pid;0; [ ; { ; IC; "rReturns the process ID of a child process associated with the stream,
which will have been set by IO#popen, or +nil+ if the stream was not
created by IO#popen:
pipe = IO.popen("-")
if pipe
$stderr.puts "In parent, child pid is #{pipe.pid}"
else
$stderr.puts "In child, pid is #{$$}"
end
Output:
In child, pid is 26209
In parent, child pid is 26209
;T; [o;=
;>I"
overload;F;?0;;;@0;:I"pid;T; IC; " ;T; [o;A
;>I" return;F;?I" ;T;0;@[I" Integer;TI"nil;T;$@X;![ ;"I"@return [Integer, nil];T;#0;$@X;.F;Bi ;C0;7[ ;$@X;![ ;"I"Returns the process ID of a child process associated with the stream,
which will have been set by IO#popen, or +nil+ if the stream was not
created by IO#popen:
pipe = IO.popen("-")
if pipe
$stderr.puts "In parent, child pid is #{pipe.pid}"
else
$stderr.puts "In child, pid is #{$$}"
end
Output:
In child, pid is 26209
In parent, child pid is 26209
@overload pid
@return [Integer, nil];T;#0;$@X;.F;/o;0;1T;2ij
;3i}
;%@kL;9I"static VALUE
rb_io_pid(VALUE io)
{
rb_io_t *fptr;
GetOpenFile(io, fptr);
if (!fptr->pid)
return Qnil;
return PIDT2NUM(fptr->pid);
};T;:I"static VALUE;T;;To;4;5F;6;;; ;&I"IO#inspect;F;7[ ;[[@Ti
;T;;J;0; [ ; { ; IC; "jReturns a string representation of +self+:
f = File.open('t.txt')
f.inspect # => "#