Handling errors

Errors are reported by Cowl via return values (such as cowl_ret), or by returning NULL on allocation errors. Sometimes this may not be enough, such as when reading ontology documents: in these cases, Cowl lets you setup CowlErrorHandler instances, which grant more fine-grained control over errors.

Error handlers can be either provided locally to specific objects (such as via cowl_manager_set_error_handler()), or you can opt to specify a global error handler via cowl_set_error_handler(). If you do both, Cowl prioritizes local error handlers, as you would expect.

struct CowlErrorHandler

Provides a mechanism for error handling.

Public Members

void *ctx

Error handler context, can be anything.

void (*handle_error)(void *ctx, CowlError const *error)

Pointer to a function called when an error occurs.

Param ctx:

Error handler context.

Param error:

Error.

void (*free)(void *ctx)

Pointer to a resource deallocator function for the context.

Note

Can be NULL if the context does not need to release resources.

Param ctx:

Error handler context.

struct CowlError

Error data structure.

Public Members

cowl_ret code

Error code.

CowlString *description

Human readable description of the error.

CowlAny *origin

Object that originated the error.

struct CowlSyntaxError

Syntax error.

Pseudo-extends: CowlError

Public Members

CowlError super

Base error.

CowlErrorLoc loc

Error location.

struct CowlErrorLoc

Error location.

Public Members

ulib_uint line

Line where the error occurred.

CowlString *source

Location of the ontology where the error occurred.

CowlString *cowl_error_to_string(CowlError const *error)

Returns a human-readable string representation of the specified error.

Note

You must release the returned object via cowl_release().

Parameters:

  • error – The error.

Returns:

String representation, or NULL on error.

cowl_ret cowl_handle_error(cowl_ret code, UString desc, CowlAny *origin)

Handles an error by using the most specific error handler available.

Parameters:

  • code – Error code.

  • desc – Error description.

  • origin – Object that originated the error.

Returns:

Error code.

cowl_ret cowl_handle_syntax_error(UString desc, CowlAny *origin, CowlErrorLoc loc)

Handles a syntax error via the most specific error handler available.

Parameters:

  • desc – Error description.

  • origin – Object that originated the error.

  • loc – Error location.

Returns:

Error code.

cowl_ret cowl_handle_error_code(cowl_ret code, CowlAny *origin)

Handles a generic error of the specified type via the most specific error handler available.

Parameters:

  • code – Error code.

  • origin – Object that originated the error.

Returns:

Error code.

cowl_ret cowl_handle_stream_error(ustream_ret code, CowlAny *origin)

Handles an IO stream error via the most specific error handler available.

Parameters:

  • code – Error code.

  • origin – Object that originated the error.

Returns:

Error code.

cowl_ret cowl_handle_path_error(UString path, UString reason, CowlAny *origin)

Handles an error triggered while accessing the file at the specified path.

Parameters:

  • path – File path.

  • reason – Why the error was triggered.

  • origin – Object that originated the error.

Returns:

Error code.