module exceptions

This library defines the standard exception types. These types are used by the standard libraries and by the VM itself. You are encouraged to use these types as well in your own code, though there is no requirement to do so.

Exception types ending in "Exception" are for generally "non-fatal" exceptions, and those ending in "Error" are for generally fatal errors which mean consistency has failed and the program needs to be fixed.

All the standard exception types are also exported into the global namespace, so they can be accessed without having to import them from this module.

class Location

This class holds a source location, which is used in exception tracebacks and compilation errors.

There two kinds of locations: compile-time and runtime. Compile-time locations have a column number > 0 and indicate the exact location within a source file where something went wrong. Runtime locations have a column number <= 0, in which case the exact kind of location is encoded in the column number as one of Location.Unknown, Location.Native, or Location.Script.

Location.Unknown

This is one of the types of locations that can be put in the col field. It means that there isn't enough information to determine a location for where an error occurred. In this case the file and line will also probably meaningless.

Location.Native

This is another type of location that can be put in the col field. It means that the location is within a native function, so there isn't enough information to give a line, but at least the file can be determined.

Location.Script

This is the last type of location that can be put in the col field. It means that the location is within script code, the file and (usually) the line can be determined. The column can never be determined at runtime, however.

Location.file = ""

This is a string containing the module and function where the error occurred, in the format "module.name.func". If col is Location.Unknown, this field will be the empty string.

Location.line = 0

This is the line on which the error occurred. If the location type is Location.Script, this field can be -1, which means that no line number could be determined.

Location.col = Location.Unknown

This field serves double duty as either a column number for compilation errors or as a location "type".

If this field is > 0, it is a compilation error and represents the column where the error occurred. Otherwise, this field will be one of the three constants above (which are all <= 0).

Location.this(file: string = null, line: int = -1, col: int = Location.Script)

Constructor. All parameters are optional. When passed null for file, the line and col parameters are ignored, constructing an "Unknown" location.

function Location.toString()

Gives a string representation of the location, in the following formats:

Unknown - "<unknown location>"
Native - "file(native)"
Script - "file(line)" (if line < 1 then the line will be '?' instead)
otherwise - "file(line:col)"

class Throwable

This class defines the interface that the VM expects throwable exception types to have, along with some useful methods. You can throw instances of any class type in Croc, but you can save a lot of time writing your own exception classes by just deriving from this class.

This class is also exported into the global namespace, so you can access it without having to import it from this module.

Throwable.location = Location()

The location where this exception was thrown. See the exceptions.Location class documentation for more info. Defaults to an unknown location.

Throwable.msg = ""

The human-readable message associated with the exception. Defaults to the empty string.

Throwable.cause = null

An optional field. Sometimes an exception can cause a cascade of other exceptions; for instance, an exception thrown while importing a module will cause the module import to fail and throw an exception of its own. In these cases, the cause field is used to hold the exception that caused this exception to be thrown. There can be arbitrarily many exceptions nested in this linked list of causes. It is up to the user, however, to provide the cause exception when throwing a second exception; there is no built-in mechanism to ensure that this field is filled in. You can use the setCause function for this purpose.

The default value is null, which means this exception had no cause.

Throwable.traceback = []

This is an array of Location instances that shows the call stack as it was when the exception was thrown, allowing you to pinpoint the exact codepath that caused the error. This array starts at the location where the exception was thrown; that is, element 0 is the same as the location field. After that, it gives the function that called the function where the exception was thrown and goes up the call stack. Tailcalls are represented as script locations. You can get a string representation of this traceback with the tracebackString method. This field defaults to an empty array.

Throwable.this(msg: string = "", cause: Throwable = null)

Constructor. All parameters are optional.

Params:
msg
A descriptive message of the exception being thrown. This is meant to be human-readable, and is not used by the EH mechanism in any way. Defaults to the empty string.
cause
The exception that caused this exception to be thrown. Defaults to none (null).

function Throwable.toString()

Gives a string representation of the exception. It is in the format "<exception type> at <location>: <msg>".

If the message is the empty string, there will be no colon after the location. If cause is non-null, this will be followed by a newline, "Caused by:", another newline, and the string representation of cause. This will continue recursively, meaning there may be several layers of causes in one representation.

function Throwable.setLocation(loc: Location)

Acts as a setter for the location field. This is occasionally useful when programmatically building exception objects such as in the compiler.

function Throwable.setCause(cause: instance)

Acts as a setter for the cause field. This can be useful when throwing an exception that is caused by another exception. Rather than forcing an exception constructor to take the cause as a parameter, you can simply use "throw SomeException().setCause(ex)" instead.

function Throwable.tracebackString()

Gets a string representation of the traceback field. The first entry is preceded by "Traceback: ". Each subsequent entry is preceded by a newline, some whitespace, and "at: ".

global function stdException(name: string)

Gets one of the standard exception types by name.

Returns:

one of the standard exception classes.

Throws:
NameError
if the given name does not name a standard exception type.

global function rethrow(ex: instance)

Rethrows the exception ex. This is the same as throwing it normally, except the traceback is not modified.

class LexicalException : Throwable

Thrown for lexical errors in source code. The location field is the source location that caused the exception to be thrown.

class SyntaxException : Throwable

Thrown for syntactic errors in source code. The location field is the source location that caused the exception to be thrown.

class SemanticException : Throwable

Thrown for semantic errors in source code. The location field is the source location that caused the exception to be thrown.

class ImportException : Throwable

Thrown when an import fails; may also have a 'cause' exception in case the import failed because of an exception being thrown from the module's top-level function.

class OSException : Throwable

OS error APIs are often a poor match for the way Croc does error handling, but unhandled OS errors can lead to bad things happening. Therefore Croc libraries are encouraged to translate OS errors into OSExceptions so that code won't blindly march on past errors, but they can still be caught and handled appropriately.

class IOException : Throwable

Thrown when an IO operation fails or is given invalid inputs. The rationale for this exception type is the same as that of OSException.

class HaltException : Throwable

Thrown when a thread is halted. You can catch this kind of exception, but in practice you really shouldn't unless you're doing something like writing a CLI.

This exception type is special in that it never propagates out of the thread that was halted. Instead when this exception escapes the thread that was halted, the thread is simply marked as dead and execution resumes in the resuming thread as normal.

class AssertError : Throwable

Thrown when an assertion fails.

class ApiError : Throwable

Thrown when the native API is given certain kinds of invalid input, generally inputs which mean the host is malfunctioning or incorrectly programmed.

class ParamError : Throwable

Thrown for function calls which are invalid because they were given an improper number of parameters. However if a function is given parameters of incorrect type, a TypeError is thrown instead.

class FinalizerError : Throwable

Thrown when an exception is thrown by a class finalizer. This is a big problem as finalizers should never fail. The exception that the finalizer threw is set as the 'cause'.

class NameError : Throwable

Thrown on invalid global access (either the name doesn't exist or trying to redefine an existing global). Also thrown on invalid local names when using the debug library.

class BoundsError : Throwable

Thrown when trying to access an array-like object out of bounds. You could also use this for other kinds of containers.

class FieldError : Throwable

Thrown when trying to access an invalid field from a namespace, class, instance etc., unless it's global access, in which case a NameError is thrown.

class MethodError : Throwable

Thrown when trying to call an invalid method on an object.

class LookupError : Throwable

Thrown when any general kind of lookup has failed. Use one of the more specific types (like BoundsError or NameError if you can.

class RuntimeError : Throwable

Kind of a catchall type for other random runtime errors. Other exceptions will probably grow out of this one.

class NotImplementedError : Throwable

An exception type that you can throw in methods that are unimplemented (such as in abstract base class methods). This way when an un-overridden method is called, you get an error instead of it silently working.

class SwitchError : Throwable

Thrown when a switch without a 'default' is given a value not listed in its cases.

class TypeError : Throwable

Thrown when an incorrect type is given to an operation (i.e. trying to add strings, or when invalid types are given to function parameters).

class ValueError : Throwable

Generally speaking, indicates that an operation was given a value of the proper type, but the value is invalid somehow - not an acceptable value, or incorrectly formed, or in an invalid state. If possible, try to use one of the more specific classes like RangeError, or derive your own.

class RangeError : Throwable

Thrown to indicate that a value is out of a valid range of acceptable values. Typically used for mathematical functions, i.e. square root only works on non-negative values. Note that if the error is because a value is out of the range of valid indices for a container, you should use a BoundsError instead.

class StateError : Throwable

Thrown to indicate that an object is in an invalid state.

class UnicodeError : Throwable

Thrown when Croc is given malformed/invalid Unicode data for a string, or when invalid Unicode data is encountered during transcoding.

class VMError : Throwable

Thrown for some kinds of internal VM errors.

HTML and JavaScript source derived from

by Victor Nakoryakov; Page generated on 15 Nov 2014 10:28:14

msg	A descriptive message of the exception being thrown. This is meant to be human-readable, and is not used by the EH mechanism in any way. Defaults to the empty string.
cause	The exception that caused this exception to be thrown. Defaults to none (null).