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/