diff options
Diffstat (limited to 'doc/globals.rdoc')
| -rw-r--r-- | doc/globals.rdoc | 491 |
1 files changed, 422 insertions, 69 deletions
diff --git a/doc/globals.rdoc b/doc/globals.rdoc index 1d7cda69f9..1b51bb1b36 100644 --- a/doc/globals.rdoc +++ b/doc/globals.rdoc @@ -1,69 +1,422 @@ -# -*- mode: rdoc; coding: utf-8; fill-column: 74; -*- - -== Pre-defined global variables - -$!:: The Exception object set by Kernel#raise. -$@:: The same as <code>$!.backtrace</code>. -$~:: The information about the last match in the current scope (thread-local and frame-local). -$&:: The string matched by the last successful match. -$`:: The string to the left of the last successful match. -$':: The string to the right of the last successful match. -$+:: The highest group matched by the last successful match. -$1:: The Nth group of the last successful match. May be > 1. -$=:: This variable is no longer effective. Deprecated. -$/:: The input record separator, newline by default. Aliased to $-0. -$\:: The output record separator for Kernel#print and IO#write. Default is +nil+. -$,:: The output field separator for Kernel#print and Array#join. Non-nil $, will be deprecated. -$;:: The default separator for String#split. Non-nil $; will be deprecated. Aliased to $-F. -$.:: The current input line number of the last file that was read. -$<:: The same as ARGF. -$>:: The default output stream for Kernel#print and Kernel#printf. $stdout by default. -$_:: The last input line of string by gets or readline. -$0:: Contains the name of the script being executed. May be assignable. -$*:: The same as ARGV. -$$:: The process number of the Ruby running this script. Same as Process.pid. -$?:: The status of the last executed child process (thread-local). -$LOAD_PATH:: Load path for searching Ruby scripts and extension libraries used - by Kernel#load and Kernel#require. Aliased to $: and $-I. - Has a singleton method <code>$LOAD_PATH.resolve_feature_path(feature)</code> - that returns [+:rb+ or +:so+, path], which resolves the feature to - the path the original Kernel#require method would load. -$LOADED_FEATURES:: The array contains the module names loaded by require. - Aliased to $". -$DEBUG:: The debug flag, which is set by the <tt>-d</tt> switch. Enabling debug - output prints each exception raised to $stderr (but not its - backtrace). Setting this to a true value enables debug output as - if <tt>-d</tt> were given on the command line. Setting this to a false - value disables debug output. Aliased to $-d. -$FILENAME:: Current input filename from ARGF. Same as ARGF.filename. -$stderr:: The current standard error output. -$stdin:: The current standard input. -$stdout:: The current standard output. -$VERBOSE:: The verbose flag, which is set by the <tt>-w</tt> or <tt>-v</tt> switch. - Setting this to a true value enables warnings as if <tt>-w</tt> or <tt>-v</tt> were given - on the command line. Setting this to +nil+ disables warnings, - including from Kernel#warn. Aliased to $-v and $-w. -$-a:: True if option <tt>-a</tt> is set. Read-only variable. -$-i:: In in-place-edit mode, this variable holds the extension, otherwise +nil+. -$-l:: True if option <tt>-l</tt> is set. Read-only variable. -$-p:: True if option <tt>-p</tt> is set. Read-only variable. - -== Pre-defined global constants - -STDIN:: The standard input. The default value for $stdin. -STDOUT:: The standard output. The default value for $stdout. -STDERR:: The standard error output. The default value for $stderr. -ENV:: The hash contains current environment variables. -ARGF:: The virtual concatenation of the files given on command line (or from $stdin if no files were given). -ARGV:: An Array of command line arguments given for the script. -DATA:: The file object of the script, pointing just after <code>__END__</code>. -TOPLEVEL_BINDING:: The Binding of the top level scope. -RUBY_VERSION:: The Ruby language version. -RUBY_RELEASE_DATE:: The release date string. -RUBY_PLATFORM:: The platform identifier. -RUBY_PATCHLEVEL:: The patchlevel for this Ruby. If this is a development build of Ruby the patchlevel will be -1. -RUBY_REVISION:: The GIT commit hash for this Ruby. -RUBY_COPYRIGHT:: The copyright string for Ruby. -RUBY_ENGINE:: The name of the Ruby implementation. -RUBY_ENGINE_VERSION:: The version of the Ruby implementation. -RUBY_DESCRIPTION:: The same as <tt>ruby --version</tt>, a String describing various aspects of the Ruby implementation. += Pre-Defined Global Variables + +Some of the pre-defined global variables have synonyms +that are available via module English. +For each of those, the \English synonym is given. + +To use the module: + + require 'English' + +== Exceptions + +=== <tt>$!</tt> (\Exception) + +Contains the Exception object set by Kernel#raise: + + begin + raise RuntimeError.new('Boo!') + rescue RuntimeError + p $! + end + +Output: + + #<RuntimeError: Boo!> + +English - <tt>$ERROR_INFO</tt> + +=== <tt>$@</tt> (Backtrace) + +Same as <tt>$!.backtrace</tt>; +returns an array of backtrace positions: + + begin + raise RuntimeError.new('Boo!') + rescue RuntimeError + pp $@.take(4) + end + +Output: + + ["(irb):338:in `<top (required)>'", + "/snap/ruby/317/lib/ruby/3.2.0/irb/workspace.rb:119:in `eval'", + "/snap/ruby/317/lib/ruby/3.2.0/irb/workspace.rb:119:in `evaluate'", + "/snap/ruby/317/lib/ruby/3.2.0/irb/context.rb:502:in `evaluate'"] + +English - <tt>$ERROR_POSITION</tt>. + +== Pattern Matching + +These global variables store information about the most recent +successful match in the current scope. + +For details and examples, +see {Regexp Global Variables}[rdoc-ref:Regexp@Global+Variables]. + +=== <tt>$~</tt> (\MatchData) + +MatchData object created from the match; +thread-local and frame-local. + +English - <tt>$LAST_MATCH_INFO</tt>. + +=== <tt>$&</tt> (Matched Substring) + +The matched string. + +English - <tt>$MATCH</tt>. + +=== <tt>$`</tt> (Pre-Match Substring) + +The string to the left of the match. + +English - <tt>$PREMATCH</tt>. + +=== <tt>$'</tt> (Post-Match Substring) + +The string to the right of the match. + +English - <tt>$POSTMATCH</tt>. + +=== <tt>$+</tt> (Last Matched Group) + +The last group matched. + +English - <tt>$LAST_PAREN_MATCH</tt>. + +=== <tt>$1</tt>, <tt>$2</tt>, \Etc. (Matched Group) + +For <tt>$_n_</tt> the _nth_ group of the match. + +No \English. + +== Separators + +=== <tt>$/</tt> (Input Record Separator) + +An input record separator, initially newline. + +English - <tt>$INPUT_RECORD_SEPARATOR</tt>, <tt>$RS</tt>. + +Aliased as <tt>$-0</tt>. + +=== <tt>$;</tt> (Input Field Separator) + +An input field separator, initially +nil+. + +English - <tt>$FIELD_SEPARATOR</tt>, <tt>$FS</tt>. + +Aliased as <tt>$-F</tt>. + +=== <tt>$\\</tt> (Output Record Separator) + +An output record separator, initially +nil+. + +English - <tt>$OUTPUT_RECORD_SEPARATOR</tt>, <tt>$ORS</tt>. + +== Streams + +=== <tt>$stdin</tt> (Standard Input) + +The current standard input stream; initially: + + $stdin # => #<IO:<STDIN>> + +=== <tt>$stdout</tt> (Standard Output) + +The current standard output stream; initially: + + $stdout # => #<IO:<STDOUT>> + +=== <tt>$stderr</tt> (Standard Error) + +The current standard error stream; initially: + + $stderr # => #<IO:<STDERR>> + +=== <tt>$<</tt> (\ARGF or $stdin) + +Points to stream ARGF if not empty, else to stream $stdin; read-only. + +English - <tt>$DEFAULT_INPUT</tt>. + +=== <tt>$></tt> (Default Standard Output) + +An output stream, initially <tt>$stdout</tt>. + +English - <tt>$DEFAULT_OUTPUT + +=== <tt>$.</tt> (Input Position) + +The input position (line number) in the most recently read stream. + +English - <tt>$INPUT_LINE_NUMBER</tt>, <tt>$NR</tt> + +=== <tt>$_</tt> (Last Read Line) + +The line (string) from the most recently read stream. + +English - <tt>$LAST_READ_LINE</tt>. + +== Processes + +=== <tt>$0</tt> + +Initially, contains the name of the script being executed; +may be reassigned. + +=== <tt>$*</tt> (\ARGV) + +Points to ARGV. + +English - <tt>$ARGV</tt>. + +=== <tt>$$</tt> (Process ID) + +The process ID of the current process. Same as Process.pid. + +English - <tt>$PROCESS_ID</tt>, <tt>$PID</tt>. + +=== <tt>$?</tt> (Child Status) + +Initially +nil+, otherwise the Process::Status object +created for the most-recently exited child process; +thread-local. + +English - <tt>$CHILD_STATUS</tt>. + +=== <tt>$LOAD_PATH</tt> (Load Path) + +Contains the array of paths to be searched +by Kernel#load and Kernel#require. + +Singleton method <tt>$LOAD_PATH.resolve_feature_path(feature)</tt> +returns: + +- <tt>[:rb, _path_]</tt>, where +path+ is the path to the Ruby file + to be loaded for the given +feature+. +- <tt>[:so+ _path_]</tt>, where +path+ is the path to the shared object file + to be loaded for the given +feature+. +- +nil+ if there is no such +feature+ and +path+. + +Examples: + + $LOAD_PATH.resolve_feature_path('timeout') + # => [:rb, "/snap/ruby/317/lib/ruby/3.2.0/timeout.rb"] + $LOAD_PATH.resolve_feature_path('date_core') + # => [:so, "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/date_core.so"] + $LOAD_PATH.resolve_feature_path('foo') + # => nil + +Aliased as <tt>$:</tt> and <tt>$-I</tt>. + +=== <tt>$LOADED_FEATURES</tt> + +Contains an array of the paths to the loaded files: + + $LOADED_FEATURES.take(10) + # => + ["enumerator.so", + "thread.rb", + "fiber.so", + "rational.so", + "complex.so", + "ruby2_keywords.rb", + "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/enc/encdb.so", + "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/enc/trans/transdb.so", + "/snap/ruby/317/lib/ruby/3.2.0/x86_64-linux/rbconfig.rb", + "/snap/ruby/317/lib/ruby/3.2.0/rubygems/compatibility.rb"] + +Aliased as <tt>$"</tt>. + +== Debugging + +=== <tt>$FILENAME</tt> + +The value returned by method ARGF.filename. + +=== <tt>$DEBUG</tt> + +Initially +true+ if command-line option <tt>-d</tt> or <tt>--debug</tt> is given, +otherwise initially +false+; +may be set to either value in the running program. + +When +true+, prints each raised exception to <tt>$stderr</tt>. + +Aliased as <tt>$-d</tt>. + +=== <tt>$VERBOSE</tt> + +Initially +true+ if command-line option <tt>-v</tt> or <tt>-w</tt> is given, +otherwise initially +false+; +may be set to either value, or to +nil+, in the running program. + +When +true+, enables Ruby warnings. + +When +nil+, disables warnings, including those from Kernel#warn. + +Aliased as <tt>$-v</tt> and <tt>$-w</tt>. + +== Other Variables + +=== <tt>$-a</tt> + +Whether command-line option <tt>-a</tt> was given; read-only. + +=== <tt>$-i</tt> + +Contains the extension given with command-line option <tt>-i</tt>, +or +nil+ if none. + +An alias of ARGF.inplace_mode. + +=== <tt>$-l</tt> + +Whether command-line option <tt>-l</tt> was set; read-only. + +=== <tt>$-p</tt> + +Whether command-line option <tt>-p</tt> was given; read-only. + +== Deprecated + +=== <tt>$=</tt> + +=== <tt>$,</tt> + += Pre-Defined Global Constants + += Streams + +=== <tt>STDIN</tt> + +The standard input stream (the default value for <tt>$stdin</tt>): + + STDIN # => #<IO:<STDIN>> + +=== <tt>STDOUT</tt> + +The standard output stream (the default value for <tt>$stdout</tt>): + + STDOUT # => #<IO:<STDOUT>> + +=== <tt>STDERR</tt> + +The standard error stream (the default value for <tt>$stderr</tt>): + + STDERR # => #<IO:<STDERR>> + +== Environment + +=== ENV + +A hash of the contains current environment variables names and values: + + ENV.take(5) + # => + [["COLORTERM", "truecolor"], + ["DBUS_SESSION_BUS_ADDRESS", "unix:path=/run/user/1000/bus"], + ["DESKTOP_SESSION", "ubuntu"], + ["DISPLAY", ":0"], + ["GDMSESSION", "ubuntu"]] + +=== ARGF + +The virtual concatenation of the files given on the command line, or from +<tt>$stdin</tt> if no files were given, <tt>"-"</tt> is given, or after +all files have been read. + +=== <tt>ARGV</tt> + +An array of the given command-line arguments. + +=== <tt>TOPLEVEL_BINDING</tt> + +The Binding of the top level scope: + + TOPLEVEL_BINDING # => #<Binding:0x00007f58da0da7c0> + +=== <tt>RUBY_VERSION</tt> + +The Ruby version: + + RUBY_VERSION # => "3.2.2" + +=== <tt>RUBY_RELEASE_DATE</tt> + +The release date string: + + RUBY_RELEASE_DATE # => "2023-03-30" + +=== <tt>RUBY_PLATFORM</tt> + +The platform identifier: + + RUBY_PLATFORM # => "x86_64-linux" + +=== <tt>RUBY_PATCHLEVEL</tt> + +The integer patch level for this Ruby: + + RUBY_PATCHLEVEL # => 53 + +For a development build the patch level will be -1. + +=== <tt>RUBY_REVISION</tt> + +The git commit hash for this Ruby: + + RUBY_REVISION # => "e51014f9c05aa65cbf203442d37fef7c12390015" + +=== <tt>RUBY_COPYRIGHT</tt> + +The copyright string: + + RUBY_COPYRIGHT + # => "ruby - Copyright (C) 1993-2023 Yukihiro Matsumoto" + +=== <tt>RUBY_ENGINE</tt> + +The name of the Ruby implementation: + + RUBY_ENGINE # => "ruby" + +=== <tt>RUBY_ENGINE_VERSION</tt> + +The version of the Ruby implementation: + + RUBY_ENGINE_VERSION # => "3.2.2" + +=== <tt>RUBY_DESCRIPTION</tt> + +The description of the Ruby implementation: + + RUBY_DESCRIPTION + # => "ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x86_64-linux]" + +== Embedded \Data + +=== <tt>DATA</tt> + +Defined if and only if the program has this line: + + __END__ + +When defined, <tt>DATA</tt> is a File object +containing the lines following the <tt>__END__</tt>, +positioned at the first of those lines: + + p DATA + DATA.each_line { |line| p line } + __END__ + Foo + Bar + Baz + +Output: + + #<File:t.rb> + "Foo\n" + "Bar\n" + "Baz\n" |