diff --git a/doc/globals.md b/doc/globals.md new file mode 100644 index 0000000000..db23831a10 --- /dev/null +++ b/doc/globals.md @@ -0,0 +1,572 @@ +# 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' +``` + +## Summary + +### Exceptions + +| Variable | English | Contains | +|-------------|--------------------------|----------------------------------------------------| +| $! | $ERROR_INFO | Exception object; set by Kernel#raise. | +| $@ | $ERROR_POSITION | Array of backtrace positions; set by Kernel#raise. | + +### Pattern Matching + +| Variable | English | Contains | +|-------------|----------------------------|--------------------------------------------------| +| $~ | $LAST_MATCH_INFO | MatchData object; set by matcher method. | +| $& | $MATCH | Matched substring; set by matcher method. | +| $` | $PRE_MATCH | Substring left of match; set by matcher method. | +| $' | $POST_MATCH | Substring right of match; set by matcher method. | +| $+ | $LAST_PAREN_MATCH | Last group matched; set by matcher method. | +| $1 | | First group matched; set by matcher method. | +| $2 | | Second group matched; set by matcher method. | +| $n | | nth group matched; set by matcher method. | + +### Separators + +| Variable | English | Contains | +|----------------------|-----------------------------------|--------------------------------------------------| +| $/ | $INPUT_RECORD_SEPARATOR | Input record separator; initially newline. | +| $\\\\\\\\ | $OUTPUT_RECORD_SEPARATOR | Output record separator; initially nil. | + +### Streams + +| Variable | English | Contains | +|------------------|-------------------------------------------|-----------------------------------------------------------| +| $stdin | | Standard input stream; initially STDIN. | +| $stdout | | Standard input stream; initially STDIOUT. | +| $stderr | | Standard input stream; initially STDERR. | +| $< | $DEFAULT_INPUT | Default standard input; ARGF or $stdin. | +| $> | $DEFAULT_OUTPUT | Default standard output; initially $stdout. | +| $. | $INPUT_LINE_NUMBER, $NR | Input position of most recently read stream. | +| $_ | $LAST_READ_LINE | String from most recently read stream. | + +### Processes + +| Variable | English | Contains | +|------------------------------------------------|-------------------------------------|--------------------------------------------------------| +| $0 | | Initially, the name of the executing program. | +| $* | $ARGV | Points to the ARGV array. | +| $$ | $PROCESS_ID, $PID | Process ID of the current process. | +| $? | $CHILD_STATUS | Process::Status of most recently exited child process. | +| $LOAD_PATH, $:, $-I | | Array of paths to be searched. | +| $LOADED_FEATURES, $" | | Array of paths to loaded files. | + +### Debugging + +| Variable | English | Contains | +|--------------------|---------|----------------------------------------------------------------------| +| $FILENAME | | The value returned by method ARGF.filename. | +| $DEBUG | | Initially, whether option -d or --debug was given. | +| $VERBOSE | | Initially, whether option -V or -W was given. | + +### Other Variables + +| Variable | English | Contains | +|--------------|---------|-------------------------------------------------------| +| $-a | | Whether option -a was given. | +| $-i | | Extension given with command-line option -i. | +| $-l | | Whether option -l was given. | +| $-p | | Whether option -p was given. | + +## Exceptions + +### `$!` (\Exception) + +Contains the Exception object set by Kernel#raise: + +``` +begin + raise RuntimeError.new('Boo!') +rescue RuntimeError + p $! +end +``` + +Output: + +``` +# +``` + +English - `$ERROR_INFO` + +### `$@` (Backtrace) + +Same as `$!.backtrace`; +returns an array of backtrace positions: + +``` +begin + raise RuntimeError.new('Boo!') +rescue RuntimeError + pp $@.take(4) +end +``` + +Output: + +``` +["(irb):338:in `'", + "/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 - `$ERROR_POSITION`. + +## 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]. + +### `$~` (\MatchData) + +MatchData object created from the match; +thread-local and frame-local. + +English - `$LAST_MATCH_INFO`. + +### `$&` (Matched Substring) + +The matched string. + +English - `$MATCH`. + +### `` $` `` (Pre-Match Substring) +The string to the left of the match. + +English - `$PREMATCH`. + +### `$'` (Post-Match Substring) + +The string to the right of the match. + +English - `$POSTMATCH`. + +### `$+` (Last Matched Group) + +The last group matched. + +English - `$LAST_PAREN_MATCH`. + +### `$1`, `$2`, \Etc. (Matched Group) + +For `$_n_` the _nth_ group of the match. + +No \English. + +## Separators + +### `$/` (Input Record Separator) + +An input record separator, initially newline. + +English - `$INPUT_RECORD_SEPARATOR`, `$RS`. + +Aliased as `$-0`. + +### `$\\` (Output Record Separator) + +An output record separator, initially +nil+. + +English - `$OUTPUT_RECORD_SEPARATOR`, `$ORS`. + +## Streams + +### `$stdin` (Standard Input) + +The current standard input stream; initially: + +``` +$stdin # => #> +``` + +### `$stdout` (Standard Output) + +The current standard output stream; initially: + +``` +$stdout # => #> +``` + +### `$stderr` (Standard Error) + +The current standard error stream; initially: + +``` +$stderr # => #> +``` + +### `$<` (\ARGF or $stdin) + +Points to stream ARGF if not empty, else to stream $stdin; read-only. + +English - `$DEFAULT_INPUT`. + +### `$>` (Default Standard Output) + +An output stream, initially `$stdout`. + +English - `$DEFAULT_OUTPUT` + +### `$.` (Input Position) + +The input position (line number) in the most recently read stream. + +English - `$INPUT_LINE_NUMBER`, `$NR` + +### `$_` (Last Read Line) + +The line (string) from the most recently read stream. + +English - `$LAST_READ_LINE`. + +## Processes + +### `$0` + +Initially, contains the name of the script being executed; +may be reassigned. + +### `$*` (\ARGV) + +Points to ARGV. + +English - `$ARGV`. + +### `$$` (Process ID) + +The process ID of the current process. Same as Process.pid. + +English - `$PROCESS_ID`, `$PID`. + +### `$?` (Child Status) + +Initially +nil+, otherwise the Process::Status object +created for the most-recently exited child process; +thread-local. + +English - `$CHILD_STATUS`. + +### `$LOAD_PATH` (Load Path) + +Contains the array of paths to be searched +by Kernel#load and Kernel#require. + +Singleton method `$LOAD_PATH.resolve_feature_path(feature)` +returns: + +- `[:rb, _path_]`, where +path+ is the path to the Ruby file + to be loaded for the given +feature+. +- `[:so+ _path_]`, 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 `$:` and `$-I`. + +### `$LOADED_FEATURES` + +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 `$"`. + +## Debugging + +### `$FILENAME` + +The value returned by method ARGF.filename. + +### `$DEBUG` + +Initially +true+ if command-line option `-d` or `--debug` is given, +otherwise initially +false+; +may be set to either value in the running program. + +When +true+, prints each raised exception to `$stderr`. + +Aliased as `$-d`. + +### `$VERBOSE` + +Initially +true+ if command-line option `-v` or `-w` 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 `$-v` and `$-w`. + +## Other Variables + +### `$-a` + +Whether command-line option `-a` was given; read-only. + +### `$-i` + +Contains the extension given with command-line option `-i`, +or +nil+ if none. + +An alias of ARGF.inplace_mode. + +### `$-l` + +Whether command-line option `-l` was set; read-only. + +### `$-p` + +Whether command-line option `-p` was given; read-only. + +## Deprecated + +### `$=` + +### `$,` + +### `$;` + +# Pre-Defined Global Constants + +## Summary + +### Streams + +| Constant | Contains | +|-----------------|-------------------------| +| STDIN | Standard input stream. | +| STDOUT | Standard output stream. | +| STDERR | Standard error stream. | + +### Environment + +| Constant | Contains | +|------------------------------|--------------------------------------------------------------------------------------| +| ENV | Hash of current environment variable names and values. | +| ARGF | String concatenation of files given on the command line, or $stdin if none. | +| ARGV | Array of the given command-line arguments. | +| TOPLEVEL_BINDING | Binding of the top level scope. | +| RUBY_VERSION | String Ruby version. | +| RUBY_RELEASE_DATE | String Ruby release date. | +| RUBY_PLATFORM | String Ruby platform. | +| RUBY_PATCH_LEVEL | String Ruby patch level. | +| RUBY_REVISION | String Ruby revision. | +| RUBY_COPYRIGHT | String Ruby copyright. | +| RUBY_ENGINE | String Ruby engine. | +| RUBY_ENGINE_VERSION | String Ruby engine version. | +| RUBY_DESCRIPTION | String Ruby description. | + +### Embedded Data + +| Constant | Contains | +|---------------|---------------------------------------------------------------------------| +| DATA | File containing embedded data (lines following __END__, if any). | + +## Streams + +### `STDIN` + +The standard input stream (the default value for `$stdin`): + +``` +STDIN # => #> +``` + +### `STDOUT` + +The standard output stream (the default value for `$stdout`): + +``` +STDOUT # => #> +``` + +### `STDERR` + +The standard error stream (the default value for `$stderr`): + +``` +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 +`$stdin` if no files were given, `"-"` is given, or after +all files have been read. + +### `ARGV` + +An array of the given command-line arguments. + +### `TOPLEVEL_BINDING` + +The Binding of the top level scope: + +``` +TOPLEVEL_BINDING # => # +``` + +### `RUBY_VERSION` + +The Ruby version: + +``` +RUBY_VERSION # => "3.2.2" +``` + +### `RUBY_RELEASE_DATE` + +The release date string: + +``` +RUBY_RELEASE_DATE # => "2023-03-30" +``` + +### `RUBY_PLATFORM` + +The platform identifier: + +``` +RUBY_PLATFORM # => "x86_64-linux" +``` + +### `RUBY_PATCHLEVEL` + +The integer patch level for this Ruby: + +``` +RUBY_PATCHLEVEL # => 53 +``` + +For a development build the patch level will be -1. + +### `RUBY_REVISION` + +The git commit hash for this Ruby: + +``` +RUBY_REVISION # => "e51014f9c05aa65cbf203442d37fef7c12390015" +``` + +### `RUBY_COPYRIGHT` + +The copyright string: + +``` +RUBY_COPYRIGHT +# => "ruby - Copyright (C) 1993-2023 Yukihiro Matsumoto" +``` + +### `RUBY_ENGINE` + +The name of the Ruby implementation: + +``` +RUBY_ENGINE # => "ruby" +``` + +### `RUBY_ENGINE_VERSION` + +The version of the Ruby implementation: + +``` +RUBY_ENGINE_VERSION # => "3.2.2" +``` + +### `RUBY_DESCRIPTION` + +The description of the Ruby implementation: + +``` +RUBY_DESCRIPTION +# => "ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x86_64-linux]" +``` + +## Embedded \Data + +### `DATA` + +Defined if and only if the program has this line: + +``` +__END__ +``` + +When defined, `DATA` is a File object +containing the lines following the `__END__`, +positioned at the first of those lines: + +``` +p DATA +DATA.each_line { |line| p line } +__END__ +Foo +Bar +Baz +``` + +Output: + +``` +# +"Foo\n" +"Bar\n" +"Baz\n" +``` diff --git a/doc/globals.rdoc b/doc/globals.rdoc deleted file mode 100644 index 9466005be7..0000000000 --- a/doc/globals.rdoc +++ /dev/null @@ -1,416 +0,0 @@ -= 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 - -=== $! (\Exception) - -Contains the Exception object set by Kernel#raise: - - begin - raise RuntimeError.new('Boo!') - rescue RuntimeError - p $! - end - -Output: - - # - -English - $ERROR_INFO - -=== $@ (Backtrace) - -Same as $!.backtrace; -returns an array of backtrace positions: - - begin - raise RuntimeError.new('Boo!') - rescue RuntimeError - pp $@.take(4) - end - -Output: - - ["(irb):338:in `'", - "/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 - $ERROR_POSITION. - -== 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]. - -=== $~ (\MatchData) - -MatchData object created from the match; -thread-local and frame-local. - -English - $LAST_MATCH_INFO. - -=== $& (Matched Substring) - -The matched string. - -English - $MATCH. - -=== $` (Pre-Match Substring) - -The string to the left of the match. - -English - $PREMATCH. - -=== $' (Post-Match Substring) - -The string to the right of the match. - -English - $POSTMATCH. - -=== $+ (Last Matched Group) - -The last group matched. - -English - $LAST_PAREN_MATCH. - -=== $1, $2, \Etc. (Matched Group) - -For $_n_ the _nth_ group of the match. - -No \English. - -== Separators - -=== $/ (Input Record Separator) - -An input record separator, initially newline. - -English - $INPUT_RECORD_SEPARATOR, $RS. - -Aliased as $-0. - -=== $\\ (Output Record Separator) - -An output record separator, initially +nil+. - -English - $OUTPUT_RECORD_SEPARATOR, $ORS. - -== Streams - -=== $stdin (Standard Input) - -The current standard input stream; initially: - - $stdin # => #> - -=== $stdout (Standard Output) - -The current standard output stream; initially: - - $stdout # => #> - -=== $stderr (Standard Error) - -The current standard error stream; initially: - - $stderr # => #> - -=== $< (\ARGF or $stdin) - -Points to stream ARGF if not empty, else to stream $stdin; read-only. - -English - $DEFAULT_INPUT. - -=== $> (Default Standard Output) - -An output stream, initially $stdout. - -English - $DEFAULT_OUTPUT - -=== $. (Input Position) - -The input position (line number) in the most recently read stream. - -English - $INPUT_LINE_NUMBER, $NR - -=== $_ (Last Read Line) - -The line (string) from the most recently read stream. - -English - $LAST_READ_LINE. - -== Processes - -=== $0 - -Initially, contains the name of the script being executed; -may be reassigned. - -=== $* (\ARGV) - -Points to ARGV. - -English - $ARGV. - -=== $$ (Process ID) - -The process ID of the current process. Same as Process.pid. - -English - $PROCESS_ID, $PID. - -=== $? (Child Status) - -Initially +nil+, otherwise the Process::Status object -created for the most-recently exited child process; -thread-local. - -English - $CHILD_STATUS. - -=== $LOAD_PATH (Load Path) - -Contains the array of paths to be searched -by Kernel#load and Kernel#require. - -Singleton method $LOAD_PATH.resolve_feature_path(feature) -returns: - -- [:rb, _path_], where +path+ is the path to the Ruby file - to be loaded for the given +feature+. -- [:so+ _path_], 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 $: and $-I. - -=== $LOADED_FEATURES - -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 $". - -== Debugging - -=== $FILENAME - -The value returned by method ARGF.filename. - -=== $DEBUG - -Initially +true+ if command-line option -d or --debug is given, -otherwise initially +false+; -may be set to either value in the running program. - -When +true+, prints each raised exception to $stderr. - -Aliased as $-d. - -=== $VERBOSE - -Initially +true+ if command-line option -v or -w 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 $-v and $-w. - -== Other Variables - -=== $-a - -Whether command-line option -a was given; read-only. - -=== $-i - -Contains the extension given with command-line option -i, -or +nil+ if none. - -An alias of ARGF.inplace_mode. - -=== $-l - -Whether command-line option -l was set; read-only. - -=== $-p - -Whether command-line option -p was given; read-only. - -== Deprecated - -=== $= - -=== $, - -=== $; - -= Pre-Defined Global Constants - -= Streams - -=== STDIN - -The standard input stream (the default value for $stdin): - - STDIN # => #> - -=== STDOUT - -The standard output stream (the default value for $stdout): - - STDOUT # => #> - -=== STDERR - -The standard error stream (the default value for $stderr): - - 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 -$stdin if no files were given, "-" is given, or after -all files have been read. - -=== ARGV - -An array of the given command-line arguments. - -=== TOPLEVEL_BINDING - -The Binding of the top level scope: - - TOPLEVEL_BINDING # => # - -=== RUBY_VERSION - -The Ruby version: - - RUBY_VERSION # => "3.2.2" - -=== RUBY_RELEASE_DATE - -The release date string: - - RUBY_RELEASE_DATE # => "2023-03-30" - -=== RUBY_PLATFORM - -The platform identifier: - - RUBY_PLATFORM # => "x86_64-linux" - -=== RUBY_PATCHLEVEL - -The integer patch level for this Ruby: - - RUBY_PATCHLEVEL # => 53 - -For a development build the patch level will be -1. - -=== RUBY_REVISION - -The git commit hash for this Ruby: - - RUBY_REVISION # => "e51014f9c05aa65cbf203442d37fef7c12390015" - -=== RUBY_COPYRIGHT - -The copyright string: - - RUBY_COPYRIGHT - # => "ruby - Copyright (C) 1993-2023 Yukihiro Matsumoto" - -=== RUBY_ENGINE - -The name of the Ruby implementation: - - RUBY_ENGINE # => "ruby" - -=== RUBY_ENGINE_VERSION - -The version of the Ruby implementation: - - RUBY_ENGINE_VERSION # => "3.2.2" - -=== RUBY_DESCRIPTION - -The description of the Ruby implementation: - - RUBY_DESCRIPTION - # => "ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x86_64-linux]" - -== Embedded \Data - -=== DATA - -Defined if and only if the program has this line: - - __END__ - -When defined, DATA is a File object -containing the lines following the __END__, -positioned at the first of those lines: - - p DATA - DATA.each_line { |line| p line } - __END__ - Foo - Bar - Baz - -Output: - - # - "Foo\n" - "Bar\n" - "Baz\n" diff --git a/doc/syntax/assignment.rdoc b/doc/syntax/assignment.rdoc index f45f5bc0ea..68d4ae97be 100644 --- a/doc/syntax/assignment.rdoc +++ b/doc/syntax/assignment.rdoc @@ -279,7 +279,7 @@ An uninitialized global variable has a value of +nil+. Ruby has some special globals that behave differently depending on context such as the regular expression match variables or that have a side-effect when -assigned to. See the {global variables documentation}[rdoc-ref:globals.rdoc] +assigned to. See the {global variables documentation}[rdoc-ref:globals.md] for details. == Assignment Methods diff --git a/load.c b/load.c index 017c236483..b85a247c18 100644 --- a/load.c +++ b/load.c @@ -1318,7 +1318,7 @@ no_feature_p(vm_ns_t *vm_ns, const char *feature, const char *ext, int rb, int e return 0; } -// Documented in doc/globals.rdoc +// Documented in doc/globals.md VALUE rb_resolve_feature_path(VALUE klass, VALUE fname) {