Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

ClassError

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

Internal VM and runtime error reflection class. more...


Member list

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.
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.
Constructor
init Initializes the error.
Methods
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

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.


Class 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.

If not applicable (i.e. because the error is not generated by a Falcon script) is 0.

message
Arbitrary text used to better explain and define the error conditions.

Consider this as a "free text".

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:

  • compiler - (represented in Error.toString() as CO)
  • assembler - (AS)
  • loader - that is, the module loader (LD)
  • vm - the virtual machine (when not running a script, short VM)
  • script - (that is, a VM running a script, short SS)
  • runtime - (core or runtime modules, RT)
  • module - an extension module (MD).
pc
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.

subErrors
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
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.

Otherwise, it will be 0.


Class methods

init()

Initializes the error.

Error.init( [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 (undefined) Expected a link class but found a string: Error property after having created the object.

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 (undefined) Expected a link class but found a string: Error array.

See also Error.toString.

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.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0