Exception Handling

Exception Handling — Throwing and catching exceptions

Synopsis

#include <seed/seed.h>

typedef             SeedException;
void                seed_make_exception                 (SeedContext ctx,
                                                         SeedException exception,
                                                         const gchar *name,
                                                         const gchar *message,
                                                         ...);
gchar *             seed_exception_get_name             (SeedContext ctx,
                                                         SeedException exception);
gchar *             seed_exception_get_message          (SeedContext ctx,
                                                         SeedException exception);
guint               seed_exception_get_line             (SeedContext ctx,
                                                         SeedException exception);
gchar *             seed_exception_get_file             (SeedContext ctx,
                                                         SeedException exception);
gchar *             seed_exception_to_string            (SeedContext ctx,
                                                         SeedException exception);

Description

Seed uses exceptions as a method of handling runtime errors within scripts. An exception consists of a name (a list of commonly-used exception names is below), a message, detailing the error, and the line number and filename from which the exception was raised. If Seed cannot determine from where the exception was raised, the line number and filename will be undefined. seed_exception_to_string() provides a simple way to convert all of these into a consistent representation to display to users.

All Seed callbacks take an exception argument; calling seed_make_exception() with this argument and the details you wish to fill it with will propogate that exception up the chain. Exceptions can be caught either by a try/catch block in the calling JavaScript, or by observing the exception property, dealing with it, and then clearing the exception. It is important to note that calling seed_make_exception() does not in fact throw the exception, but just creates an object which, when stored in the exception pointer passed to a callback, causes JSC to throw an exception once flow is returned.

Example 9. Throw an exception, because random_callback was called with the wrong number of arguments

SeedValue random_callback(SeedContext ctx,
                          SeedObject function,
                          SeedObject this_object,
                          gsize argument_count,
                          const SeedValue arguments[],
                          SeedException *exception)
{
    ...
 
    if(argument_count != 1)
    {
        seed_make_exception(ctx, exception, "ArgumentError",
                            "wrong number of arguments; expected 1, got %Zd",
                            argument_count);
        return seed_make_undefined(ctx);
    }
 
    ...
}

Predefined Exception Names

InvalidPropertyValue - a property was set to a value out of range
PropertyError - a warning occurred in GLib while trying to set a property
ArgumentError - a function was called with the wrong number of arguments
ConversionError - one of the type conversion functions threw an exception
TypeError - a required argument was of the wrong type
SyntaxError - a syntax error was thrown from JavaScriptCore
ParseError - a parsing error was thrown from JavaScriptCore (make sure you close all of your brackets!)
ReferenceError - a reference error was thrown from JavaScriptCore (most likely, you tried to access a variable which was undefined)

Details

SeedException

typedef gpointer SeedException;

seed_make_exception ()

void                seed_make_exception                 (SeedContext ctx,
                                                         SeedException exception,
                                                         const gchar *name,
                                                         const gchar *message,
                                                         ...);

Creates a new JavaScript exception with the given attributes.

The line number and file name of the exception created will be undefined.

`ctx` :	A SeedContext.
`exception` :	A reference to a SeedException in which to store the exception.
`name` :	The gchar* representing the exception name.
`message` :	The gchar*, as a printf format string, representing the details of the exception.

seed_exception_get_name ()

gchar *             seed_exception_get_name             (SeedContext ctx,
                                                         SeedException exception);

Retrieves the name of the given exception; this could be one of the predefined exception names given above, or your own name, which should be a single CamelCase word, preferably ending in something like "Error".

`ctx` :	A SeedContext.
`exception` :	A reference to a SeedException.
Returns :	A gchar* representing the name of `exception`.

seed_exception_get_message ()

gchar *             seed_exception_get_message          (SeedContext ctx,
                                                         SeedException exception);

Retrieves the message of the given exception; this should be a human-readable string describing the exception enough that a developer could utilize the message in order to determine where to look to debug the problem.

`ctx` :	A SeedContext.
`exception` :	A reference to a SeedException.
Returns :	A gchar* representing the detailed message of `exception`.

seed_exception_get_line ()

guint               seed_exception_get_line             (SeedContext ctx,
                                                         SeedException exception);

Retrieves the line number the given exception was thrown from; keep in mind that exceptions created from C have an undefined line number.

`ctx` :	A SeedContext.
`exception` :	A reference to a SeedException.
Returns :	A guint representing the line number from which `exception` was thrown.

seed_exception_get_file ()

gchar *             seed_exception_get_file             (SeedContext ctx,
                                                         SeedException exception);

Retrieves the file name the given exception was thrown from; keep in mind that exceptions created from C have an undefined file name.

`ctx` :	A SeedContext.
`exception` :	A reference to a SeedException.
Returns :	A gchar* representing the name of the file from which `exception` was thrown.

seed_exception_to_string ()

gchar *             seed_exception_to_string            (SeedContext ctx,
                                                         SeedException exception);

Properly formats the name, detailed message, line number, and file name of the given extension. This provides a consistent format for printed exceptions, to reduce confusion. Please use it if you're exposing exception data to the outside world.

`ctx` :	A SeedContext.
`exception` :	A reference to a SeedException.
Returns :	A gchar* representing the `exception`.

			Seed Reference Manual
Top \| Description