Internal VM and runtime error reflection class.
Class Error( [code],[description],[extra] )
| code | A numeric error code. |
| description | A textual description of the error code. |
| extra | A descriptive message explaining the error conditions. |
In case the error code is a well known code (i.e. one of the codes known by the engine), the description of the error will be automatically provided.
To provide an error message without setting the code description, use directly the Error.message property after having created the object.
The Error class is used by the virtual machine and by the Falcon Feathers functions to communicate to the scripts, and eventually to the embedding application, about error conditions. It is also available to extension modules, and to the script themselves, that can create error instances that can be cached internally or returned to the embedder.
A complete error code is formed by two letters indicating the error origin, and a numeric code specifying the correct error name. By convention, one and only one error description may be associated with one error code. The error message is free to be used to carry more specific informations about the error conditions.
Use the comment parameter when the error message is generic, and/or the error may be reported because of various reasons, or to give an hint about how to avoid the error.
Error codes below 5000 are reserved to Falcon engine and officially recognized modules. Extension modules should issue errors above 5001, unless raising well known error codes that are encoded and described directly by the Falcon Engine (i.e. a very common error code is 901 - invalid parameters when a user makes a mistake in calling a script function).
All the elements in the error class are automatically initialized by the constructor, except for the code, the message and the description. As some error are created by binary modules, which are not executed by the VM, the informations about the line and the program counter that generated the error may not always be available.
The toString() method returns a string representation of the error, which includes all the available informations (except for system error description). In this version, access to the TraceBack class has been removed from scripts.
| Properties | |
| boxed | Boxed error. |
| code | Error code associated with this error. |
| description | Textual description for the error code of this error. |
| line | Line at which the error happened. |
| message | Arbitrary text used to better explain and define the error conditions. |
| module | Name of the module where the error has been generated. |
| origin | String identifying the origin of the error. |
| pc | Program counter of the instruction that raised the error. |
| subErrors | Array of sub-errors. |
| symbol | Symbol name (function or method) where the error has been raised. |
| systemError | If the error was caused by a failure during an OS operation, this this property contains the error code indicating the cause of the failure. |
| Methods | |
| getSysErrDesc | returns system specific error description. |
| heading | Creates a short textual representation of the error. |
| toString | Creates a textual representation of the error. |
Boxed error.
Boxed error. Similar to subError, but this is a single error that was separately raised, and caused an higher-priority error to be raised next. For example, included script may raise an error that generates then a "failed to include" error at top-level. The inner error generated by the included script is available as the boxed error.
Error code associated with this error.
Textual description for the error code of this error.
Textual description for the error code of this error.
Line at which the error happened.
Line at which the error happened. If not applicable (i.e. because the error is not generated by a Falcon script) is 0.
Arbitrary text used to better explain and define the error conditions.
Arbitrary text used to better explain and define the error conditions. Consider this as a "free text".
Name of the module where the error has been generated.
Name of the module where the error has been generated.
String identifying the origin of the error.
This code allows to determine what element of the Falcon engine has raised the error (or eventually, if this error has been raised by a script or a loaded module).
The error origin is a string; when an error gets displayed through a standard rendering function (as the Error.toString() method), it is indicated by two letters in front of the error code for better readability. The origin code may be one of the following:
- compiler - (represented in Error.toString() as CO)
Program counter of the instruction that raised the error.
Program counter of the instruction that raised the error. If not applicable (i.e. if the VM wasn't running when the error has been raised) the number will be 0.
Array of sub-errors.
Array of sub-errors. Some error generating facilities may delay error reporting to complete some operations, and then report all the errors at once, encapsulated in a top-level failure signaling error. It's the case of the reflexive compiler, which, in case of errors during compilation of source code, would record all the errors and store them in a generic "syntax error" exception. This property stores a vector of the single sub-errors that have caused operation failure.
Symbol name (function or method) where the error has been raised.
Symbol name (function or method) where the error has been raised.
If the error was caused by a failure during an OS operation, this this property contains the error code indicating the cause of the failure.
If the error was caused by a failure during an OS operation, this this property contains the error code indicating the cause of the failure. Otherwise, it will be 0.
returns system specific error description.
Error.getSysErrDesc()
| Return | System specific error description or nil if not available. |
If the error was generated by the underlying system (that is, if systemError > 0) returns a system and locale dependent error description. The description is obtained by querying the relevant OS error description API/SDK.
Creates a short textual representation of the error.
Error.heading()
This method will only render the essential informations of the error, without printing the stack trace and without checking for other sub errors in the Error.subErrors array.
See also: Error.
Creates a textual representation of the error.
Error.toString()
This method uses the standard Falcon error representation to render the error codes, descriptions and stack traces into a string. Suberrors are also considered.
To get only a descriptive string of the error without its stack trace, use the Error.heading method.