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

ruby-changes:15743

From: marcandre <ko1@a...>
Date: Sat, 8 May 2010 13:50:32 +0900 (JST)
Subject: [ruby-changes:15743] Ruby:r27671 (trunk): * error.c: RDoc for subclasses of Exception.

marcandre	2010-05-08 13:50:09 +0900 (Sat, 08 May 2010)

  New Revision: 27671

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=27671

  Log:
    * error.c: RDoc for subclasses of Exception. [ruby-core:28394]
    
    * cont.c: ditto
    
    * enumerator.c: ditto
    
    * io.c: ditto
    
    * math.c: ditto
    
    * numeric.c: ditto
    
    * proc.c: ditto
    
    * re.c: ditto
    
    * thread.c: ditto
    
    * transcode.c: ditto. Thanks to Run Paint for some of the documentation.

  Modified files:
    trunk/cont.c
    trunk/enumerator.c
    trunk/error.c
    trunk/io.c
    trunk/math.c
    trunk/numeric.c
    trunk/proc.c
    trunk/re.c
    trunk/thread.c
    trunk/transcode.c

Index: math.c
===================================================================
--- math.c	(revision 27670)
+++ math.c	(revision 27671)
@@ -735,6 +735,22 @@
 
 
 /*
+ *  Document-class: Math::DomainError
+ *
+ *  Raised when a mathematical function is evaluated outside of its
+ *  domain of definition.
+ *
+ *  For example, since +cos+ returns values in the range -1..1,
+ *  its inverse function +acos+ is only defined on that interval:
+ *
+ *     Math.acos(42)
+ *
+ *  <em>produces:</em>
+ *
+ *     Math::DomainError: Numerical argument is out of domain - "acos"
+ */
+
+/*
  *  The <code>Math</code> module contains module functions for basic
  *  trigonometric and transcendental functions. See class
  *  <code>Float</code> for a list of constants that
Index: re.c
===================================================================
--- re.c	(revision 27670)
+++ re.c	(revision 27671)
@@ -3449,6 +3449,18 @@
 }
 
 /*
+ *  Document-class: RegexpError
+ *
+ *  Raised when given an invalid regexp expression.
+ *
+ *     Regexp.new("?")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RegexpError: target of repeat operator is not specified: /?/
+ */
+
+/*
  *  Document-class: Regexp
  *
  *  A <code>Regexp</code> holds a regular expression, used to match a pattern
Index: enumerator.c
===================================================================
--- enumerator.c	(revision 27670)
+++ enumerator.c	(revision 27671)
@@ -1021,7 +1021,22 @@
 }
 
 /*
- * StopIteration
+ *  Document-class: StopIteration
+ *
+ *  Raised to stop the iteration, in particular by Enumerator#next. It is
+ *  rescued by Kernel#loop.
+ *
+ *     loop do
+ *       puts "Hello"
+ *       raise StopIteration
+ *       puts "World"
+ *     end
+ *     puts "Done!"
+ *
+ *  <em>produces:</em>
+ *
+ *     Hello
+ *     Done!
  */
 
 /*
Index: io.c
===================================================================
--- io.c	(revision 27670)
+++ io.c	(revision 27671)
@@ -9586,6 +9586,41 @@
 }
 
 /*
+ * Document-class: IOError
+ *
+ * Raised when an IO operation fails.
+ *
+ *    File.open("/etc/hosts") {|f| f << "example"}
+ *      #=> IOError: not opened for writing
+ *
+ *    File.open("/etc/hosts") {|f| f.close; f.read }
+ *      #=> IOError: closed stream
+ *
+ * Note that some IO failures raise +SystemCallError+s and these are not
+ * subclasses of IOError:
+ *
+ *    File.open("does/not/exist")
+ *      #=> Errno::ENOENT: No such file or directory - does/not/exist
+ */
+
+/*
+* Document-class: EOFError
+*
+ * Raised by some IO operations when reaching the end of file. Many IO
+ * methods exist in two forms,
+ *
+ * one that returns +nil+ when the end of file is reached, the other
+ * raises EOFError +EOFError+.
+ *
+ * +EOFError+ is a subclass of +IOError+.
+ *
+ *    file = File.open("/etc/hosts")
+ *    file.read
+ *    file.gets     #=> nil
+ *    file.readline #=> EOFError: end of file reached
+ */
+
+/*
  * Document-class:  ARGF
  *
  * +ARGF+ is a stream designed for use in scripts that process files given as
Index: proc.c
===================================================================
--- proc.c	(revision 27670)
+++ proc.c	(revision 27671)
@@ -2007,6 +2007,49 @@
 }
 
 /*
+ *  Document-class: LocalJumpError
+ *
+ *  Raised when Ruby can't yield as requested.
+ *
+ *  A typical scenario is attempting to yield when no block is given:
+ *
+ *     def call_block
+ *       yield 42
+ *     end
+ *     call_block
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LocalJumpError: no block given (yield)
+ *
+ *  A more subtle example:
+ *
+ *     def get_me_a_return
+ *       Proc.new { return 42 }
+ *     end
+ *     get_me_a_return.call
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LocalJumpError: unexpected return
+ */
+
+/*
+ *  Document-class: SystemStackError
+ *
+ *  Raised in case of a stack overflow.
+ *
+ *     def me_myself_and_i
+ *       me_myself_and_i
+ *     end
+ *     me_myself_and_i
+ *
+ *  <em>raises the exception:</em>
+ *
+ *    SystemStackError: stack level too deep
+ */
+
+/*
  *  <code>Proc</code> objects are blocks of code that have been bound to
  *  a set of local variables. Once bound, the code may be called in
  *  different contexts and still access those variables.
Index: thread.c
===================================================================
--- thread.c	(revision 27670)
+++ thread.c	(revision 27671)
@@ -4127,6 +4127,20 @@
 }
 
 /*
+ *  Document-class: ThreadError
+ *
+ *  Raised when an invalid operation is attempted on a thread.
+ *
+ *  For example, when no other thread has been started:
+ *
+ *     Thread.stop
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ThreadError: stopping only thread
+ */
+
+/*
  *  +Thread+ encapsulates the behavior of a thread of
  *  execution, including the main thread of the Ruby script.
  *
Index: error.c
===================================================================
--- error.c	(revision 27670)
+++ error.c	(revision 27671)
@@ -1084,14 +1084,304 @@
     return Qfalse;
 }
 
+
 /*
+ *  Document-class: StandardError
+ *
+ *  The most standard error types are subclasses of StandardError. A
+ *  rescue clause without an explicit Exception class will rescue all
+ *  StandardErrors (and only those).
+ *
+ *     def foo
+ *       raise "Oups"
+ *     end
+ *     foo rescue "Hello"   # => "Hello"
+ *
+ *  On the other hand:
+ *
+ *     require 'does/not/exist' rescue "Hi"
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LoadError: no such file to load -- does/not/exist
+ *
+ */
+
+/*
+ *  Document-class: SystemExit
+ *
+ *  Raised by +exit+ to initiate the termination of the script.
+ */
+
+/*
+ *  Document-class: SignalException
+ *
+ *  Raised when a signal is received.
+ *
+ *     begin
+ *       Process.kill('HUP',Process.pid)
+ *     rescue SignalException => e
+ *       puts "received Exception #{e}"
+ *     end
+ *
+ *  <em>produces:</em>
+ *
+ *     received Exception SIGHUP
+ */
+
+/*
+ *  Document-class: Interrupt
+ *
+ *  Raised with the interrupt signal is received, typically because the
+ *  user pressed on Control-C (on most posix platforms). As such, it is a
+ *  subclass of +SignalException+.
+ *
+ *     begin
+ *       puts "Press ctrl-C when you get bored"
+ *       loop {}
+ *     rescue Interrupt => e
+ *       puts "Note: You will typically use Signal.trap instead."
+ *     end
+ *
+ *  <em>produces:</em>
+ *
+ *     Press ctrl-C when you get bored
+ *
+ *  <em>then waits until it is interrupted with Control-C and then prints:</em>
+ *
+ *     Note: You will typically use Signal.trap instead.
+ */
+
+/*
+ *  Document-class: TypeError
+ *
+ *  Raised when encountering an object that is not of the expected type.
+ *
+ *     [1, 2, 3].first("two")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     TypeError: can't convert String into Integer
+ *
+ */
+
+/*
+ *  Document-class: ArgumentError
+ *
+ *  Raised when the arguments are wrong and there isn't a more specific
+ *  Exception class.
+ *
+ *  Ex: passing the wrong number of arguments
+ *
+ *     [1, 2, 3].first(4, 5)
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ArgumentError: wrong number of arguments (2 for 1)
+ *
+ *  Ex: passing an argument that is not acceptable:
+ *
+ *     [1, 2, 3].first(-4)
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ArgumentError: negative array size
+ */
+
+/*
+ *  Document-class: IndexError
+ *
+ *  Raised when the given index is invalid.
+ *
+ *     a = [:foo, :bar]
+ *     a.fetch(0)   #=> :foo
+ *     a[4]         #=> nil
+ *     a.fetch(4)   #=> IndexError: index 4 outside of array bounds: -2...2
+ *
+ */
+
+/*
+ *  Document-class: KeyError
+ *
+ *  Raised when the specified key is not found. It is a subclass of
+ *  IndexError.
+ *
+ *     h = {"foo" => :bar}
+ *     h.fetch("foo") # => :bar
+ *     h.fetch("baz") # => KeyError: key not found: "baz"
+ *
+ */
+
+/*
+ *  Document-class: RangeError
+ *
+ *  Raised when a given numerical value is out of range.
+ *
+ *     [1, 2, 3].drop(1 << 100)
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RangeError: bignum too big to convert into `long'
+ */
+
+/*
+ *  Document-class: ScriptError
+ *
+ *  ScriptError is the superclass for errors raised when a script
+ *  can not be executed because of a +LoadError+,
+ *  +NotImplementedError+ or a +SyntaxError+. Note these type of
+ *  +ScriptErrors+ are not +StandardExceptions+ and will not be
+ *  rescued unless it is specified explicitly (or its ancestor
+ *  +Exception+).
+ */
+
+/*
+ *  Document-class: SyntaxError
+ *
+ *  Raised when encountering Ruby code with an invalid syntax.
+ *
+ *     eval("1+1=2")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     SyntaxError: (eval):1: syntax error, unexpected '=', expecting $end
+ */
+
+/*
+ *  Document-class: LoadError
+ *
+ *  Raised when a file required (a Ruby script, extension library, ...)
+ *  fails to load.
+ *
+ *     require 'this/file/does/not/exist'
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LoadError: no such file to load -- this/file/does/not/exist
+ */
+
+/*
+ *  Document-class: NotImplementedError
+ *
+ *  Raised when a feature is not implemented on the current platform. For
+ *  example, methods depending on the +fsync+ or +fork+ system calls may
+ *  raise this exception if the underlying operating system or Ruby
+ *  runtime does not support them.
+ *
+ *  Note that if +fork+ raises a +NotImplementedError+, then
+ *  <code>respond_to?(:fork)</code> returns +false+.
+ */
+
+/*
+ *  Document-class: NameError
+ *
+ *  Raised when a given name is invalid or undefined.
+ *
+ *     puts foo
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     NameError: undefined local variable or method `foo' for main:Object
+ *
+ *  Since constant names must start with a capital:
+ *
+ *     Fixnum.const_set :answer, 42
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     NameError: wrong constant name answer
+ */
+
+/*
+ *  Document-class: NoMethodError
+ *
+ *  Raised when a method is called on a receiver which doesn't have it
+ *  defined and also fails to respond with +method_missing+.
+ *
+ *     "hello".to_ary
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     NoMethodError: undefined method `to_ary' for "hello":String
+ */
+
+/*
+ *  Document-class: RuntimeError
+ *
+ *  A generic error class raised when an invalid operation is attempted.
+ *
+ *     [1, 2, 3].freeze << 4
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RuntimeError: can't modify frozen array
+ *
+ *  Kernel.raise will raise a RuntimeError if no Exception class is
+ *  specified.
+ *
+ *     raise "ouch"
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RuntimeError: ouch
+ */
+
+/*
+ *  Document-class: SecurityError
+ *
+ *  Raised when attempting a potential unsafe operation, typically when
+ *  the $SAFE level is raised above 0.
+ *
+ *     foo = "bar"
+ *     proc = Proc.new do
+ *       $SAFE = 4
+ *       foo.gsub! "a", "*"
+ *     end
+ *     proc.call
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     SecurityError: Insecure: can't modify string
+ */
+
+/*
+ *  Document-class: NoMemoryError
+ *
+ *  Raised when memory allocation fails.
+ */
+
+/*
+ *  Document-class: SystemCallError
+ *
+ *  SystemCallError is the base class for all low-level
+ *  platform-dependent errors.
+ *
+ *  The errors available on the current platform are subclasses of
+ *  SystemCallError and are defined in the Errno module.
+ *
+ *     File.open("does/not/exist")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     Errno::ENOENT: No such file or directory - does/not/exist
+ */
+
+/*
+ *  Document-class: Encoding::CompatibilityError
+ *
+ *  Raised by Encoding and String methods when the source encoding is
+ *  incompatible with the target encoding.
+ */
+
+/*
  *  Descendants of class <code>Exception</code> are used to communicate
  *  between <code>raise</code> methods and <code>rescue</code>
  *  statements in <code>begin/end</code> blocks. <code>Exception</code>
  *  objects carry information about the exception---its type (the
  *  exception's class name), an optional descriptive string, and
  *  optional traceback information. Programs may subclass
- *  <code>Exception</code> to add additional information.
+ *  <code>Exception</code>, or more typically <code>StandardException</code>
+ *  to provide custom classes and add additional information.
  */
 
 void
Index: numeric.c
===================================================================
--- numeric.c	(revision 27670)
+++ numeric.c	(revision 27671)
@@ -3198,6 +3198,38 @@
     return Qtrue;
 }
 
+/*
+ *  Document-class: ZeroDivisionError
+ *
+ *  Raised when attempting to divide an integer by 0.
+ *
+ *     42 / 0
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ZeroDivisionError: divided by 0
+ *
+ *  Note that only division by an exact 0 will raise that exception:
+ *
+ *     42 /  0.0 # => Float::INFINITY
+ *     42 / -0.0 # => -Float::INFINITY
+ *     0  /  0.0 # => NaN
+ */
+
+/*
+ *  Document-class: FloatDomainError
+ *
+ *  Raised when attempting to convert special float values
+ *  (in particular infinite or NaN)
+ *  to numerical classes which don't support them.
+ *
+ *     Float::INFINITY.to_r
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     FloatDomainError: Infinity
+ */
+
 void
 Init_Numeric(void)
 {
Index: cont.c
===================================================================
--- cont.c	(revision 27670)
+++ cont.c	(revision 27671)
@@ -1422,6 +1422,21 @@
     return rb_fiber_current();
 }
 
+
+
+/*
+ *  Document-class: FiberError
+ *
+ *  Raised when an invalid operation is attempted on a Fiber, in
+ *  particular when attempting to call/resume a dead fiber,
+ *  attempting to yield from the root fiber, or calling a fiber across
+ *  threads.
+ *
+ *     fiber = Fiber.new{}
+ *     fiber.resume #=> nil
+ *     fiber.resume #=> FiberError: dead fiber called
+ */
+
 void
 Init_Cont(void)
 {
Index: transcode.c
===================================================================
--- transcode.c	(revision 27670)
+++ transcode.c	(revision 27671)
@@ -4217,6 +4217,28 @@
 
 extern void Init_newline(void);
 
+/*
+ *  Document-class: Encoding::UndefinedConversionError
+ *
+ *  Raised by Encoding and String methods when a transcoding operation
+ *  fails.
+ */
+
+/*
+ *  Document-class: Encoding::InvalidByteSequenceError
+ *
+ *  Raised by Encoding and String methods when the string being
+ *  transcoded contains a byte invalid for the either the source or
+ *  target encoding.
+ */
+
+/*
+ *  Document-class: Encoding::ConverterNotFoundError
+ *
+ *  Raised by transcoding methods when a named encoding does not
+ *  correspond with a known converter.
+ */
+
 void
 Init_transcode(void)
 {

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

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