[ruby/irb] [DOC] RDoc for module IRB

(https://github.com/ruby/irb/pull/738) [DOC] RDoc for module IRB https://github.com/ruby/irb/commit/f3a0626298
2023-12-12 04:34:34 -06:00 · 2023-12-12 04:34:34 -06:00 · 35990cb38c
--- a/doc/irb/indexes.rdoc
+++ b/doc/irb/indexes.rdoc
@ -0,0 +1,190 @@
+== Indexes
+
+=== Index of Command-Line Options
+
+These are the \IRB command-line options, with links to explanatory text:
+
+- <tt>-d</tt>: Set <tt>$DEBUG</tt> and {$VERBOSE}[rdoc-ref:IRB@Verbosity]
+  to +true+.
+- <tt>-E _ex_[:_in_]</tt>: Set initial external (ex) and internal (in)
+  {encodings}[rdoc-ref:IRB@Encodings] (same as <tt>ruby -E></tt>).
+- <tt>-f</tt>: Don't initialize from {configuration file}[rdoc-ref:IRB@Configuration+File].
+- <tt>-I _dirpath_</tt>: Specify {$LOAD_PATH directory}[rdoc-ref:IRB@Load+Modules]
+  (same as <tt>ruby -I</tt>).
+- <tt>-r _load-module_</tt>: Require {load-module}[rdoc-ref:IRB@Load+Modules]
+  (same as <tt>ruby -r</tt>).
+- <tt>-U</tt>: Set external and internal {encodings}[rdoc-ref:IRB@Encodings] to UTF-8.
+- <tt>-w</tt>: Suppress {warnings}[rdoc-ref:IRB@Warnings] (same as <tt>ruby -w</tt>).
+- <tt>-W[_level_]</tt>: Set {warning level}[rdoc-ref:IRB@Warnings];
+  0=silence, 1=medium, 2=verbose (same as <tt>ruby -W</tt>).
+- <tt>--autocomplete</tt>: Use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
+- <tt>--back-trace-limit _n_</tt>: Set a {backtrace limit}[rdoc-ref:IRB@Tracer];
+  display at most the top +n+ and bottom +n+ entries.
+- <tt>--colorize</tt>: Use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
+  for input and output.
+- <tt>--context-mode _n_</tt>: Select method to create Binding object
+  for new {workspace}[rdoc-ref:IRB@Commands]; +n+ in range <tt>0..4</tt>.
+- <tt>--echo</tt>: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- <tt>--extra-doc-dir _dirpath_</tt>:
+  Add a {documentation directory}[rdoc-ref:IRB@RI+Documentation+Directories]
+  for the documentation dialog.
+- <tt>--inf-ruby-mode</tt>: Set prompt mode to {:INF_RUBY}[rdoc-ref:IRB@Pre-Defined+Prompts]
+  (appropriate for +inf-ruby-mode+ on Emacs);
+  suppresses --multiline and --singleline.
+- <tt>--inspect</tt>: Use method +inspect+ for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- <tt>--multiline</tt>: Use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- <tt>--noautocomplete</tt>: Don't use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
+- <tt>--nocolorize</tt>: Don't use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
+  for input and output.
+- <tt>--noecho</tt>: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- <tt>--noecho-on-assignment</tt>: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  result on assignment.
+- <tt>--noinspect</tt>: Don't se method +inspect+ for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- <tt>--nomultiline</tt>: Don't use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- <tt>--noprompt</tt>: Don't print {prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats].
+- <tt>--noscript</tt>:  Treat the first command-line argument as a normal
+  {command-line argument}[rdoc-ref:IRB@Initialization+Script],
+  and include it in +ARGV+.
+- <tt>--nosingleline</tt>: Don't use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- <tt>--noverbose</tt>Don't print {verbose}[rdoc-ref:IRB@Verbosity] details.
+- <tt>--prompt _mode_</tt>, <tt>--prompt-mode _mode_</tt>:
+  Set {prompt and return formats}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  +mode+ may be a {pre-defined prompt}[rdoc-ref:IRB@Pre-Defined+Prompts]
+  or the name of a {custom prompt}[rdoc-ref:IRB@Custom+Prompts].
+- <tt>--script</tt>: Treat the first command-line argument as the path to an
+  {initialization script}[rdoc-ref:IRB@Initialization+Script],
+  and omit it from +ARGV+.
+- <tt>--simple-prompt</tt>, <tt>--sample-book-mode</tt>:
+  Set prompt mode to {:SIMPLE}[rdoc-ref:IRB@Pre-Defined+Prompts].
+- <tt>--singleline</tt>: Use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- <tt>--tracer</tt>: Use {Tracer}[rdoc-ref:IRB@Tracer] to print a stack trace for each input command.
+- <tt>--truncate-echo-on-assignment</tt>: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  truncated result on assignment.
+- <tt>--verbose</tt>Print {verbose}[rdoc-ref:IRB@Verbosity] details.
+- <tt>-v</tt>, <tt>--version</tt>: Print the {IRB version}[rdoc-ref:IRB@Version].
+- <tt>-h</tt>, <tt>--help</tt>: Print the {IRB help text}[rdoc-ref:IRB@Help].
+- <tt>--</tt>: Separate options from {arguments}[rdoc-ref:IRB@Command-Line+Arguments]
+  on the command-line.
+
+=== Index of \IRB.conf Entries
+
+These are the keys for hash \IRB.conf entries, with links to explanatory text;
+for each entry that is pre-defined, the initial value is given:
+
+- <tt>:AP_NAME</tt>: \IRB {application name}[rdoc-ref:IRB@Application+Name];
+  initial value: <tt>'irb'</tt>.
+- <tt>:AT_EXIT</tt>: Array of hooks to call
+  {at exit}[rdoc-ref:IRB@IRB];
+  initial value: <tt>[]</tt>.
+- <tt>:AUTO_INDENT</tt>: Whether {automatic indentation}[rdoc-ref:IRB@Automatic+Indentation]
+  is enabled; initial value: +true+.
+- <tt>:BACK_TRACE_LIMIT</tt>: Sets the {back trace limit}[rdoc-ref:IRB@Tracer];
+  initial value: +16+.
+- <tt>:COMMAND_ALIASES</tt>: Defines input {command aliases}[rdoc-ref:IRB@Command+Aliases];
+  initial value:
+
+    {
+      "$": :show_source,
+      "@": :whereami,
+    }
+
+- <tt>:CONTEXT_MODE</tt>: Sets the {context mode}[rdoc-ref:IRB@Context+Mode],
+  the type of binding to be used when evaluating statements;
+  initial value: +4+.
+- <tt>:ECHO</tt>: Whether to print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values;
+  initial value: +nil+, which would set +conf.echo+ to +true+.
+- <tt>:ECHO_ON_ASSIGNMENT</tt>: Whether to print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values on assignment;
+  initial value: +nil+, which would set +conf.echo_on_assignment+ to +:truncate+.
+- <tt>:EVAL_HISTORY</tt>: How much {evaluation history}[rdoc-ref:IRB@Evaluation+History]
+  is to be stored; initial value: +nil+.
+- <tt>:EXTRA_DOC_DIRS</tt>: \Array of
+  {RI documentation directories}[rdoc-ref:IRB@RI+Documentation+Directories]
+  to be parsed for the documentation dialog;
+  initial value: <tt>[]</tt>.
+- <tt>:IGNORE_EOF</tt>: Whether to ignore {end-of-file}[rdoc-ref:IRB@End-of-File];
+  initial value: +false+.
+- <tt>:IGNORE_SIGINT</tt>: Whether to ignore {SIGINT}[rdoc-ref:IRB@SIGINT];
+  initial value: +true+.
+- <tt>:INSPECT_MODE</tt>: Whether to use method +inspect+ for printing
+  ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) return values;
+  initial value: +true+.
+- <tt>:IRB_LIB_PATH</tt>: The path to the {IRB library directory}[rdoc-ref:IRB@IRB+Library+Directory]; initial value:
+  <tt>"<i>RUBY_DIR</i>/lib/ruby/gems/<i>RUBY_VER_NUM</i>/gems/irb-<i>IRB_VER_NUM</i>/lib/irb"</tt>,
+  where:
+
+  - <i>RUBY_DIR</i> is the Ruby installation dirpath.
+  - <i>RUBY_VER_NUM</i> is the Ruby version number.
+  - <i>IRB_VER_NUM</i> is the \IRB version number.
+
+- <tt>:IRB_NAME</tt>: {IRB name}[rdoc-ref:IRB@IRB+Name];
+  initial value: <tt>'irb'</tt>.
+- <tt>:IRB_RC</tt>: {Configuration monitor}[rdoc-ref:IRB@Configuration+Monitor];
+  initial value: +nil+.
+- <tt>:LC_MESSAGES</tt>: {Locale}[rdoc-ref:IRB@Locale];
+  initial value: IRB::Locale object.
+- <tt>:LOAD_MODULES</tt>: deprecated.
+- <tt>:MAIN_CONTEXT</tt>: The {context}[rdoc-ref:IRB@Session+Context] for the main \IRB session;
+  initial value: IRB::Context object.
+- <tt>:MEASURE</tt>: Whether to
+  {measure performance}[rdoc-ref:IRB@Performance+Measurement];
+  initial value: +false+.
+- <tt>:MEASURE_CALLBACKS</tt>: Callback methods for
+  {performance measurement}[rdoc-ref:IRB@Performance+Measurement];
+  initial value: <tt>[]</tt>.
+- <tt>:MEASURE_PROC</tt>: Procs for
+  {performance measurement}[rdoc-ref:IRB@Performance+Measurement];
+  initial value:
+
+    {
+      :TIME=>#<Proc:0x0000556e271c6598 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:106>,
+      :STACKPROF=>#<Proc:0x0000556e271c6548 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:116>
+    }
+
+- <tt>:PROMPT</tt>: \Hash of {defined prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  initial value:
+
+    {
+      :NULL=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n"},
+      :DEFAULT=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>"%N(%m):%03n%l ", :PROMPT_C=>"%N(%m):%03n* ", :RETURN=>"=> %s\n"},
+      :CLASSIC=>{:PROMPT_I=>"%N(%m):%03n:%i> ", :PROMPT_S=>"%N(%m):%03n:%i%l ", :PROMPT_C=>"%N(%m):%03n:%i* ", :RETURN=>"%s\n"},
+      :SIMPLE=>{:PROMPT_I=>">> ", :PROMPT_S=>"%l> ", :PROMPT_C=>"?> ", :RETURN=>"=> %s\n"},
+      :INF_RUBY=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n", :AUTO_INDENT=>true},
+      :XMP=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"    ==>%s\n"}
+    }
+
+- <tt>:PROMPT_MODE</tt>: Name of {current prompt}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  initial value: +:DEFAULT+.
+- <tt>:RC</tt>: Whether a {configuration file}[rdoc-ref:IRB@Configuration+File]
+  was found and interpreted;
+  initial value: +true+ if a configuration file was found, +false+ otherwise.
+- <tt>:RC_NAME_GENERATOR</tt>: \Proc to generate paths of potential
+  {configuration files}[rdoc-ref:IRB@Configuration+File];
+  initial value: <tt>=> #<Proc:0x000055f9bebfed80 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:401></tt>.
+- <tt>:SAVE_HISTORY</tt>: Number of commands to save in
+  {input command history}[rdoc-ref:IRB@Input+Command+History];
+  initial value: +1000+.
+- <tt>:SINGLE_IRB</tt>: Whether command-line option <tt>--single-irb</tt> was given;
+  initial value: +true+ if the option was given, +false+ otherwise.
+  See {Single-IRB Mode}[rdoc-ref:IRB@Single-IRB+Mode].
+- <tt>:USE_AUTOCOMPLETE</tt>: Whether to use
+  {automatic completion}[rdoc-ref:IRB@Automatic+Completion];
+  initial value: +true+.
+- <tt>:USE_COLORIZE</tt>: Whether to use
+  {color highlighting}[rdoc-ref:IRB@Color+Highlighting];
+  initial value: +true+.
+- <tt>:USE_LOADER</tt>: Whether to use the
+  {IRB loader}[rdoc-ref:IRB@IRB+Loader] for +require+ and +load+;
+  initial value: +false+.
+- <tt>:USE_TRACER</tt>: Whether to use the
+  {IRB tracer}[rdoc-ref:IRB@Tracer];
+  initial value: +false+.
+- <tt>:VERBOSE</tt>: Whether to print {verbose output}[rdoc-ref:IRB@Verbosity];
+  initial value: +nil+.
+- <tt>:__MAIN__</tt>: The main \IRB object;
+  initial value: +main+.
--- a/lib/irb.rb
+++ b/lib/irb.rb
--- a/lib/irb/context.rb
+++ b/lib/irb/context.rb
@ -264,15 +264,15 @@ module IRB
    attr_reader :prompt_mode
    # Standard IRB prompt.
    #
-    # See IRB@Customizing+the+IRB+Prompt for more information.
+    # See {Custom Prompts}[rdoc-ref:IRB@Custom+Prompts] for more information.
    attr_accessor :prompt_i
    # IRB prompt for continuated strings.
    #
-    # See IRB@Customizing+the+IRB+Prompt for more information.
+    # See {Custom Prompts}[rdoc-ref:IRB@Custom+Prompts] for more information.
    attr_accessor :prompt_s
    # IRB prompt for continuated statement. (e.g. immediately after an +if+)
    #
-    # See IRB@Customizing+the+IRB+Prompt for more information.
+    # See {Custom Prompts}[rdoc-ref:IRB@Custom+Prompts] for more information.
    attr_accessor :prompt_c

    # TODO: Remove this when developing v2.0
@ -394,8 +394,6 @@ module IRB
    # The default value is 16.
    #
    # Can also be set using the +--back-trace-limit+ command line option.
-    #
-    # See IRB@Command+line+options for more command line options.
    attr_accessor :back_trace_limit

    # User-defined IRB command aliases
@ -463,7 +461,7 @@ module IRB

    # Sets the +mode+ of the prompt in this context.
    #
-    # See IRB@Customizing+the+IRB+Prompt for more information.
+    # See {Custom Prompts}[rdoc-ref:IRB@Custom+Prompts] for more information.
    def prompt_mode=(mode)
      @prompt_mode = mode
      pconf = IRB.conf[:PROMPT][mode]
@ -501,8 +499,6 @@ module IRB
    #
    # Can also be set using the +--inspect+ and +--noinspect+ command line
    # options.
-    #
-    # See IRB@Command+line+options for more command line options.
    def inspect_mode=(opt)

      if i = Inspector::INSPECTORS[opt]
--- a/lib/irb/help.rb
+++ b/lib/irb/help.rb
@ -5,7 +5,7 @@
 #

 module IRB
-  # Outputs the irb help message, see IRB@Command+line+options.
+  # Outputs the irb help message, see IRB@Command-Line+Options.
  def IRB.print_usage
    lc = IRB.conf[:LC_MESSAGES]
    path = lc.find("irb/help-message")
--- a/lib/irb/xmp.rb
+++ b/lib/irb/xmp.rb
@ -44,8 +44,8 @@ class XMP
  # The top-level binding or, optional +bind+ parameter will be used when
  # creating the workspace. See WorkSpace.new for more information.
  #
-  # This uses the +:XMP+ prompt mode, see IRB@Customizing+the+IRB+Prompt for
-  # full detail.
+  # This uses the +:XMP+ prompt mode.
+  # See {Custom Prompts}[rdoc-ref:IRB@Custom+Prompts] for more information.
  def initialize(bind = nil)
    IRB.init_config(nil)