exceptions: MDL-16175 new invalid_state_exception

This is for those situations where something basically impossible happens,
like $context->contextlevel not having one of the valid value, and you
want to throw an exception (for example in the default: case of a switch)
rather than just ignoring the possibility.

lang/en_utf8/error.php

@@ -298,6 +298,7 @@
 $string['invalidsesskey'] = 'Incorrect sesskey submitted, form not accepted!';
 $string['invalidsection'] = 'Course module record contains invalid section';
 $string['invalidshortname'] = 'That\'s an invalid short course name';
+$string['invalidstatedetected'] = 'Something has gone wrong: $a. This should never normally happen.';
 $string['invalidurl'] = 'Invalid URL';
 $string['invaliduser'] = 'Invalid user';
 $string['invaliduserid'] = 'Invalid user id';

lib/setuplib.php

@@ -45,10 +45,10 @@ function __construct($errorcode, $module='', $link='', $a=NULL, $debuginfo=null)
 }
 
 /**
- * Exception indicating programming error, must be fixed by a programer.
+ * Exception indicating programming error, must be fixed by a programer. For example
+ * a core API might throw this type of exception if a plugin calls it incorrectly.
  */
 class coding_exception extends moodle_exception {
-
     /**
      * Constructor
      * @param string $hint short description of problem
@@ -59,6 +59,24 @@ function __construct($hint, $debuginfo=null) {
     }
 }
 
+/**
+ * An exception that indicates something really weird happended. For example,
+ * if you do switch ($context->contextlevel), and have one case for each
+ * CONTEXT_... constant. You might throw an invalid_state_exception in the
+ * default case, to just in case something really weird is going on, and 
+ * $context->contextlevel is invalid - ratehr than ignoring this possibility.
+ */
+class invalid_state_exception extends moodle_exception {
+    /**
+     * Constructor
+     * @param string $hint short description of problem
+     * @param string $debuginfo optional more detailed information
+     */
+    function __construct($hint, $debuginfo=null) {
+        parent::__construct('invalidstatedetected', 'debug', '', $hint, $debuginfo);
+    }
+}
+
 /**
  * Default exception handler, uncought exceptions are equivalent to using print_error()
  */