ruby-changes:26464
From: zzak <ko1@a...>
Date: Fri, 21 Dec 2012 14:46:11 +0900 (JST)
Subject: [ruby-changes:26464] zzak:r38515 (trunk): * lib/irb.rb, lib/irb/*: Documentation for IRB
zzak 2012-12-21 14:45:50 +0900 (Fri, 21 Dec 2012) New Revision: 38515 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38515 Log: * lib/irb.rb, lib/irb/*: Documentation for IRB Modified files: trunk/ChangeLog trunk/lib/irb/completion.rb trunk/lib/irb/context.rb trunk/lib/irb/ext/change-ws.rb trunk/lib/irb/ext/history.rb trunk/lib/irb/ext/loader.rb trunk/lib/irb/ext/multi-irb.rb trunk/lib/irb/ext/save-history.rb trunk/lib/irb/ext/tracer.rb trunk/lib/irb/ext/use-loader.rb trunk/lib/irb/ext/workspaces.rb trunk/lib/irb/extend-command.rb trunk/lib/irb/frame.rb trunk/lib/irb/help.rb trunk/lib/irb/input-method.rb trunk/lib/irb/inspector.rb trunk/lib/irb/notifier.rb trunk/lib/irb/output-method.rb trunk/lib/irb/workspace.rb trunk/lib/irb/xmp.rb trunk/lib/irb.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 38514) +++ ChangeLog (revision 38515) @@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Fri Dec 21 14:45:00 2012 Zachary Scott <zachary@z...> + + * lib/irb.rb, lib/irb/*: Documentation for IRB + Fri Dec 21 11:31:02 2012 Eric Hodel <drbrain@s...> * lib/rake/*: Updated to rake 0.9.6 Index: lib/irb/input-method.rb =================================================================== --- lib/irb/input-method.rb (revision 38514) +++ lib/irb/input-method.rb (revision 38515) @@ -12,34 +12,39 @@ require 'irb/src_encoding' https://github.com/ruby/ruby/blob/trunk/lib/irb/input-method.rb#L12 require 'irb/magic-file' module IRB - # - # InputMethod - # StdioInputMethod - # FileInputMethod - # (ReadlineInputMethod) - # - STDIN_FILE_NAME = "(line)" + STDIN_FILE_NAME = "(line)" # :nodoc: class InputMethod @RCS_ID='-$Id$-' + # Creates a new input method object def initialize(file = STDIN_FILE_NAME) @file_name = file end + # The file name of this input method, usually given during initialization. attr_reader :file_name + # The irb prompt associated with this input method attr_accessor :prompt + # Reads the next line from this input method. + # + # See IO#gets for more information. def gets IRB.fail NotImplementedError, "gets" end public :gets + # Whether this input method is still readable when there is no more data to + # read. + # + # See IO#eof for more information. def readable_atfer_eof? false end end class StdioInputMethod < InputMethod + # Creates a new input method object def initialize super @line_no = 0 @@ -48,40 +53,67 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/input-method.rb#L53 @stdout = IO.open(STDOUT.to_i, 'w', :external_encoding => IRB.conf[:LC_MESSAGES].encoding, :internal_encoding => "-") end + # Reads the next line from this input method. + # + # See IO#gets for more information. def gets print @prompt line = @stdin.gets @line[@line_no += 1] = line end + # Whether the end of this input method has been reached, returns +true+ if + # there is no more data to read. + # + # See IO#eof? for more information. def eof? @stdin.eof? end + # Whether this input method is still readable when there is no more data to + # read. + # + # See IO#eof for more information. def readable_atfer_eof? true end + # Returns the current line number for #io. + # + # #line counts the number of times #gets is called. + # + # See IO#lineno for more information. def line(line_no) @line[line_no] end + # The external encoding for standard input. def encoding @stdin.external_encoding end end + # Use a File for IO with irb, see InputMethod class FileInputMethod < InputMethod + # Creates a new input method object def initialize(file) super @io = IRB::MagicFile.open(file) end + # The file name of this input method, usually given during initialization. attr_reader :file_name + # Whether the end of this input method has been reached, returns +true+ if + # there is no more data to read. + # + # See IO#eof? for more information. def eof? @io.eof? end + # Reads the next line from this input method. + # + # See IO#gets for more information. def gets print @prompt l = @io.gets @@ -89,6 +121,7 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/input-method.rb#L121 l end + # The external encoding for standard input. def encoding @io.external_encoding end @@ -98,6 +131,7 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/input-method.rb#L131 require "readline" class ReadlineInputMethod < InputMethod include Readline + # Creates a new input method object using Readline def initialize super @@ -109,6 +143,9 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/input-method.rb#L143 @stdout = IO.open(STDOUT.to_i, 'w', :external_encoding => IRB.conf[:LC_MESSAGES].encoding, :internal_encoding => "-") end + # Reads the next line from this input method. + # + # See IO#gets for more information. def gets Readline.input = @stdin Readline.output = @stdout @@ -121,18 +158,32 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/input-method.rb#L158 end end + # Whether the end of this input method has been reached, returns +true+ + # if there is no more data to read. + # + # See IO#eof? for more information. def eof? @eof end + # Whether this input method is still readable when there is no more data to + # read. + # + # See IO#eof for more information. def readable_atfer_eof? true end + # Returns the current line number for #io. + # + # #line counts the number of times #gets is called. + # + # See IO#lineno for more information. def line(line_no) @line[line_no] end + # The external encoding for standard input. def encoding @stdin.external_encoding end Index: lib/irb/output-method.rb =================================================================== --- lib/irb/output-method.rb (revision 38514) +++ lib/irb/output-method.rb (revision 38515) @@ -12,21 +12,25 @@ https://github.com/ruby/ruby/blob/trunk/lib/irb/output-method.rb#L12 require "e2mmap" module IRB - # OutputMethod - # StdioOutputMethod - + # An abstract output class for IO in irb. This is mainly used internally by + # IRB::Notifier. You can define your own output method to use with Irb.new, + # or Context.new class OutputMethod @RCS_ID='-$Id$-' + # Open this method to implement your own output method, raises a + # NotImplementedError if you don't define #print in your own class. def print(*opts) IRB.fail NotImplementedError, "print" end + # Prints the given +opts+, with a newline delimiter. def printn(*opts) print opts.join(" "), "\n" end - # extend printf + # Extends IO#printf to format the given +opts+ for Kernel#sprintf using + # #parse_printf_format def printf(format, *opts) if /(%*)%I/ =~ format format, opts = parse_printf_format(format, opts) @@ -34,16 +38,22 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/output-method.rb#L38 print sprintf(format, *opts) end - # % - # <flag> [#0- +] - # <minimum field width> (\*|\*[1-9][0-9]*\$|[1-9][0-9]*) - # <precision>.(\*|\*[1-9][0-9]*\$|[1-9][0-9]*|)? - # #<length modifier>(hh|h|l|ll|L|q|j|z|t) - # <conversion specifier>[diouxXeEfgGcsb%] + # Returns an array of the given +format+ and +opts+ to be used by + # Kernel#sprintf, if there was a successful Regexp match in the given + # +format+ from #printf + # + # % + # <flag> [#0- +] + # <minimum field width> (\*|\*[1-9][0-9]*\$|[1-9][0-9]*) + # <precision>.(\*|\*[1-9][0-9]*\$|[1-9][0-9]*|)? + # #<length modifier>(hh|h|l|ll|L|q|j|z|t) + # <conversion specifier>[diouxXeEfgGcsb%] def parse_printf_format(format, opts) return format, opts if $1.size % 2 == 1 end + # Calls #print on each element in the given +objs+, followed by a newline + # character. def puts(*objs) for obj in objs print(*obj) @@ -51,17 +61,27 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/output-method.rb#L61 end end + # Prints the given +objs+ calling Object#inspect on each. + # + # See #puts for more detail. def pp(*objs) puts(*objs.collect{|obj| obj.inspect}) end + # Prints the given +objs+ calling Object#inspect on each and appending the + # given +prefix+. + # + # See #puts for more detail. def ppx(prefix, *objs) puts(*objs.collect{|obj| prefix+obj.inspect}) end end + # A standard output printer class StdioOutputMethod<OutputMethod + # Prints the given +opts+ to standard output, see IO#print for more + # information. def print(*opts) STDOUT.print(*opts) end Index: lib/irb/notifier.rb =================================================================== --- lib/irb/notifier.rb (revision 38514) +++ lib/irb/notifier.rb (revision 38515) @@ -13,6 +13,7 @@ require "e2mmap" https://github.com/ruby/ruby/blob/trunk/lib/irb/notifier.rb#L13 require "irb/output-method" module IRB + # An output formatter used internally by the lexer. module Notifier extend Exception2MessageMapper def_exception :ErrUndefinedNotifier, @@ -20,59 +21,100 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/notifier.rb#L21 def_exception :ErrUnrecognizedLevel, "unrecognized notifier level: %s is specified" + # Define a new Notifier output source, returning a new CompositeNotifier + # with the given +prefix+ and +output_method+. + # + # The optional +prefix+ will be appended to all objects being inspected + # during output, using the given +output_method+ as the output source. If + # no +output_method+ is given, StdioOuputMethod will be used, and all + # expressions will be sent directly to STDOUT without any additional + # formatting. def def_notifier(prefix = "", output_method = StdioOutputMethod.new) CompositeNotifier.new(prefix, output_method) end module_function :def_notifier + # An abstract class, or superclass, for CompositeNotifier and + # LeveledNotifier to inherit. It provides several wrapper methods for the + # OutputMethod object used by the Notifier. class AbstractNotifier + # Creates a new Notifier object def initialize(prefix, base_notifier) @prefix = prefix @base_notifier = base_notifier end + # The +prefix+ for this Notifier, which is appended to all objects being + # inspected during output. attr_reader :prefix + # A wrapper method used to determine whether notifications are enabled. + # + # Defaults to +true+. def notify? true end + # See OutputMethod#print for more detail. def print(*opts) @base_notifier.print prefix, *opts if notify? end + # See OutputMethod#printn for more detail. def printn(*opts) @base_notifier.printn prefix, *opts if notify? end + # See OutputMethod#printf for more detail. def printf(format, *opts) @base_notifier.printf(prefix + format, *opts) if notify? end + # See OutputMethod#puts for more detail. def puts(*objs) if notify? @base_notifier.puts(*objs.collect{|obj| prefix + obj.to_s}) end end + # Same as #ppx, except it uses the #prefix given during object + # initialization. + # See OutputMethod#ppx for more detail. def pp(*objs) if notify? @base_notifier.ppx @prefix, *objs end end + # Same as #pp, except it concatenates the given +prefix+ with the #prefix + # given during object initialization. + # + # See OutputMethod#ppx for more detail. def ppx(prefix, *objs) if notify? @base_notifier.ppx @prefix+prefix, *objs end end + # Execute the given block if notifications are enabled. def exec_if yield(@base_notifier) if notify? end end + # A class that can be used to create a group of notifier objects with the + # intent of representing a leveled notification system for irb. + # + # This class will allow you to generate other notifiers, and assign them + # the appropriate level for output. + # + # The Notifier class provides a class-method Notifier.def_notifier to + # create a new composite notifier. Using the first composite notifier + # object you create, sibling notifiers can be initialized with + # #def_notifier. class CompositeNotifier<AbstractNotifier + # Create a new composite notifier object with the given +prefix+, and + # +base_notifier+ to use for output. def initialize(prefix, base_notifier) super @@ -80,17 +122,39 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/notifier.rb#L122 @level_notifier = D_NOMSG end + # List of notifiers in the group attr_reader :notifiers + # Creates a new LeveledNotifier in the composite #notifiers group. + # + # The given +prefix+ will be assigned to the notifier, and +level+ will + # be used as the index of the #notifiers Array. + # + # This method returns the newly created instance. def def_notifier(level, prefix = "") notifier = LeveledNotifier.new(self, level, prefix) @notifiers[level] = notifier notifier end + # Returns the leveled notifier for this object attr_reader :level_notifier alias level level_notifier + # Sets the leveled notifier for this object. + # + # When the given +value+ is an instance of AbstractNotifier, + # #level_notifier is set to the given object. + # + # When an Integer is given, #level_notifier is set to the notifier at the + # index +value+ in the #notifiers Array. + # + # If no notifier exists at the index +value+ in the #notifiers Array, an + # ErrUndefinedNotifier exception is raised. + # + # An ErrUnrecognizedLevel exception is raised if the given +value+ is not + # found in the existing #notifiers Array, or an instance of + # AbstractNotifier def level_notifier=(value) case value when AbstractNotifier @@ -107,38 +171,61 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/notifier.rb#L171 alias level= level_notifier= end + # A leveled notifier is comparable to the composite group from + # CompositeNotifier#notifiers. class LeveledNotifier<AbstractNotifier include Comparable + # Create a new leveled notifier with the given +base+, and +prefix+ to + # send to AbstractNotifier.new + # + # The given +level+ is used to compare other leveled notifiers in the + # CompositeNotifier group to determine whether or not to output + # notifications. def initialize(base, level, prefix) super(prefix, base) @level = level end + # The current level of this notifier object attr_reader :level + # Compares the level of this notifier object with the given +other+ + # notifier. + # + # See the Comparable module for more information. def <=>(other) @level <=> other.level end + # Whether to output messages to the output method, depending on the level + # of this notifier object. def notify? @base_notifier.level >= self end end + # NoMsgNotifier is a LeveledNotifier that's used as the default notifier + # when creating a new CompositeNotifier. + # + # This notifier is used as the +zero+ index, or level +0+, for + # CompositeNotifier#notifiers, and will not output messages of any sort. class NoMsgNotifier<LeveledNotifier + # Creates a new notifier that should not be used to output messages. def initialize @base_notifier = nil @level = 0 @prefix = "" end + # Ensures notifications are ignored, see AbstractNotifier#notify? for + # more information. def notify? false end end - D_NOMSG = NoMsgNotifier.new + D_NOMSG = NoMsgNotifier.new # :nodoc: end end Index: lib/irb/context.rb =================================================================== --- lib/irb/context.rb (revision 38514) +++ lib/irb/context.rb (revision 38515) @@ -12,6 +12,8 @@ require "irb/workspace" https://github.com/ruby/ruby/blob/trunk/lib/irb/context.rb#L12 require "irb/inspector" module IRB + # A class that wraps the current state of the irb session, including the + # configuration of IRB.conf. class Context # Creates a new IRB context. # @@ -101,28 +103,49 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/context.rb#L103 @debug_level = IRB.conf[:DEBUG_LEVEL] end + # The top-level workspace, see WorkSpace#main def main @workspace.main end + # The toplevel workspace, see #home_workspace attr_reader :workspace_home + # WorkSpace in the current context attr_accessor :workspace + # The current thread in this context attr_reader :thread + # The current input method + # + # Can be either StdioInputMethod, ReadlineInputMethod, FileInputMethod or + # other specified when the context is created. See ::new for more + # information on +input_method+. attr_accessor :io + # Current irb session attr_accessor :irb + # A copy of the default <code>IRB.conf[:AP_NAME]</code> attr_accessor :ap_name + # A copy of the default <code>IRB.conf[:RC]</code> attr_accessor :rc + # A copy of the default <code>IRB.conf[:LOAD_MODULES]</code> attr_accessor :load_modules + # Can be either name from <code>IRB.conf[:IRB_NAME]</code>, or the number of + # the current job set by JobManager, such as <code>irb#2</code> attr_accessor :irb_name + # Can be either the #irb_name surrounded by parenthesis, or the + # +input_method+ passed to Context.new attr_accessor :irb_path # Whether +Readline+ is enabled or not. # + # A copy of the default <code>IRB.conf[:USE_READLINE]</code> + # # See #use_readline= for more information. attr_reader :use_readline + # A copy of the default <code>IRB.conf[:INSPECT_MODE]</code> attr_reader :inspect_mode + # A copy of the default <code>IRB.conf[:PROMPT_MODE]</code> attr_reader :prompt_mode # Standard IRB prompt # @@ -138,7 +161,11 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/context.rb#L161 attr_accessor :prompt_c # See IRB@Customizing+the+IRB+Prompt for more information. attr_accessor :prompt_n + # Can be either the deafult <code>IRB.conf[:AUTO_INDENT]</code>, or the + # mode set by #prompt_mode= attr_accessor :auto_indent_mode + # The format of the return statement, set by #prompt_mode= using the + # +:RETURN+ of the +mode+ passed to set the current #prompt_mode. attr_accessor :return_format # Whether <code>^C</code> (+control-c+) will be ignored or not. @@ -154,8 +181,20 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/context.rb#L181 # # If set to +false+, <code>^D</code> will quit irb. attr_accessor :ignore_eof + # Whether to echo the return value to output or not. + # + # Uses IRB.conf[:ECHO] if available, or defaults to +true+. + # + # puts "hello" + # # hello + # #=> nil + # IRB.CurrentContext.echo = false + # puts "omg" + # # omg attr_accessor :echo # Whether verbose messages are displayed or not. + # + # A copy of the default <code>IRB.conf[:VERBOSE]</code> attr_accessor :verbose # The debug level of irb # @@ -194,18 +233,26 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb/context.rb#L233 end end + # Whether #verbose? is +true+, and +input_method+ is either + # StdioInputMethod or ReadlineInputMethod, see #io for more information. def prompting? verbose? || (STDIN.tty? && @io.kind_of?(StdioInputMethod) || (defined?(ReadlineInputMethod) && @io.kind_of?(ReadlineInputMethod))) end + # The return value of the last statement evaluated. attr_reader :last_value + (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/