[DOC] Globals doc (#8445)

This commit is contained in:
Burdette Lamar 2023-09-15 12:59:48 -05:00 committed by GitHub
parent c423d6e0e4
commit e50b7bf784
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -1,69 +1,419 @@
# -*- mode: rdoc; coding: utf-8; fill-column: 74; -*-
== Pre-Defined Global Variables
== Pre-defined global variables
Some of the pre-defined global variables have synonyms
that are available via module Engish.
For each of those, the \English synonym is given.
$!:: 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.
To use the module:
== Pre-defined global constants
require 'English'
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.
=== 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.
==== <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>>
=== Enviroment
==== <tt>ENV</tt>
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"]]
==== <tt>ARGF</tt>
The virtual concatenation of the files given on the command line,
or from <tt>$stdin</tt> if no files were given.
==== <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"