From 1dee5e34a3d397eb96db0b6bcc8e9cb9858975d0 Mon Sep 17 00:00:00 2001 From: marcandre Date: Sat, 8 May 2010 04:50:09 +0000 Subject: [PATCH] * 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. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27671 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- cont.c | 15 +++ enumerator.c | 17 ++- error.c | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++- io.c | 35 ++++++ math.c | 16 +++ numeric.c | 32 ++++++ proc.c | 43 ++++++++ re.c | 12 +++ thread.c | 14 +++ transcode.c | 22 ++++ 10 files changed, 496 insertions(+), 2 deletions(-) diff --git a/cont.c b/cont.c index c164a3554b..fb0959d1b9 100644 --- a/cont.c +++ b/cont.c @@ -1422,6 +1422,21 @@ rb_fiber_s_current(VALUE klass) 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) { diff --git a/enumerator.c b/enumerator.c index 91bb3be14f..64ff841a11 100644 --- a/enumerator.c +++ b/enumerator.c @@ -1021,7 +1021,22 @@ generator_each(VALUE obj) } /* - * 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!" + * + * produces: + * + * Hello + * Done! */ /* diff --git a/error.c b/error.c index 2cced9aa62..cfa5d57ce2 100644 --- a/error.c +++ b/error.c @@ -1084,6 +1084,295 @@ syserr_eqq(VALUE self, VALUE exc) 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" + * + * raises the exception: + * + * 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 + * + * produces: + * + * 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 + * + * produces: + * + * Press ctrl-C when you get bored + * + * then waits until it is interrupted with Control-C and then prints: + * + * 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") + * + * raises the exception: + * + * 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) + * + * raises the exception: + * + * ArgumentError: wrong number of arguments (2 for 1) + * + * Ex: passing an argument that is not acceptable: + * + * [1, 2, 3].first(-4) + * + * raises the exception: + * + * 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) + * + * raises the exception: + * + * 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") + * + * raises the exception: + * + * 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' + * + * raises the exception: + * + * 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 + * respond_to?(:fork) returns +false+. + */ + +/* + * Document-class: NameError + * + * Raised when a given name is invalid or undefined. + * + * puts foo + * + * raises the exception: + * + * NameError: undefined local variable or method `foo' for main:Object + * + * Since constant names must start with a capital: + * + * Fixnum.const_set :answer, 42 + * + * raises the exception: + * + * 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 + * + * raises the exception: + * + * 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 + * + * raises the exception: + * + * RuntimeError: can't modify frozen array + * + * Kernel.raise will raise a RuntimeError if no Exception class is + * specified. + * + * raise "ouch" + * + * raises the exception: + * + * 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 + * + * raises the exception: + * + * 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") + * + * raises the exception: + * + * 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 Exception are used to communicate * between raise methods and rescue @@ -1091,7 +1380,8 @@ syserr_eqq(VALUE self, VALUE exc) * objects carry information about the exception---its type (the * exception's class name), an optional descriptive string, and * optional traceback information. Programs may subclass - * Exception to add additional information. + * Exception, or more typically StandardException + * to provide custom classes and add additional information. */ void diff --git a/io.c b/io.c index c72caae3b9..f9c01f3839 100644 --- a/io.c +++ b/io.c @@ -9585,6 +9585,41 @@ rb_get_argv(void) return ARGF.argv; } +/* + * 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 * diff --git a/math.c b/math.c index 8601b614e7..3d673129bd 100644 --- a/math.c +++ b/math.c @@ -734,6 +734,22 @@ exp1(sinh) exp1(sqrt) +/* + * 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) + * + * produces: + * + * Math::DomainError: Numerical argument is out of domain - "acos" + */ + /* * The Math module contains module functions for basic * trigonometric and transcendental functions. See class diff --git a/numeric.c b/numeric.c index fc05c9963c..f2c8c13a97 100644 --- a/numeric.c +++ b/numeric.c @@ -3198,6 +3198,38 @@ fix_even_p(VALUE num) return Qtrue; } +/* + * Document-class: ZeroDivisionError + * + * Raised when attempting to divide an integer by 0. + * + * 42 / 0 + * + * raises the exception: + * + * 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 + * + * raises the exception: + * + * FloatDomainError: Infinity + */ + void Init_Numeric(void) { diff --git a/proc.c b/proc.c index 9539f71445..30fc2475a6 100644 --- a/proc.c +++ b/proc.c @@ -2006,6 +2006,49 @@ proc_curry(int argc, VALUE *argv, VALUE self) return make_curry_proc(self, rb_ary_new(), arity); } +/* + * 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 + * + * raises the exception: + * + * LocalJumpError: no block given (yield) + * + * A more subtle example: + * + * def get_me_a_return + * Proc.new { return 42 } + * end + * get_me_a_return.call + * + * raises the exception: + * + * 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 + * + * raises the exception: + * + * SystemStackError: stack level too deep + */ + /* * Proc objects are blocks of code that have been bound to * a set of local variables. Once bound, the code may be called in diff --git a/re.c b/re.c index 3316da2d72..2789120cd4 100644 --- a/re.c +++ b/re.c @@ -3448,6 +3448,18 @@ re_warn(const char *s) rb_warn("%s", s); } +/* + * Document-class: RegexpError + * + * Raised when given an invalid regexp expression. + * + * Regexp.new("?") + * + * raises the exception: + * + * RegexpError: target of repeat operator is not specified: /?/ + */ + /* * Document-class: Regexp * diff --git a/thread.c b/thread.c index c9a18088f5..668e698cea 100644 --- a/thread.c +++ b/thread.c @@ -4126,6 +4126,20 @@ rb_thread_backtrace_m(VALUE thval) return rb_thread_backtrace(thval); } +/* + * Document-class: ThreadError + * + * Raised when an invalid operation is attempted on a thread. + * + * For example, when no other thread has been started: + * + * Thread.stop + * + * raises the exception: + * + * ThreadError: stopping only thread + */ + /* * +Thread+ encapsulates the behavior of a thread of * execution, including the main thread of the Ruby script. diff --git a/transcode.c b/transcode.c index 6490f5b3bc..5ca3a3abc9 100644 --- a/transcode.c +++ b/transcode.c @@ -4217,6 +4217,28 @@ ecerr_incomplete_input(VALUE self) 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) {