path: root/doc/globals.rdoc

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