diff options
| -rw-r--r-- | cont.c | 15 | ||||
| -rw-r--r-- | enumerator.c | 17 | ||||
| -rw-r--r-- | error.c | 292 | ||||
| -rw-r--r-- | io.c | 35 | ||||
| -rw-r--r-- | math.c | 16 | ||||
| -rw-r--r-- | numeric.c | 32 | ||||
| -rw-r--r-- | proc.c | 43 | ||||
| -rw-r--r-- | re.c | 12 | ||||
| -rw-r--r-- | thread.c | 14 | ||||
| -rw-r--r-- | transcode.c | 22 |
10 files changed, 496 insertions, 2 deletions
@@ -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!" + * + * <em>produces:</em> + * + * Hello + * Done! */ /* @@ -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" + * + * <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> @@ -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 - * <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 @@ -9586,6 +9586,41 @@ rb_get_argv(void) } /* + * 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 @@ -735,6 +735,22 @@ 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) + * + * <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 @@ -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 + * + * <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) { @@ -2007,6 +2007,49 @@ proc_curry(int argc, VALUE *argv, VALUE self) } /* + * 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. @@ -3449,6 +3449,18 @@ re_warn(const char *s) } /* + * 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 @@ -4127,6 +4127,20 @@ rb_thread_backtrace_m(VALUE 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 + * + * <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. * 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) { |