Module: Kernel

Included in:
Object
Defined in:
object.c

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(symbol[, *args]) ⇒ Object

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. 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 romanToInt(str)
    # ...
  end
  def method_missing(methId)
    str = methId.id2name
    romanToInt(str)
  end
end

r = Roman.new
r.iv      #=> 4
r.xxiii   #=> 23
r.mm      #=> 2000



5549
5550
5551
 
# File 'eval.c', line 5549

static VALUE
rb_method_missing(argc, argv, obj)
int argc;

Instance Method Details

#abort ⇒ Object #Kernel::abort ⇒ Object #Process::abort ⇒ Object

Terminate execution immediately, effectively by calling Kernel.exit(1). If msg is given, it is written to STDERR prior to terminating.



4486
4487
4488
 
# File 'eval.c', line 4486

VALUE
rb_f_abort(argc, argv)
int argc;

#Array(arg) ⇒ Array

Returns arg as an Array. First tries to call arg.to_ary, then arg.to_a. If both fail, creates a single element array containing arg (unless arg is nil).

Array(1..5)   #=> [1, 2, 3, 4, 5]

Returns:



2530
2531
2532
 
# File 'object.c', line 2530

static VALUE
rb_f_array(obj, arg)
VALUE obj, arg;

#at_exit { ... } ⇒ Proc

Converts block to a Proc object (and therefore binds it at the point of call) and registers it for execution when the program exits. If multiple handlers are registered, they are executed in reverse order of registration.

def do_at_exit(str1)
  at_exit { print str1 }
end
at_exit { puts "cruel world" }
do_at_exit("goodbye ")
exit

produces:

goodbye cruel world

Yields:

Returns:



7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
 
# File 'eval.c', line 7881

static VALUE
rb_f_at_exit()
{
    VALUE proc;

    if (!rb_block_given_p()) {
	rb_raise(rb_eArgError, "called without a block");
    }
    proc = rb_block_proc();
    rb_set_end_proc(call_end_proc, proc);
    return proc;
}

#autoload ⇒ nil

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")

Returns:

  • (nil) 


8099
8100
8101
 
# File 'eval.c', line 8099

static VALUE
rb_f_autoload(obj, sym, file)
VALUE obj;

#autoload ⇒ nil

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")

Returns:

  • (nil) 


8122
8123
8124
 
# File 'eval.c', line 8122

static VALUE
rb_f_autoload_p(obj, sym)
VALUE obj;

#binding ⇒ Binding

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. Also see the description of class Binding.

def getBinding(param)
  return binding
end
b = getBinding("hello")
eval("param", b)   #=> "hello"

Returns:



8333
8334
8335
 
# File 'eval.c', line 8333

static VALUE
rb_f_binding(self)
VALUE self;

#block_given? ⇒ Boolean #iterator? ⇒ Boolean

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"

Overloads:

  • #block_given? ⇒ Boolean

    Returns:

    • (Boolean)
  • #iterator? ⇒ Boolean

    Returns:

    • (Boolean) 


4739
4740
4741
4742
4743
4744
4745
 
# File 'eval.c', line 4739

static VALUE
rb_f_block_given_p()
{
    if (ruby_frame->prev && ruby_frame->prev->iter == ITER_CUR && ruby_block)
	return Qtrue;
    return Qfalse;
}

#callcc {|cont| ... } ⇒ Object

Generates a Continuation object, which it passes to the associated block. 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.

Yields:

  • (cont)

Returns:



12664
12665
12666
 
# File 'eval.c', line 12664

static VALUE
rb_callcc(self)
VALUE self;

#caller(start = 1) ⇒ Array

Returns the current execution stack—an array containing strings in the form “file:line” or “file:line: in ‘method’”. The optional start parameter determines the number of initial stack entries to omit from the result.

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"]
c(1)   #=> ["prog:5:in `b'", "prog:8:in `c'", "prog:11"]
c(2)   #=> ["prog:8:in `c'", "prog:12"]
c(3)   #=> ["prog:13"]

Returns:



6317
6318
6319
 
# File 'eval.c', line 6317

static VALUE
rb_f_caller(argc, argv)
int argc;

#catch ⇒ Object

#chomp ⇒ Object #chomp(string) ⇒ Object

Equivalent to $_ = $_.chomp(string). See String#chomp.

$_ = "now\n"
chomp         #=> "now"
$_            #=> "now"
chomp "ow"    #=> "n"
$_            #=> "n"
chomp "xxx"   #=> "n"
$_            #=> "n"



4016
4017
4018
 
# File 'string.c', line 4016

static VALUE
rb_f_chomp(argc, argv)
int argc;

#chomp! ⇒ nil #chomp!(string) ⇒ nil

Equivalent to $_.chomp!(string). See String#chomp!

$_ = "now\n"
chomp!       #=> "now"
$_           #=> "now"
chomp! "x"   #=> nil
$_           #=> "now"

Overloads:

  • #chomp! ⇒ nil

    Returns:

    • (nil)
  • #chomp!(string) ⇒ nil

    Returns:

    • (nil) 


3991
3992
3993
 
# File 'string.c', line 3991

static VALUE
rb_f_chomp_bang(argc, argv)
int argc;

#chop ⇒ String

Equivalent to ($_.dup).chop!, except nil is never returned. See String#chop!.

a  =  "now\r\n"
$_ = a
chop   #=> "now"
$_     #=> "now"
chop   #=> "no"
chop   #=> "n"
chop   #=> ""
chop   #=> ""
a      #=> "now\r\n"

Returns:



3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
 
# File 'string.c', line 3851

static VALUE
rb_f_chop()
{
    VALUE str = uscore_get();

    if (RSTRING(str)->len > 0) {
	str = rb_str_dup(str);
	rb_str_chop_bang(str);
	rb_lastline_set(str);
    }
    return str;
}

#chop! ⇒ nil

Equivalent to $_.chop!.

a  = "now\r\n"
$_ = a
chop!   #=> "now"
chop!   #=> "no"
chop!   #=> "n"
chop!   #=> ""
chop!   #=> nil
$_      #=> ""
a       #=> ""

Returns:

  • (nil) 


3826
3827
3828
 
# File 'string.c', line 3826

static VALUE
rb_f_chop_bang(str)
VALUE str;

#eval(string[, binding [, filename [,lineno]]]) ⇒ Object

Evaluates the Ruby expression(s) in string. If binding is given, the evaluation is performed in its context. The binding may be a Binding object or a Proc object. If the optional filename and lineno parameters are present, they will be used when reporting syntax errors.

def getBinding(str)
  return binding
end
str = "hello"
eval "str + ' Fred'"                      #=> "hello Fred"
eval "str + ' Fred'", getBinding("bye")   #=> "bye Fred"

Returns:



6534
6535
6536
 
# File 'eval.c', line 6534

static VALUE
rb_f_eval(argc, argv, self)
int argc;

#exit(integer = 0) ⇒ Object #Kernel::exit(integer = 0) ⇒ Object #Process::exit(integer = 0) ⇒ Object

Initiates the termination of the Ruby script by raising the SystemExit exception. This exception may be caught. The optional parameter is used to return a status code to the invoking environment.

begin
  exit
  puts "never get here"
rescue SystemExit
  puts "rescued a SystemExit exception"
end
puts "after begin block"

produces:

rescued a SystemExit exception
after begin block

Just prior to termination, Ruby executes any at_exit functions (see Kernel::at_exit) and runs any object finalizers (see ObjectSpace::define_finalizer).

at_exit { puts "at_exit function" }
ObjectSpace.define_finalizer("string",  proc { puts "in finalizer" })
exit

produces:

at_exit function
in finalizer



4442
4443
4444
 
# File 'eval.c', line 4442

VALUE
rb_f_exit(argc, argv)
int argc;

#raise ⇒ Object #raise(string) ⇒ Object #raise(exception[, string [, array]]) ⇒ Object #fail ⇒ Object #fail(string) ⇒ Object #fail(exception[, string [, array]]) ⇒ Object

With no arguments, raises the exception in $! or raises a RuntimeError if $! is nil. With a single String argument, raises a RuntimeError with the string as a message. Otherwise, the first parameter should be the name of an Exception class (or an object that returns an Exception object when sent an exception message). The optional second parameter sets the message associated with the exception, and the third parameter is an array of callback information. Exceptions are caught by the rescue clause of begin...end blocks.

raise "Failed to create socket"
raise ArgumentError, "No parameters", caller



4627
4628
4629
 
# File 'eval.c', line 4627

static VALUE
rb_f_raise(argc, argv)
int argc;

#Float(arg) ⇒ Float

Returns arg converted to a float. Numeric types are converted directly, the rest are converted using arg.to_f. As of Ruby 1.8, converting nil generates a TypeError.

Float(1)           #=> 1.0
Float("123.456")   #=> 123.456

Returns:



2431
2432
2433
 
# File 'object.c', line 2431

static VALUE
rb_f_float(obj, arg)
VALUE obj, arg;

#format(format_string[, arguments...]) ⇒ String #sprintf(format_string[, arguments...]) ⇒ String

Returns the string resulting from applying format_string to any additional arguments. Within the format string, any characters other than format sequences are copied to the result. A format sequence consists of a percent sign, followed by optional flags, width, and precision indicators, then terminated with a field type character. The field type controls how the corresponding sprintf argument is to be interpreted, while the flags modify that interpretation. The field type characters are listed in the table at the end of this section. The flag characters are:

Flag     | Applies to   | Meaning
---------+--------------+-----------------------------------------
space    | bdeEfgGiouxX | Leave a space at the start of
         |              | positive numbers.
---------+--------------+-----------------------------------------
(digit)$ | all          | Specifies the absolute argument number
         |              | for this field. Absolute and relative
         |              | argument numbers cannot be mixed in a
         |              | sprintf string.
---------+--------------+-----------------------------------------
 #       | beEfgGoxX    | Use an alternative format. For the
         |              | conversions `o', `x', `X', and `b',
         |              | prefix the result with ``0'', ``0x'', ``0X'',
         |              |  and ``0b'', respectively. For `e',
         |              | `E', `f', `g', and 'G', force a decimal
         |              | point to be added, even if no digits follow.
         |              | For `g' and 'G', do not remove trailing zeros.
---------+--------------+-----------------------------------------
+        | bdeEfgGiouxX | Add a leading plus sign to positive numbers.
---------+--------------+-----------------------------------------
-        | all          | Left-justify the result of this conversion.
---------+--------------+-----------------------------------------
0 (zero) | bdeEfgGiouxX | Pad with zeros, not spaces.
---------+--------------+-----------------------------------------
*        | all          | Use the next argument as the field width.
         |              | If negative, left-justify the result. If the
         |              | asterisk is followed by a number and a dollar
         |              | sign, use the indicated argument as the width.

The field width is an optional integer, followed optionally by a period and a precision. The width specifies the minimum number of characters that will be written to the result for this field. For numeric fields, the precision controls the number of decimal places displayed. For string fields, the precision determines the maximum number of characters to be copied from the string. (Thus, the format sequence %10.10s will always contribute exactly ten characters to the result.)

The field types are:

Field |  Conversion
------+--------------------------------------------------------------
  b   | Convert argument as a binary number.
  c   | Argument is the numeric code for a single character.
  d   | Convert argument as a decimal number.
  E   | Equivalent to `e', but uses an uppercase E to indicate
      | the exponent.
  e   | Convert floating point argument into exponential notation
      | with one digit before the decimal point. The precision
      | determines the number of fractional digits (defaulting to six).
  f   | Convert floating point argument as [-]ddd.ddd,
      |  where the precision determines the number of digits after
      | the decimal point.
  G   | Equivalent to `g', but use an uppercase `E' in exponent form.
  g   | Convert a floating point number using exponential form
      | if the exponent is less than -4 or greater than or
      | equal to the precision, or in d.dddd form otherwise.
  i   | Identical to `d'.
  o   | Convert argument as an octal number.
  p   | The valuing of argument.inspect.
  s   | Argument is a string to be substituted. If the format
      | sequence contains a precision, at most that many characters
      | will be copied.
  u   | Treat argument as an unsigned decimal number. Negative integers
      | are displayed as a 32 bit two's complement plus one for the
      | underlying architecture; that is, 2 ** 32 + n.  However, since
      | Ruby has no inherent limit on bits used to represent the
      | integer, this value is preceded by two dots (..) in order to
      | indicate a infinite number of leading sign bits.
  X   | Convert argument as a hexadecimal number using uppercase
      | letters. Negative numbers will be displayed with two
      | leading periods (representing an infinite string of
      | leading 'FF's.
  x   | Convert argument as a hexadecimal number.
      | Negative numbers will be displayed with two
      | leading periods (representing an infinite string of
      | leading 'ff's.

Examples:

sprintf("%d %04x", 123, 123)               #=> "123 007b"
sprintf("%08b '%4s'", 123, 123)            #=> "01111011 ' 123'"
sprintf("%1$*2$s %2$d %1$s", "hello", 8)   #=> "   hello 8 hello"
sprintf("%1$*2$s %2$d", "hello", -8)       #=> "hello    -8"
sprintf("%+g:% g:%-g", 1.23, 1.23, 1.23)   #=> "+1.23: 1.23:1.23"
sprintf("%u", -123)                        #=> "..4294967173"

Overloads:

  • #format(format_string[, arguments...]) ⇒ String

    Returns:

  • #sprintf(format_string[, arguments...]) ⇒ String

    Returns:



241
242
243
 
# File 'sprintf.c', line 241

VALUE
rb_f_sprintf(argc, argv)
int argc;

#global_variables ⇒ Array

Returns an array of the names of global variables.

global_variables.grep /std/   #=> ["$stderr", "$stdout", "$stdin"]

Returns:



777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
 
# File 'variable.c', line 777

VALUE
rb_f_global_variables()
{
    VALUE ary = rb_ary_new();
    char buf[4];
    char *s = "&`'+123456789";

    st_foreach(rb_global_tbl, gvar_i, ary);
    if (!NIL_P(rb_backref_get())) {
	while (*s) {
	    sprintf(buf, "$%c", *s++);
	    rb_ary_push(ary, rb_str_new2(buf));
	}
    }
    return ary;
}

#gsub(pattern, replacement) ⇒ String #gsub(pattern) {|...| ... } ⇒ String

Equivalent to $_.gsub..., except that $_ receives the modified result.

$_ = "quick brown fox"
gsub /[aeiou]/, '*'   #=> "q**ck br*wn f*x"
$_                    #=> "q**ck br*wn f*x"

Overloads:

  • #gsub(pattern, replacement) ⇒ String

    Returns:

  • #gsub(pattern) {|...| ... } ⇒ String

    Yields:

    • (...)

    Returns:



2362
2363
2364
 
# File 'string.c', line 2362

static VALUE
rb_f_gsub(argc, argv)
int argc;

#gsub!(pattern, replacement) ⇒ String? #gsub!(pattern) {|...| ... } ⇒ String?

Equivalent to Kernel::gsub, except nil is returned if $_ is not modified.

$_ = "quick brown fox"
gsub! /cat/, '*'   #=> nil
$_                 #=> "quick brown fox"

Overloads:

  • #gsub!(pattern, replacement) ⇒ String?

    Returns:

  • #gsub!(pattern) {|...| ... } ⇒ String?

    Yields:

    • (...)

    Returns:



2341
2342
2343
 
# File 'string.c', line 2341

static VALUE
rb_f_gsub_bang(argc, argv)
int argc;

#Integer(arg) ⇒ Integer

Converts arg to a Fixnum or Bignum. Numeric types are converted directly (with floating point numbers being truncated). If arg is a String, leading radix indicators (0, 0b, and 0x) are honored. Others are converted using to_int and to_i. This behavior is different from that of String#to_i.

Integer(123.999)    #=> 123
Integer("0x1a")     #=> 26
Integer(Time.new)   #=> 1049896590

Returns:



2279
2280
2281
 
# File 'object.c', line 2279

static VALUE
rb_f_integer(obj, arg)
VALUE obj, arg;

#block_given? ⇒ Boolean #iterator? ⇒ Boolean

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"

Overloads:

  • #block_given? ⇒ Boolean

    Returns:

    • (Boolean)
  • #iterator? ⇒ Boolean

    Returns:

    • (Boolean) 


4739
4740
4741
4742
4743
4744
4745
 
# File 'eval.c', line 4739

static VALUE
rb_f_block_given_p()
{
    if (ruby_frame->prev && ruby_frame->prev->iter == ITER_CUR && ruby_block)
	return Qtrue;
    return Qfalse;
}

#proc {|...| ... } ⇒ Proc #lambda {|...| ... } ⇒ Proc

Equivalent to Proc.new, except the resulting Proc objects check the number of parameters passed when called.

Overloads:

  • #proc {|...| ... } ⇒ Proc

    Yields:

    • (...)

    Returns:

  • #lambda {|...| ... } ⇒ Proc

    Yields:

    • (...)

    Returns:



8506
8507
8508
8509
8510
 
# File 'eval.c', line 8506

static VALUE
proc_lambda()
{
    return proc_alloc(rb_cProc, Qtrue);
}

#load(filename, wrap = false) ⇒ true

Loads and executes the Ruby program in the file filename. If the filename does not resolve to an absolute path, the file is searched for in the library directories listed in $:. If the optional wrap parameter is true, the loaded script will be executed under an anonymous module, protecting the calling program’s global namespace. In no circumstance will any local variables in the loaded file be propagated to the loading environment.

Returns:

  • (true) 


6917
6918
6919
 
# File 'eval.c', line 6917

static VALUE
rb_f_load(argc, argv)
int argc;

#local_variables ⇒ Array

Returns the names of the current local variables.

fred = 1
for i in 1..10
   # ...
end
local_variables   #=> ["fred", "i"]

Returns:



7754
7755
7756
7757
7758
7759
7760
7761
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
 
# File 'eval.c', line 7754

static VALUE
rb_f_local_variables()
{
    ID *tbl;
    int n, i;
    VALUE ary = rb_ary_new();
    struct RVarmap *vars;

    tbl = ruby_scope->local_tbl;
    if (tbl) {
	n = *tbl++;
	for (i=2; i<n; i++) {	/* skip first 2 ($_ and $~) */
	    if (!rb_is_local_id(tbl[i])) continue; /* skip flip states */
	    rb_ary_push(ary, rb_str_new2(rb_id2name(tbl[i])));
	}
    }

    vars = ruby_dyna_vars;
    while (vars) {
	if (vars->id && rb_is_local_id(vars->id)) { /* skip $_, $~ and flip states */
	    rb_ary_push(ary, rb_str_new2(rb_id2name(vars->id)));
	}
	vars = vars->next;
    }

    return ary;
}

#loop { ... } ⇒ Object

Repeatedly executes the block.

loop do
  print "Input: "
  line = gets
  break if !line or line =~ /^qQ/
  # ...
end

Yields:



5131
5132
5133
5134
5135
5136
5137
5138
5139
 
# File 'eval.c', line 5131

static VALUE
rb_f_loop()
{
    for (;;) {
	rb_yield_0(Qundef, 0, 0, 0, Qfalse);
	CHECK_INTS;
    }
    return Qnil;		/* dummy */
}

#proc {|...| ... } ⇒ Proc #lambda {|...| ... } ⇒ Proc

Equivalent to Proc.new, except the resulting Proc objects check the number of parameters passed when called.

Overloads:

  • #proc {|...| ... } ⇒ Proc

    Yields:

    • (...)

    Returns:

  • #lambda {|...| ... } ⇒ Proc

    Yields:

    • (...)

    Returns:



8506
8507
8508
8509
8510
 
# File 'eval.c', line 8506

static VALUE
proc_lambda()
{
    return proc_alloc(rb_cProc, Qtrue);
}

#raise ⇒ Object #raise(string) ⇒ Object #raise(exception[, string [, array]]) ⇒ Object #fail ⇒ Object #fail(string) ⇒ Object #fail(exception[, string [, array]]) ⇒ Object

With no arguments, raises the exception in $! or raises a RuntimeError if $! is nil. With a single String argument, raises a RuntimeError with the string as a message. Otherwise, the first parameter should be the name of an Exception class (or an object that returns an Exception object when sent an exception message). The optional second parameter sets the message associated with the exception, and the third parameter is an array of callback information. Exceptions are caught by the rescue clause of begin...end blocks.

raise "Failed to create socket"
raise ArgumentError, "No parameters", caller



4627
4628
4629
 
# File 'eval.c', line 4627

static VALUE
rb_f_raise(argc, argv)
int argc;

#rand(max = 0) ⇒ Numeric

Converts max to an integer using max1 = max.to_i.abs. If the result is zero, returns a pseudorandom floating point number greater than or equal to 0.0 and less than 1.0. Otherwise, returns a pseudorandom integer greater than or equal to zero and less than max1. Kernel::srand may be used to ensure repeatable sequences of random numbers between different runs of the program. Ruby currently uses a modified Mersenne Twister with a period of 2**19937-1.

srand 1234                 #=> 0
[ rand,  rand ]            #=> [0.191519450163469, 0.49766366626136]
[ rand(10), rand(1000) ]   #=> [6, 817]
srand 1234                 #=> 1234
[ rand,  rand ]            #=> [0.191519450163469, 0.49766366626136]

Returns:



438
439
440
 
# File 'random.c', line 438

static VALUE
rb_f_rand(argc, argv, obj)
int argc;

#require(string) ⇒ Boolean

Ruby tries to load the library named string, returning true if successful. If the filename does not resolve to an absolute path, it will be searched for in the directories listed in $:. If the file has the extension “.rb”, it is loaded as a source file; if the extension is “.so”, “.o”, or “.dll”, or whatever the default shared library extension is 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. The name of the loaded feature is added to the array in $". A feature will not be loaded if it’s name already appears in $". However, the file name is not converted to an absolute path, so that “require 'a';require './a'” will load a.rb twice.

require "my-library.rb"
require "db-driver"

Returns:

  • (Boolean) 


7102
7103
7104
 
# File 'eval.c', line 7102

VALUE
rb_f_require(obj, fname)
VALUE obj, fname;

#scan(pattern) ⇒ Array #scan(pattern) {|///| ... } ⇒ Object

Equivalent to calling $_.scan. See String#scan.

Overloads:

  • #scan(pattern) ⇒ Array

    Returns:

  • #scan(pattern) {|///| ... } ⇒ Object

    Yields:

    • (///) 


4295
4296
4297
 
# File 'string.c', line 4295

static VALUE
rb_f_scan(self, pat)
VALUE self, pat;

#set_trace_func(proc) ⇒ Proc #set_trace_func(nil) ⇒ nil

Establishes proc as the handler for tracing, or disables tracing if the parameter is nil. proc takes up to six parameters: an event name, a filename, a line number, an object id, a binding, and 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), and 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

Overloads:

  • #set_trace_func(proc) ⇒ Proc

    Returns:

  • #set_trace_func(nil) ⇒ nil

    Returns:

    • (nil) 


2609
2610
2611
 
# File 'eval.c', line 2609

static VALUE
set_trace_func(obj, trace)
VALUE obj, trace;

#split([pattern [, limit]]) ⇒ Array

Equivalent to $_.split(pattern, limit). See String#split.

Returns:



3629
3630
3631
 
# File 'string.c', line 3629

static VALUE
rb_f_split(argc, argv)
int argc;

#format(format_string[, arguments...]) ⇒ String #sprintf(format_string[, arguments...]) ⇒ String

Returns the string resulting from applying format_string to any additional arguments. Within the format string, any characters other than format sequences are copied to the result. A format sequence consists of a percent sign, followed by optional flags, width, and precision indicators, then terminated with a field type character. The field type controls how the corresponding sprintf argument is to be interpreted, while the flags modify that interpretation. The field type characters are listed in the table at the end of this section. The flag characters are:

Flag     | Applies to   | Meaning
---------+--------------+-----------------------------------------
space    | bdeEfgGiouxX | Leave a space at the start of
         |              | positive numbers.
---------+--------------+-----------------------------------------
(digit)$ | all          | Specifies the absolute argument number
         |              | for this field. Absolute and relative
         |              | argument numbers cannot be mixed in a
         |              | sprintf string.
---------+--------------+-----------------------------------------
 #       | beEfgGoxX    | Use an alternative format. For the
         |              | conversions `o', `x', `X', and `b',
         |              | prefix the result with ``0'', ``0x'', ``0X'',
         |              |  and ``0b'', respectively. For `e',
         |              | `E', `f', `g', and 'G', force a decimal
         |              | point to be added, even if no digits follow.
         |              | For `g' and 'G', do not remove trailing zeros.
---------+--------------+-----------------------------------------
+        | bdeEfgGiouxX | Add a leading plus sign to positive numbers.
---------+--------------+-----------------------------------------
-        | all          | Left-justify the result of this conversion.
---------+--------------+-----------------------------------------
0 (zero) | bdeEfgGiouxX | Pad with zeros, not spaces.
---------+--------------+-----------------------------------------
*        | all          | Use the next argument as the field width.
         |              | If negative, left-justify the result. If the
         |              | asterisk is followed by a number and a dollar
         |              | sign, use the indicated argument as the width.

The field width is an optional integer, followed optionally by a period and a precision. The width specifies the minimum number of characters that will be written to the result for this field. For numeric fields, the precision controls the number of decimal places displayed. For string fields, the precision determines the maximum number of characters to be copied from the string. (Thus, the format sequence %10.10s will always contribute exactly ten characters to the result.)

The field types are:

Field |  Conversion
------+--------------------------------------------------------------
  b   | Convert argument as a binary number.
  c   | Argument is the numeric code for a single character.
  d   | Convert argument as a decimal number.
  E   | Equivalent to `e', but uses an uppercase E to indicate
      | the exponent.
  e   | Convert floating point argument into exponential notation
      | with one digit before the decimal point. The precision
      | determines the number of fractional digits (defaulting to six).
  f   | Convert floating point argument as [-]ddd.ddd,
      |  where the precision determines the number of digits after
      | the decimal point.
  G   | Equivalent to `g', but use an uppercase `E' in exponent form.
  g   | Convert a floating point number using exponential form
      | if the exponent is less than -4 or greater than or
      | equal to the precision, or in d.dddd form otherwise.
  i   | Identical to `d'.
  o   | Convert argument as an octal number.
  p   | The valuing of argument.inspect.
  s   | Argument is a string to be substituted. If the format
      | sequence contains a precision, at most that many characters
      | will be copied.
  u   | Treat argument as an unsigned decimal number. Negative integers
      | are displayed as a 32 bit two's complement plus one for the
      | underlying architecture; that is, 2 ** 32 + n.  However, since
      | Ruby has no inherent limit on bits used to represent the
      | integer, this value is preceded by two dots (..) in order to
      | indicate a infinite number of leading sign bits.
  X   | Convert argument as a hexadecimal number using uppercase
      | letters. Negative numbers will be displayed with two
      | leading periods (representing an infinite string of
      | leading 'FF's.
  x   | Convert argument as a hexadecimal number.
      | Negative numbers will be displayed with two
      | leading periods (representing an infinite string of
      | leading 'ff's.

Examples:

sprintf("%d %04x", 123, 123)               #=> "123 007b"
sprintf("%08b '%4s'", 123, 123)            #=> "01111011 ' 123'"
sprintf("%1$*2$s %2$d %1$s", "hello", 8)   #=> "   hello 8 hello"
sprintf("%1$*2$s %2$d", "hello", -8)       #=> "hello    -8"
sprintf("%+g:% g:%-g", 1.23, 1.23, 1.23)   #=> "+1.23: 1.23:1.23"
sprintf("%u", -123)                        #=> "..4294967173"

Overloads:

  • #format(format_string[, arguments...]) ⇒ String

    Returns:

  • #sprintf(format_string[, arguments...]) ⇒ String

    Returns:



241
242
243
 
# File 'sprintf.c', line 241

VALUE
rb_f_sprintf(argc, argv)
int argc;

#srand(number = 0) ⇒ Object

Seeds the pseudorandom number generator to the value of number.to_i.abs. If number is omitted or zero, seeds the generator using a combination of the time, the process id, and a sequence number. (This is also the behavior if Kernel::rand is called without previously calling srand, but without the sequence.) By setting the seed to a known value, scripts can be made deterministic during testing. The previous seed value is returned. Also see Kernel::rand.



322
323
324
 
# File 'random.c', line 322

static VALUE
rb_f_srand(argc, argv, obj)
int argc;

#String(arg) ⇒ String

Converts arg to a String by calling its to_s method.

String(self)        #=> "main"
String(self.class   #=> "Object"
String(123456)      #=> "123456"

Returns:



2494
2495
2496
 
# File 'object.c', line 2494

static VALUE
rb_f_string(obj, arg)
VALUE obj, arg;

#sub(pattern, replacement) ⇒ Object #sub(pattern) { ... } ⇒ Object

Equivalent to $_.sub(args), except that $_ will be updated if substitution occurs.

Overloads:

  • #sub(pattern) { ... } ⇒ Object

    Yields:



2315
2316
2317
 
# File 'string.c', line 2315

static VALUE
rb_f_sub(argc, argv)
int argc;

#sub!(pattern, replacement) ⇒ nil #sub!(pattern) {|...| ... } ⇒ nil

Equivalent to $_.sub!(args).

Overloads:

  • #sub!(pattern, replacement) ⇒ nil

    Returns:

    • (nil)
  • #sub!(pattern) {|...| ... } ⇒ nil

    Yields:

    • (...)

    Returns:

    • (nil) 


2298
2299
2300
 
# File 'string.c', line 2298

static VALUE
rb_f_sub_bang(argc, argv)
int argc;

#test(int_cmd, file1[, file2]) ⇒ Object

Uses the integer aCmd to perform various tests on file1 (first table below) or on file1 and file2 (second table).

File tests on a single file:

Test   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

Returns:



3333
3334
3335
 
# File 'file.c', line 3333

static VALUE
rb_f_test(argc, argv)
int argc;

#throw ⇒ Object

#trace_var ⇒ Object 



7707
 
# File 'eval.c', line 7707

VALUE rb_f_trace_var();

#trap(signal, proc) ⇒ Object #trap(signal) {|| ... } ⇒ Object

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 operating system’s default handler will be invoked. If the command is “EXIT”, the script will be terminated by the signal. 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

Overloads:



881
882
883
 
# File 'signal.c', line 881

static VALUE
sig_trap(argc, argv)
int argc;

#untrace_var ⇒ Object 



7708
 
# File 'eval.c', line 7708

VALUE rb_f_untrace_var();

#warn(msg) ⇒ nil

Display the given message (followed by a newline) on STDERR unless warnings are disabled (for example with the -W0 flag).

Returns:

  • (nil) 


180
181
182
 
# File 'error.c', line 180

static VALUE
rb_warn_m(self, mesg)
VALUE self, mesg;