[前][次][番号順一覧][スレッド一覧]

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/

[前][次][番号順一覧][スレッド一覧]