# # The Kernel module is included by class Object, so its methods are available in # every Ruby object. # # The Kernel instance methods are documented in class Object while the module # methods are documented here. These methods are called without a receiver and # thus can be called in functional form: # # sprintf "%.1f", 1.234 #=> "1.2" # # ## What's Here # # Module Kernel provides methods that are useful for: # # * [Converting](rdoc-ref:Kernel@Converting) # * [Querying](rdoc-ref:Kernel@Querying) # * [Exiting](rdoc-ref:Kernel@Exiting) # * [Exceptions](rdoc-ref:Kernel@Exceptions) # * [IO](rdoc-ref:Kernel@IO) # * [Procs](rdoc-ref:Kernel@Procs) # * [Tracing](rdoc-ref:Kernel@Tracing) # * [Subprocesses](rdoc-ref:Kernel@Subprocesses) # * [Loading](rdoc-ref:Kernel@Loading) # * [Yielding](rdoc-ref:Kernel@Yielding) # * [Random Values](rdoc-ref:Kernel@Random+Values) # * [Other](rdoc-ref:Kernel@Other) # # # ### Converting # # * #Array: Returns an Array based on the given argument. # * #Complex: Returns a Complex based on the given arguments. # * #Float: Returns a Float based on the given arguments. # * #Hash: Returns a Hash based on the given argument. # * #Integer: Returns an Integer based on the given arguments. # * #Rational: Returns a Rational based on the given arguments. # * #String: Returns a String based on the given argument. # # # ### Querying # # * #__callee__: Returns the called name of the current method as a symbol. # * #__dir__: Returns the path to the directory from which the current method # is called. # * #__method__: Returns the name of the current method as a symbol. # * #autoload?: Returns the file to be loaded when the given module is # referenced. # * #binding: Returns a Binding for the context at the point of call. # * #block_given?: Returns `true` if a block was passed to the calling method. # * #caller: Returns the current execution stack as an array of strings. # * #caller_locations: Returns the current execution stack as an array of # Thread::Backtrace::Location objects. # * #class: Returns the class of `self`. # * #frozen?: Returns whether `self` is frozen. # * #global_variables: Returns an array of global variables as symbols. # * #local_variables: Returns an array of local variables as symbols. # * #test: Performs specified tests on the given single file or pair of files. # # # ### Exiting # # * #abort: Exits the current process after printing the given arguments. # * #at_exit: Executes the given block when the process exits. # * #exit: Exits the current process after calling any registered `at_exit` # handlers. # * #exit!: Exits the current process without calling any registered `at_exit` # handlers. # # # ### Exceptions # # * #catch: Executes the given block, possibly catching a thrown object. # * #raise (aliased as #fail): Raises an exception based on the given # arguments. # * #throw: Returns from the active catch block waiting for the given tag. # # # ### IO # # * ::pp: Prints the given objects in pretty form. # * #gets: Returns and assigns to `$_` the next line from the current input. # * #open: Creates an IO object connected to the given stream, file, or # subprocess. # * #p: Prints the given objects' inspect output to the standard output. # * #print: Prints the given objects to standard output without a newline. # * #printf: Prints the string resulting from applying the given format string # to any additional arguments. # * #putc: Equivalent to for the given object. # * #puts: Equivalent to `$stdout.puts(*objects)` for the given objects. # * #readline: Similar to #gets, but raises an exception at the end of file. # * #readlines: Returns an array of the remaining lines from the current # input. # * #select: Same as IO.select. # # # ### Procs # # * #lambda: Returns a lambda proc for the given block. # * #proc: Returns a new Proc; equivalent to Proc.new. # # # ### Tracing # # * #set_trace_func: Sets the given proc as the handler for tracing, or # disables tracing if given `nil`. # * #trace_var: Starts tracing assignments to the given global variable. # * #untrace_var: Disables tracing of assignments to the given global # variable. # # # ### Subprocesses # # * [\`command`](rdoc-ref:Kernel#`): Returns the standard output of running # `command` in a subshell. # * #exec: Replaces current process with a new process. # * #fork: Forks the current process into two processes. # * #spawn: Executes the given command and returns its pid without waiting for # completion. # * #system: Executes the given command in a subshell. # # # ### Loading # # * #autoload: Registers the given file to be loaded when the given constant # is first referenced. # * #load: Loads the given Ruby file. # * #require: Loads the given Ruby file unless it has already been loaded. # * #require_relative: Loads the Ruby file path relative to the calling file, # unless it has already been loaded. # # # ### Yielding # # * #tap: Yields `self` to the given block; returns `self`. # * #then (aliased as #yield_self): Yields `self` to the block and returns the # result of the block. # # # ### Random Values # # * #rand: Returns a pseudo-random floating point number strictly between 0.0 # and 1.0. # * #srand: Seeds the pseudo-random number generator with the given number. # # # ### Other # # * #eval: Evaluates the given string as Ruby code. # * #loop: Repeatedly executes the given block. # * #sleep: Suspends the current thread for the given number of seconds. # * #sprintf (aliased as #format): Returns the string resulting from applying # the given format string to any additional arguments. # * #syscall: Runs an operating system call. # * #trap: Specifies the handling of system signals. # * #warn: Issue a warning based on the given messages and options. # %a{annotate:rdoc:source:from=object.c} module Kernel : BasicObject # # 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 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 `
'"] # c(1) #=> ["prog:5:in `b'", "prog:8:in `c'", "prog:11:in `
'"] # c(2) #=> ["prog:8:in `c'", "prog:12:in `
'"] # c(3) #=> ["prog:13:in `
'"] # c(4) #=> [] # c(5) #=> nil # def self?.caller: (Integer start_or_range, ?Integer length) -> ::Array[String]? | (::Range[Integer] start_or_range) -> ::Array[String]? | () -> ::Array[String] # # Returns the current execution stack---an array containing backtrace location # objects. # # See Thread::Backtrace::Location for more information. # # 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 self?.caller_locations: (?Integer start_or_range, ?Integer length) -> ::Array[Thread::Backtrace::Location]? | (?::Range[Integer] start_or_range) -> ::Array[Thread::Backtrace::Location]? # # `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 # def self?.catch: [T] (T tag) { (T tag) -> untyped } -> untyped | () { (Object tag) -> untyped } -> untyped # # Returns the class of *obj*. This method must always be called with an explicit # receiver, as #class is also a reserved word in Ruby. # # 1.class #=> Integer # self.class #=> Object # def class: () -> untyped # # Evaluates the Ruby expression(s) in *string*. If *binding* is given, which # must be a Binding object, the evaluation is performed in its context. If the # optional *filename* and *lineno* parameters are present, they will be used # when reporting syntax errors. # # def get_binding(str) # return binding # end # str = "hello" # eval "str + ' Fred'" #=> "hello Fred" # eval "str + ' Fred'", get_binding("bye") #=> "bye Fred" # def self?.eval: (String arg0, ?Binding arg1, ?String filename, ?Integer lineno) -> untyped # # 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" # def self?.block_given?: () -> bool # # Returns the names of the current local variables. # # fred = 1 # for i in 1..10 # # ... # end # local_variables #=> [:fred, :i] # def self?.local_variables: () -> ::Array[Symbol] # # Seeds the system pseudo-random number generator, with `number`. The previous # seed value is returned. # # If `number` is omitted, seeds the generator using a source of entropy provided # by the operating system, if available (/dev/urandom on Unix systems or the RSA # cryptographic provider on Windows), which is then combined with the time, the # process id, and a sequence number. # # srand may be used to ensure repeatable sequences of pseudo-random numbers # between different runs of the program. By setting the seed to a known value, # programs can be made deterministic during testing. # # srand 1234 # => 268519324636777531569100071560086917274 # [ rand, rand ] # => [0.1915194503788923, 0.6221087710398319] # [ rand(10), rand(1000) ] # => [4, 664] # srand 1234 # => 1234 # [ rand, rand ] # => [0.1915194503788923, 0.6221087710398319] # def self?.srand: (?Numeric number) -> Numeric # # Creates a subprocess. If a block is specified, that block is run in the # subprocess, and the subprocess terminates with a status of zero. Otherwise, # the `fork` call returns twice, once in the parent, returning the process ID of # the child, and once in the child, returning *nil*. The child process can exit # using Kernel.exit! to avoid running any `at_exit` functions. The parent # process should use Process.wait to collect the termination statuses of its # children or use Process.detach to register disinterest in their status; # otherwise, the operating system may accumulate zombie processes. # # The thread calling fork is the only thread in the created child process. fork # doesn't copy other threads. # # If fork is not usable, Process.respond_to?(:fork) returns false. # # Note that fork(2) is not available on some platforms like Windows and NetBSD # 4. Therefore you should use spawn() instead of fork(). # def self?.fork: () -> Integer? | () { () -> untyped } -> Integer? def initialize_copy: (self object) -> self # # Returns an array converted from `object`. # # Tries to convert `object` to an array using `to_ary` first and `to_a` second: # # Array([0, 1, 2]) # => [0, 1, 2] # Array({foo: 0, bar: 1}) # => [[:foo, 0], [:bar, 1]] # Array(0..4) # => [0, 1, 2, 3, 4] # # Returns `object` in an array, `[object]`, if `object` cannot be converted: # # Array(:foo) # => [:foo] # def self?.Array: (NilClass x) -> [ ] | [T] (::Array[T] x) -> ::Array[T] | [T] (::Range[T] x) -> ::Array[T] | [T] (_Each[T] x) -> ::Array[T] | [K, V] (::Hash[K, V] x) -> ::Array[[ K, V ]] | [T] (T x) -> ::Array[T] # # Returns x+i*y; # # Complex(1, 2) #=> (1+2i) # Complex('1+2i') #=> (1+2i) # Complex(nil) #=> TypeError # Complex(1, nil) #=> TypeError # # Complex(1, nil, exception: false) #=> nil # Complex('1+2', exception: false) #=> nil # # Syntax of string form: # # string form = extra spaces , complex , extra spaces ; # complex = real part | [ sign ] , imaginary part # | real part , sign , imaginary part # | rational , "@" , rational ; # real part = rational ; # imaginary part = imaginary unit | unsigned rational , imaginary unit ; # 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 ] ; # imaginary unit = "i" | "I" | "j" | "J" ; # sign = "-" | "+" ; # digits = digit , { digit | "_" , digit }; # digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; # extra spaces = ? \s* ? ; # # See String#to_c. # def self?.Complex: (Numeric | String x, ?Numeric | String y, ?exception: bool exception) -> Complex # # Returns *arg* converted to a float. Numeric types are converted directly, and # with exception to String and `nil` the rest are converted using *arg*`.to_f`. # Converting a String with invalid characters will result in a ArgumentError. # Converting `nil` generates a TypeError. Exceptions can be suppressed by # passing `exception: false`. # # Float(1) #=> 1.0 # Float("123.456") #=> 123.456 # Float("123.0_badstring") #=> ArgumentError: invalid value for Float(): "123.0_badstring" # Float(nil) #=> TypeError: can't convert nil into Float # Float("123.0_badstring", exception: false) #=> nil # def self?.Float: (Numeric | String x, ?exception: bool exception) -> Float # # Returns a hash converted from `object`. # # * If `object` is: # # * A hash, returns `object`. # * An empty array or `nil`, returns an empty hash. # # # * Otherwise, if `object.to_hash` returns a hash, returns that hash. # * Otherwise, returns TypeError. # # # Examples: # # Hash({foo: 0, bar: 1}) # => {:foo=>0, :bar=>1} # Hash(nil) # => {} # Hash([]) # => {} # def self?.Hash: [K, V] (Object x) -> ::Hash[K, V] # # Returns an integer converted from `object`. # # Tries to convert `object` to an integer using `to_int` first and `to_i` # second; see below for exceptions. # # With a non-zero `base`, `object` must be a string or convertible to a string. # # #### numeric objects # # With integer argument `object` given, returns `object`: # # Integer(1) # => 1 # Integer(-1) # => -1 # # With floating-point argument `object` given, returns `object` truncated to an # intger: # # Integer(1.9) # => 1 # Rounds toward zero. # Integer(-1.9) # => -1 # Rounds toward zero. # # #### string objects # # With string argument `object` and zero `base` given, returns `object` # converted to an integer in base 10: # # Integer('100') # => 100 # Integer('-100') # => -100 # # With `base` zero, string `object` may contain leading characters to specify # the actual base (radix indicator): # # Integer('0100') # => 64 # Leading '0' specifies base 8. # Integer('0b100') # => 4 # Leading '0b', specifies base 2. # Integer('0x100') # => 256 # Leading '0x' specifies base 16. # # With a positive `base` (in range 2..36) given, returns `object` converted to # an integer in the given base: # # Integer('100', 2) # => 4 # Integer('100', 8) # => 64 # Integer('-100', 16) # => -256 # # With a negative `base` (in range -36..-2) given, returns `object` converted to # an integer in the radix indicator if exists or `-base`: # # Integer('0x100', -2) # => 256 # Integer('100', -2) # => 4 # Integer('0b100', -8) # => 4 # Integer('100', -8) # => 64 # Integer('0o100', -10) # => 64 # Integer('100', -10) # => 100 # # `base` -1 is equal the -10 case. # # When converting strings, surrounding whitespace and embedded underscores are # allowed and ignored: # # Integer(' 100 ') # => 100 # Integer('-1_0_0', 16) # => -256 # # #### other classes # # Examples with `object` of various other classes: # # Integer(Rational(9, 10)) # => 0 # Rounds toward zero. # Integer(Complex(2, 0)) # => 2 # Imaginary part must be zero. # Integer(Time.now) # => 1650974042 # # #### keywords # # With optional keyword argument `exception` given as `true` (the default): # # * Raises TypeError if `object` does not respond to `to_int` or `to_i`. # * Raises TypeError if `object` is `nil`. # * Raise ArgumentError if `object` is an invalid string. # # # With `exception` given as `false`, an exception of any kind is suppressed and # `nil` is returned. # def self?.Integer: (Numeric | String arg, ?exception: bool exception) -> Integer | (String arg, ?Integer base, ?exception: bool exception) -> Integer # # 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. # def self?.Rational: (Numeric | String | Object x, ?Numeric | String y, ?exception: bool exception) -> Rational # # Returns a string converted from `object`. # # Tries to convert `object` to a string using `to_str` first and `to_s` second: # # String([0, 1, 2]) # => "[0, 1, 2]" # String(0..5) # => "0..5" # String({foo: 0, bar: 1}) # => "{:foo=>0, :bar=>1}" # # Raises `TypeError` if `object` cannot be converted to a string. # def self?.String: (_ToStr | _ToS x) -> String # # Returns the called name of the current method as a Symbol. If called outside # of a method, it returns `nil`. # def self?.__callee__: () -> Symbol? # # Returns the canonicalized absolute path of the directory of the file from # which this method is called. It means symlinks in the path is resolved. If # `__FILE__` is `nil`, it returns `nil`. The return value equals to # `File.dirname(File.realpath(__FILE__))`. # def self?.__dir__: () -> String? # # Returns the name at the definition of the current method as a Symbol. If # called outside of a method, it returns `nil`. # def self?.__method__: () -> Symbol? # # Returns the `$stdout` output from running `command` in a subshell; sets global # variable `$?` to the process status. # # This method has potential security vulnerabilities if called with untrusted # input; see [Command Injection](rdoc-ref:command_injection.rdoc). # # Examples: # # $ `date` # => "Wed Apr 9 08:56:30 CDT 2003\n" # $ `echo oops && exit 99` # => "oops\n" # $ $? # => # # $ $?.status # => 99> # # The built-in syntax `%x{...}` uses this method. # def self?.`: (String arg0) -> String # # Terminate execution immediately, effectively by calling `Kernel.exit(false)`. # If *msg* is given, it is written to STDERR prior to terminating. # def self?.abort: (?String msg) -> bot # # 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 # def self?.at_exit: () { () -> untyped } -> Proc # # Registers _filename_ to be loaded (using Kernel::require) # the first time that _const_ (which may be a String or # a symbol) is accessed. # # autoload(:MyModule, "/usr/local/lib/modules/my_module.rb") # # If *const* is defined as autoload, the file name to be loaded is replaced with # *filename*. If *const* is defined but not as autoload, does nothing. # def self?.autoload: (String | Symbol _module, String filename) -> NilClass # # Returns *filename* to be loaded if *name* is registered as `autoload`. # # autoload(:B, "b") # autoload?(:B) #=> "b" # def self?.autoload?: (Symbol | String name) -> String? # # 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" # def self?.binding: () -> Binding # # 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. `true` and `FALSE` of # *status* means success and failure respectively. The interpretation of other # integer values are system dependent. # # 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 # def self?.exit: () -> bot | (?Integer | TrueClass | FalseClass status) -> bot # # Exits the process immediately. No exit handlers are run. *status* is returned # to the underlying system as the exit status. # # Process.exit!(true) # def self?.exit!: (Integer | TrueClass | FalseClass status) -> bot # # 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 an # `Exception` class (or another object that returns an `Exception` object when # sent an `exception` message). The optional second parameter sets the message # associated with the exception (accessible via Exception#message), and the # third parameter is an array of callback information (accessible via # Exception#backtrace). The `cause` of the generated exception (accessible via # Exception#cause) is automatically set to the "current" exception (`$!`), if # any. An alternative value, either an `Exception` object or `nil`, can be # specified via the `:cause` argument. # # Exceptions are caught by the `rescue` clause of `begin...end` blocks. # # raise "Failed to create socket" # raise ArgumentError, "No parameters", caller # def self?.fail: () -> bot | (String message, ?cause: Exception?) -> bot | (_Exception exception, ?untyped message, ?::Array[String] backtrace, ?cause: Exception?) -> bot # # 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 an # `Exception` class (or another object that returns an `Exception` object when # sent an `exception` message). The optional second parameter sets the message # associated with the exception (accessible via Exception#message), and the # third parameter is an array of callback information (accessible via # Exception#backtrace). The `cause` of the generated exception (accessible via # Exception#cause) is automatically set to the "current" exception (`$!`), if # any. An alternative value, either an `Exception` object or `nil`, can be # specified via the `:cause` argument. # # Exceptions are caught by the `rescue` clause of `begin...end` blocks. # # raise "Failed to create socket" # raise ArgumentError, "No parameters", caller # alias raise fail alias self.raise self.fail # # Returns the string resulting from formatting `objects` into `format_string`. # # For details on `format_string`, see [Format # Specifications](rdoc-ref:format_specifications.rdoc). # # Kernel#format is an alias for Kernel#sprintf. # def self?.format: (String format, *untyped args) -> String # # Returns the string resulting from formatting `objects` into `format_string`. # # For details on `format_string`, see [Format # Specifications](rdoc-ref:format_specifications.rdoc). # # Kernel#format is an alias for Kernel#sprintf. # alias sprintf format alias self.sprintf self.format # # Returns (and assigns to `$_`) the next line from the list of files in `ARGV` # (or `$*`), or from standard input if no files are present on the command line. # Returns `nil` at end of file. The optional argument specifies the record # separator. The separator is included with the contents of each record. A # separator of `nil` reads the entire contents, and a zero-length separator # reads the input one paragraph at a time, where paragraphs are divided by two # consecutive newlines. If the first argument is an integer, or optional second # argument is given, the returning string would not be longer than the given # value in bytes. If multiple filenames are present in `ARGV`, `gets(nil)` will # read the contents one file at a time. # # ARGV << "testfile" # print while gets # # *produces:* # # This is line one # This is line two # This is line three # And so on... # # The style of programming using `$_` as an implicit parameter is gradually # losing favor in the Ruby community. # def self?.gets: (?String arg0, ?Integer arg1) -> String? # # Returns an array of the names of global variables. This includes special # regexp global variables such as `$~` and `$+`, but does not include the # numbered regexp global variables (`$1`, `$2`, etc.). # # global_variables.grep /std/ #=> [:$stdin, :$stdout, :$stderr] # def self?.global_variables: () -> ::Array[Symbol] # # 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. # def self?.load: (String filename, ?Module | bool) -> bool # # 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 =~ /^q/i # # ... # 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 # def self?.loop: () { (nil) -> untyped } -> bot | () -> ::Enumerator[nil, bot] # # Creates an IO object connected to the given stream, file, or subprocess. # # Required string argument `path` determines which of the following occurs: # # * The file at the specified `path` is opened. # * The process forks. # * A subprocess is created. # # # Each of these is detailed below. # # **File Opened** # # If `path` does *not* start with a pipe character (`'|'`), a file stream is # opened with `File.open(path, mode, perm, **opts)`. # # With no block given, file stream is returned: # # open('t.txt') # => # # # With a block given, calls the block with the open file stream, then closes the # stream: # # open('t.txt') {|f| p f } # => # # # Output: # # # # # See File.open for details. # # **Process Forked** # # If `path` is the 2-character string `'|-'`, the process forks and the child # process is connected to the parent. # # With no block given: # # io = open('|-') # if io # $stderr.puts "In parent, child pid is #{io.pid}." # else # $stderr.puts "In child, pid is #{$$}." # end # # Output: # # In parent, child pid is 27903. # In child, pid is 27903. # # With a block given: # # open('|-') do |io| # if io # $stderr.puts "In parent, child pid is #{io.pid}." # else # $stderr.puts "In child, pid is #{$$}." # end # end # # Output: # # In parent, child pid is 28427. # In child, pid is 28427. # # **Subprocess Created** # # If `path` is `'|command'` (`'command' != '-'`), a new subprocess runs the # command; its open stream is returned. Note that the command may be processed # by shell if it contains shell metacharacters. # # With no block given: # # io = open('|echo "Hi!"') # => # # print io.gets # io.close # # Output: # # "Hi!" # # With a block given, calls the block with the stream, then closes the stream: # # open('|echo "Hi!"') do |io| # print io.gets # end # # Output: # # "Hi!" # def self?.open: (String name, ?String mode, ?Integer perm) -> IO? | [T] (String name, ?String mode, ?Integer perm) { (IO) -> T } -> T # # Equivalent to `$stdout.print(*objects)`, this method is the straightforward # way to write to `$stdout`. # # Writes the given objects to `$stdout`; returns `nil`. Appends the output # record separator `$OUTPUT_RECORD_SEPARATOR` `$\`), if it is not `nil`. # # With argument `objects` given, for each object: # # * Converts via its method `to_s` if not a string. # * Writes to `stdout`. # * If not the last object, writes the output field separator # `$OUTPUT_FIELD_SEPARATOR` (`$,` if it is not `nil`. # # # With default separators: # # objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero'] # $OUTPUT_RECORD_SEPARATOR # $OUTPUT_FIELD_SEPARATOR # print(*objects) # # Output: # # nil # nil # 00.00/10+0izerozero # # With specified separators: # # $OUTPUT_RECORD_SEPARATOR = "\n" # $OUTPUT_FIELD_SEPARATOR = ',' # print(*objects) # # Output: # # 0,0.0,0/1,0+0i,zero,zero # # With no argument given, writes the content of `$_` (which is usually the most # recent user input): # # gets # Sets $_ to the most recent user input. # print # Prints $_. # def self?.print: (*Kernel args) -> nil # # Equivalent to: # # io.write(sprintf(format_string, *objects)) # # For details on `format_string`, see [Format # Specifications](rdoc-ref:format_specifications.rdoc). # # With the single argument `format_string`, formats `objects` into the string, # then writes the formatted string to $stdout: # # printf('%4.4d %10s %2.2f', 24, 24, 24.0) # # Output (on $stdout): # # 0024 24 24.00# # # With arguments `io` and `format_string`, formats `objects` into the string, # then writes the formatted string to `io`: # # printf($stderr, '%4.4d %10s %2.2f', 24, 24, 24.0) # # Output (on $stderr): # # 0024 24 24.00# => nil # # With no arguments, does nothing. # def self?.printf: (IO arg0, String arg1, *untyped args) -> nil | (String arg1, *untyped args) -> nil | () -> nil # # Equivalent to Proc.new. # def self?.proc: () { () -> untyped } -> Proc # # Equivalent to Proc.new, except the resulting Proc objects check the number of # parameters passed when called. # def self?.lambda: () { () -> untyped } -> Proc # # Equivalent to: # # $stdout.putc(int) # # See IO#putc for important information regarding multi-byte characters. # def self?.putc: (Integer arg0) -> Integer | (String arg0) -> String # # Equivalent to # # $stdout.puts(objects) # def self?.puts: (*untyped arg0) -> NilClass # # For each object `obj`, executes: # # $stdout.write(obj.inspect, "\n") # # With one object given, returns the object; with multiple objects given, # returns an array containing the objects; with no object given, returns `nil`. # # Examples: # # r = Range.new(0, 4) # p r # => 0..4 # p [r, r, r] # => [0..4, 0..4, 0..4] # p # => nil # # Output: # # 0..4 # [0..4, 0..4, 0..4] # def self?.p: [T] (T arg0) -> T | (*untyped arg0) -> Array[untyped] # # prints arguments in pretty form. # # pp returns argument(s). # def self?.pp: [T] (T arg0) -> T | (*untyped arg0) -> Array[untyped] # # If called without an argument, or if `max.to_i.abs == 0`, rand returns a # pseudo-random floating point number between 0.0 and 1.0, including 0.0 and # excluding 1.0. # # rand #=> 0.2725926052826416 # # When `max.abs` is greater than or equal to 1, `rand` returns a pseudo-random # integer greater than or equal to 0 and less than `max.to_i.abs`. # # rand(100) #=> 12 # # When `max` is a Range, `rand` returns a random number where # `range.member?(number) == true`. # # Negative or floating point values for `max` are allowed, but may give # surprising results. # # rand(-100) # => 87 # rand(-0.5) # => 0.8130921818028143 # rand(1.9) # equivalent to rand(1), which is always 0 # # Kernel.srand may be used to ensure that sequences of random numbers are # reproducible between different runs of a program. # # See also Random.rand. # def self?.rand: () -> Float | (Integer arg0) -> Integer | (::Range[Integer] arg0) -> Integer | (::Range[Float] arg0) -> Float # # Equivalent to method Kernel#gets, except that it raises an exception if called # at end-of-stream: # # $ cat t.txt | ruby -e "p readlines; readline" # ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"] # in `readline': end of file reached (EOFError) # # Optional keyword argument `chomp` specifies whether line separators are to be # omitted. # def self?.readline: (?String arg0, ?Integer arg1) -> String # # Returns an array containing the lines returned by calling Kernel#gets until # the end-of-stream is reached; (see [Line IO](rdoc-ref:IO@Line+IO)). # # With only string argument `sep` given, returns the remaining lines as # determined by line separator `sep`, or `nil` if none; see [Line # Separator](rdoc-ref:IO@Line+Separator): # # # Default separator. # $ cat t.txt | ruby -e "p readlines" # ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"] # # # Specified separator. # $ cat t.txt | ruby -e "p readlines 'li'" # ["First li", "ne\nSecond li", "ne\n\nFourth li", "ne\nFifth li", "ne\n"] # # # Get-all separator. # $ cat t.txt | ruby -e "p readlines nil" # ["First line\nSecond line\n\nFourth line\nFifth line\n"] # # # Get-paragraph separator. # $ cat t.txt | ruby -e "p readlines ''" # ["First line\nSecond line\n\n", "Fourth line\nFifth line\n"] # # With only integer argument `limit` given, limits the number of bytes in the # line; see [Line Limit](rdoc-ref:IO@Line+Limit): # # $cat t.txt | ruby -e "p readlines 10" # ["First line", "\n", "Second lin", "e\n", "\n", "Fourth lin", "e\n", "Fifth line", "\n"] # # $cat t.txt | ruby -e "p readlines 11" # ["First line\n", "Second line", "\n", "\n", "Fourth line", "\n", "Fifth line\n"] # # $cat t.txt | ruby -e "p readlines 12" # ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"] # # With arguments `sep` and `limit` given, combines the two behaviors; see [Line # Separator and Line Limit](rdoc-ref:IO@Line+Separator+and+Line+Limit). # # Optional keyword argument `chomp` specifies whether line separators are to be # omitted: # # $ cat t.txt | ruby -e "p readlines(chomp: true)" # ["First line", "Second line", "", "Fourth line", "Fifth line"] # # Optional keyword arguments `enc_opts` specify encoding options; see [Encoding # options](rdoc-ref:encodings.rdoc@Encoding+Options). # def self?.readlines: (?String arg0, ?Integer arg1) -> ::Array[String] # # When RubyGems is required, Kernel#require is replaced with our own which is # capable of loading gems on demand. # # When you call `require 'x'`, this is what happens: # * If the file can be loaded from the existing Ruby loadpath, it is. # * Otherwise, installed gems are searched for a file that matches. If it's # found in gem 'y', that gem is activated (added to the loadpath). # # # The normal `require` functionality of returning false if that file has already # been loaded is preserved. # def self?.require: (String path) -> bool # # Ruby tries to load the library named *string* relative to the directory # containing the requiring file. If the file does not exist a LoadError is # raised. Returns `true` if the file was loaded and `false` if the file was # already loaded before. # def self?.require_relative: (String feature) -> bool # # Invokes system call [select(2)](https://linux.die.net/man/2/select), which # monitors multiple file descriptors, waiting until one or more of the file # descriptors becomes ready for some class of I/O operation. # # Not implemented on all platforms. # # Each of the arguments `read_ios`, `write_ios`, and `error_ios` is an array of # IO objects. # # Argument `timeout` is an integer timeout interval in seconds. # # The method monitors the IO objects given in all three arrays, waiting for some # to be ready; returns a 3-element array whose elements are: # # * An array of the objects in `read_ios` that are ready for reading. # * An array of the objects in `write_ios` that are ready for writing. # * An array of the objects in `error_ios` have pending exceptions. # # # If no object becomes ready within the given `timeout`, `nil` is returned. # # 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 non-blocking 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 non-blocking 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 non-blocking 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)](https://linux.die.net/man/2/select) # # 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 # # 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 # } # # Output: # # ping pong # ping pong # ping pong # (snipped) # ping # def self?.select: (::Array[IO] read, ?::Array[IO] write, ?::Array[IO] error, ?Integer timeout) -> ::Array[String] # # Suspends the current thread for *duration* seconds (which may be any number, # including a `Float` with fractional seconds). Returns the actual number of # seconds slept (rounded), which may be less than that asked for if another # thread calls Thread#run. Called without an argument, sleep() will sleep # forever. # # Time.new #=> 2008-03-08 19:56:19 +0900 # sleep 1.2 #=> 1 # Time.new #=> 2008-03-08 19:56:20 +0900 # sleep 1.9 #=> 2 # Time.new #=> 2008-03-08 19:56:22 +0900 # def self?.sleep: () -> bot | ((Integer | Float | _Divmod) duration) -> Integer interface _Divmod def divmod: (Numeric) -> [ Numeric, Numeric ] end # # Invokes Posix system call [syscall(2)](https://linux.die.net/man/2/syscall), # which calls a specified function. # # Calls the operating system function identified by `integer_callno`; returns # the result of the function or raises SystemCallError if it failed. The effect # of the call is platform-dependent. The arguments and returned value are # platform-dependent. # # For each of `arguments`: if it is an integer, it is passed directly; if it is # a string, it is interpreted as a binary sequence of bytes. There may be as # many as nine such arguments. # # Arguments `integer_callno` and `argument`, as well as the returned value, are # platform-dependent. # # Note: Method `syscall` is essentially unsafe and unportable. The DL (Fiddle) # library is preferred for safer and a bit more portable programming. # # Not implemented on all platforms. # def self?.syscall: (Integer num, *untyped args) -> untyped # # 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 setgid bit set # "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 # def self?.test: (String | Integer cmd, String | IO file1, ?String | IO file2) -> (TrueClass | FalseClass | Time | nil | Integer) # # 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. # def self?.throw: (Object tag, ?untyped obj) -> bot # # If warnings have been disabled (for example with the `-W0` flag), does # nothing. Otherwise, converts each of the messages to strings, appends a # newline character to the string if the string does not end in a newline, and # calls Warning.warn with the string. # # warn("warning 1", "warning 2") # # produces: # # warning 1 # warning 2 # # If the `uplevel` keyword argument is given, the string will be prepended with # information for the given caller frame in the same format used by the # `rb_warn` C function. # # # In baz.rb # def foo # warn("invalid call to foo", uplevel: 1) # end # # def bar # foo # end # # bar # # produces: # # baz.rb:6: warning: invalid call to foo # # If `category` keyword argument is given, passes the category to # `Warning.warn`. The category given must be be one of the following # categories: # # :deprecated # : Used for warning for deprecated functionality that may be removed in the # future. # :experimental # : Used for experimental features that may change in future releases. # def self?.warn: (*untyped msg, ?uplevel: Integer | nil, ?category: :deprecated | :experimental | nil) -> NilClass # # Replaces the current process by running the given external *command*, which # can take one of the following forms: # # `exec(commandline)` # : command line string which is passed to the standard shell # `exec(cmdname, arg1, ...)` # : command name and one or more arguments (no shell) # `exec([cmdname, argv0], arg1, ...)` # : command name, `argv[0]` and zero or more arguments (no shell) # # # In the first form, the string is taken as a command line that is subject to # shell expansion before being executed. # # The standard shell always means `"/bin/sh"` on Unix-like systems, otherwise, # `ENV["RUBYSHELL"]` or `ENV["COMSPEC"]` on Windows and similar. The command is # passed as an argument to the `"-c"` switch to the shell, except in the case of # `COMSPEC`. # # If the string from the first form (`exec("command")`) follows these simple # rules: # # * no meta characters, # * not starting with shell reserved word or special built-in, # # # Ruby invokes the command directly without shell. # # You can force shell invocation by adding ";" to the string (because ";" is a # meta character). # # Note that this behavior is observable by pid obtained (return value of spawn() # and IO#pid for IO.popen) is the pid of the invoked command, not shell. # # In the second form (`exec("command1", "arg1", ...)`), the first is taken as a # command name and the rest are passed as parameters to command with no shell # expansion. # # In the third form (`exec(["command", "argv0"], "arg1", ...)`), starting a # two-element array at the beginning of the command, the first element is the # command to be executed, and the second argument is used as the `argv[0]` # value, which may show up in process listings. # # In order to execute the command, one of the `exec(2)` system calls are used, # so the running command may inherit some of the environment of the original # program (including open file descriptors). # # This behavior is modified by the given `env` and `options` parameters. See # ::spawn for details. # # If the command fails to execute (typically Errno::ENOENT when it was not # found) a SystemCallError exception is raised. # # This method modifies process attributes according to given `options` before # `exec(2)` system call. See ::spawn for more details about the given `options`. # # The modified attributes may be retained when `exec(2)` system call fails. # # For example, hard resource limits are not restorable. # # Consider to create a child process using ::spawn or Kernel#system if this is # not acceptable. # # exec "echo *" # echoes list of files in current directory # # never get here # # exec "echo", "*" # echoes an asterisk # # never get here # def self?.exec: (*String args) -> bot type redirect_fd = Integer | :in | :out | :err | IO | String | [ String ] | [ String, string | int ] | [ String, string | int, int ] | [ :child, int ] | :close # # spawn executes specified command and return its pid. # # pid = spawn("tar xf ruby-2.0.0-p195.tar.bz2") # Process.wait pid # # pid = spawn(RbConfig.ruby, "-eputs'Hello, world!'") # Process.wait pid # # This method is similar to Kernel#system but it doesn't wait for the command to # finish. # # The parent process should use Process.wait to collect the termination status # of its child or use Process.detach to register disinterest in their status; # otherwise, the operating system may accumulate zombie processes. # # spawn has bunch of options to specify process attributes: # # env: hash # name => val : set the environment variable # name => nil : unset the environment variable # # the keys and the values except for +nil+ must be strings. # command...: # commandline : command line string which is passed to the standard shell # cmdname, arg1, ... : command name and one or more arguments (This form does not use the shell. See below for caveats.) # [cmdname, argv0], arg1, ... : command name, argv[0] and zero or more arguments (no shell) # options: hash # clearing environment variables: # :unsetenv_others => true : clear environment variables except specified by env # :unsetenv_others => false : don't clear (default) # process group: # :pgroup => true or 0 : make a new process group # :pgroup => pgid : join the specified process group # :pgroup => nil : don't change the process group (default) # create new process group: Windows only # :new_pgroup => true : the new process is the root process of a new process group # :new_pgroup => false : don't create a new process group (default) # resource limit: resourcename is core, cpu, data, etc. See Process.setrlimit. # :rlimit_resourcename => limit # :rlimit_resourcename => [cur_limit, max_limit] # umask: # :umask => int # redirection: # key: # FD : single file descriptor in child process # [FD, FD, ...] : multiple file descriptor in child process # value: # FD : redirect to the file descriptor in parent process # string : redirect to file with open(string, "r" or "w") # [string] : redirect to file with open(string, File::RDONLY) # [string, open_mode] : redirect to file with open(string, open_mode, 0644) # [string, open_mode, perm] : redirect to file with open(string, open_mode, perm) # [:child, FD] : redirect to the redirected file descriptor # :close : close the file descriptor in child process # FD is one of follows # :in : the file descriptor 0 which is the standard input # :out : the file descriptor 1 which is the standard output # :err : the file descriptor 2 which is the standard error # integer : the file descriptor of specified the integer # io : the file descriptor specified as io.fileno # file descriptor inheritance: close non-redirected non-standard fds (3, 4, 5, ...) or not # :close_others => false : inherit # current directory: # :chdir => str # # The `cmdname, arg1, ...` form does not use the shell. However, on different # OSes, different things are provided as built-in commands. An example of this # is +'echo'+, which is a built-in on Windows, but is a normal program on Linux # and Mac OS X. This means that `Process.spawn 'echo', '%Path%'` will display # the contents of the `%Path%` environment variable on Windows, but # `Process.spawn 'echo', '$PATH'` prints the literal `$PATH`. # # If a hash is given as `env`, the environment is updated by `env` before # `exec(2)` in the child process. If a pair in `env` has nil as the value, the # variable is deleted. # # # set FOO as BAR and unset BAZ. # pid = spawn({"FOO"=>"BAR", "BAZ"=>nil}, command) # # If a hash is given as `options`, it specifies process group, create new # process group, resource limit, current directory, umask and redirects for the # child process. Also, it can be specified to clear environment variables. # # The `:unsetenv_others` key in `options` specifies to clear environment # variables, other than specified by `env`. # # pid = spawn(command, :unsetenv_others=>true) # no environment variable # pid = spawn({"FOO"=>"BAR"}, command, :unsetenv_others=>true) # FOO only # # The `:pgroup` key in `options` specifies a process group. The corresponding # value should be true, zero, a positive integer, or nil. true and zero cause # the process to be a process leader of a new process group. A non-zero positive # integer causes the process to join the provided process group. The default # value, nil, causes the process to remain in the same process group. # # pid = spawn(command, :pgroup=>true) # process leader # pid = spawn(command, :pgroup=>10) # belongs to the process group 10 # # The `:new_pgroup` key in `options` specifies to pass # `CREATE_NEW_PROCESS_GROUP` flag to `CreateProcessW()` that is Windows API. # This option is only for Windows. true means the new process is the root # process of the new process group. The new process has CTRL+C disabled. This # flag is necessary for `Process.kill(:SIGINT, pid)` on the subprocess. # :new_pgroup is false by default. # # pid = spawn(command, :new_pgroup=>true) # new process group # pid = spawn(command, :new_pgroup=>false) # same process group # # The `:rlimit_`*foo* key specifies a resource limit. *foo* should be one of # resource types such as `core`. The corresponding value should be an integer or # an array which have one or two integers: same as cur_limit and max_limit # arguments for Process.setrlimit. # # cur, max = Process.getrlimit(:CORE) # pid = spawn(command, :rlimit_core=>[0,max]) # disable core temporary. # pid = spawn(command, :rlimit_core=>max) # enable core dump # pid = spawn(command, :rlimit_core=>0) # never dump core. # # The `:umask` key in `options` specifies the umask. # # pid = spawn(command, :umask=>077) # # The :in, :out, :err, an integer, an IO and an array key specifies a # redirection. The redirection maps a file descriptor in the child process. # # For example, stderr can be merged into stdout as follows: # # pid = spawn(command, :err=>:out) # pid = spawn(command, 2=>1) # pid = spawn(command, STDERR=>:out) # pid = spawn(command, STDERR=>STDOUT) # # The hash keys specifies a file descriptor in the child process started by # #spawn. :err, 2 and STDERR specifies the standard error stream (stderr). # # The hash values specifies a file descriptor in the parent process which # invokes #spawn. :out, 1 and STDOUT specifies the standard output stream # (stdout). # # In the above example, the standard output in the child process is not # specified. So it is inherited from the parent process. # # The standard input stream (stdin) can be specified by :in, 0 and STDIN. # # A filename can be specified as a hash value. # # pid = spawn(command, :in=>"/dev/null") # read mode # pid = spawn(command, :out=>"/dev/null") # write mode # pid = spawn(command, :err=>"log") # write mode # pid = spawn(command, [:out, :err]=>"/dev/null") # write mode # pid = spawn(command, 3=>"/dev/null") # read mode # # For stdout and stderr (and combination of them), it is opened in write mode. # Otherwise read mode is used. # # For specifying flags and permission of file creation explicitly, an array is # used instead. # # pid = spawn(command, :in=>["file"]) # read mode is assumed # pid = spawn(command, :in=>["file", "r"]) # pid = spawn(command, :out=>["log", "w"]) # 0644 assumed # pid = spawn(command, :out=>["log", "w", 0600]) # pid = spawn(command, :out=>["log", File::WRONLY|File::EXCL|File::CREAT, 0600]) # # The array specifies a filename, flags and permission. The flags can be a # string or an integer. If the flags is omitted or nil, File::RDONLY is assumed. # The permission should be an integer. If the permission is omitted or nil, 0644 # is assumed. # # If an array of IOs and integers are specified as a hash key, all the elements # are redirected. # # # stdout and stderr is redirected to log file. # # The file "log" is opened just once. # pid = spawn(command, [:out, :err]=>["log", "w"]) # # Another way to merge multiple file descriptors is [:child, fd]. [:child, fd] # means the file descriptor in the child process. This is different from fd. For # example, :err=>:out means redirecting child stderr to parent stdout. But # :err=>[:child, :out] means redirecting child stderr to child stdout. They # differ if stdout is redirected in the child process as follows. # # # stdout and stderr is redirected to log file. # # The file "log" is opened just once. # pid = spawn(command, :out=>["log", "w"], :err=>[:child, :out]) # # [:child, :out] can be used to merge stderr into stdout in IO.popen. In this # case, IO.popen redirects stdout to a pipe in the child process and [:child, # :out] refers the redirected stdout. # # io = IO.popen(["sh", "-c", "echo out; echo err >&2", :err=>[:child, :out]]) # p io.read #=> "out\nerr\n" # # The `:chdir` key in `options` specifies the current directory. # # pid = spawn(command, :chdir=>"/var/tmp") # # spawn closes all non-standard unspecified descriptors by default. The # "standard" descriptors are 0, 1 and 2. This behavior is specified by # :close_others option. :close_others doesn't affect the standard descriptors # which are closed only if :close is specified explicitly. # # pid = spawn(command, :close_others=>true) # close 3,4,5,... (default) # pid = spawn(command, :close_others=>false) # don't close 3,4,5,... # # :close_others is false by default for spawn and IO.popen. # # Note that fds which close-on-exec flag is already set are closed regardless of # :close_others option. # # So IO.pipe and spawn can be used as IO.popen. # # # similar to r = IO.popen(command) # r, w = IO.pipe # pid = spawn(command, :out=>w) # r, w is closed in the child process. # w.close # # :close is specified as a hash value to close a fd individually. # # f = open(foo) # system(command, f=>:close) # don't inherit f. # # If a file descriptor need to be inherited, io=>io can be used. # # # valgrind has --log-fd option for log destination. # # log_w=>log_w indicates log_w.fileno inherits to child process. # log_r, log_w = IO.pipe # pid = spawn("valgrind", "--log-fd=#{log_w.fileno}", "echo", "a", log_w=>log_w) # log_w.close # p log_r.read # # It is also possible to exchange file descriptors. # # pid = spawn(command, :out=>:err, :err=>:out) # # The hash keys specify file descriptors in the child process. The hash values # specifies file descriptors in the parent process. So the above specifies # exchanging stdout and stderr. Internally, `spawn` uses an extra file # descriptor to resolve such cyclic file descriptor mapping. # # See Kernel.exec for the standard shell. # def self?.spawn: (String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> Integer | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> Integer # # Executes *command...* in a subshell. *command...* is one of following forms. # # This method has potential security vulnerabilities if called with untrusted # input; see [Command Injection](rdoc-ref:command_injection.rdoc). # # `commandline` # : command line string which is passed to the standard shell # `cmdname, arg1, ...` # : command name and one or more arguments (no shell) # `[cmdname, argv0], arg1, ...` # : command name, `argv[0]` and zero or more arguments (no shell) # # # system returns `true` if the command gives zero exit status, `false` for non # zero exit status. Returns `nil` if command execution fails. An error status is # available in `$?`. # # If the `exception: true` argument is passed, the method raises an exception # instead of returning `false` or `nil`. # # The arguments are processed in the same way as for Kernel#spawn. # # The hash arguments, env and options, are same as #exec and #spawn. See # Kernel#spawn for details. # # system("echo *") # system("echo", "*") # # *produces:* # # config.h main.rb # * # # Error handling: # # system("cat nonexistent.txt") # # => false # system("catt nonexistent.txt") # # => nil # # system("cat nonexistent.txt", exception: true) # # RuntimeError (Command failed with exit 1: cat) # system("catt nonexistent.txt", exception: true) # # Errno::ENOENT (No such file or directory - catt) # # See Kernel#exec for the standard shell. # def self?.system: (String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> (NilClass | FalseClass | TrueClass) | (Hash[string, string?] env, String command, *String args, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: redirect_fd, ?out: redirect_fd, ?err: redirect_fd, ?close_others: boolish, ?chdir: String) -> (NilClass | FalseClass | TrueClass) end Kernel::RUBYGEMS_ACTIVATION_MONITOR: untyped