Class Error

Internal VM and runtime error reflection class.

class Error( [code], [description], [extra] )

more...

Summary

initInternal VM and runtime error reflection class.
codeError code associated with this error.
descriptionTextual description for the error code of this error
lineLine at which the error happened
messageArbitrary text used to better explain and define the error conditions
moduleName of the module where the error has been generated
originString identifying the origin of the error.
pcProgram counter of the instruction that raised the error
subErrorsArray of sub-errors
symbolSymbol name (function or method) where the error has been raised
systemErrorIf the error was caused by a failure during an OS operation, this this property contains the error code indicating the cause of the failure
getSysErrDesc()returns system specific error description.
heading()Creates a short textual representation of the error.
toString()Creates a textual representation of the error.

Detailed description

Internal VM and runtime error reflection class.

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.

Init Block

Internal VM and runtime error reflection class.

init Error( [code], [description], [extra] )

codeA numeric error code.
descriptionA textual description of the error code.
extraA descriptive message explaining the error conditions.

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

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.

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:

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.

Error.getSysErrDesc( )

Returns: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.

heading()

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.

toString()

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.


Made with faldoc 2.1.0