About all my projects
Gnome::Glib::Error

Gnome::Glib::Error

A system for reporting errors

Description

GLib provides a standard method of reporting errors from a called method to the calling code. Methods that can fail return an N-GError object. On error, a defined N-GError instance will be returned to the caller. After handling the error, the error object must be freed using clear-object().

The N-GError object contains three fields: domain indicates the module the error-reporting function is located in, code indicates the specific error that occurred, and message is a user-readable error message with as many details as possible. Several functions are provided to deal with an error received from a called function: matches() returns True if the error matches a given domain and code. To display an error to the user, simply call the message() method, perhaps along with additional context known only to the calling function.

This class is greatly simplified because in Raku one can use Exception classes to throw any errors. It exists mainly to handle errors coming from other methods in the Gio, Glib, Gtk and Gdk libraries.

Error domains and codes are conventionally named as follows:

  • The error domain is called NAMESPACE_MODULE_ERROR. For instance glib file utilities uses G_FILE_ERROR.

  • The quark function for the error domain is called <namespace>_<module>_error_quark

  • The error codes are in an enumeration called <Namespace><Module>Error, for example GFileError.

  • Members of the error code enumeration are called <NAMESPACE>_<MODULE>_ERROR_<CODE>

  • If there's a "generic" or "unknown" error code for unrecoverable errors it doesn't make sense to distinguish with specific codes, it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, for example G_SPAWN_ERROR_FAILED. In the case of error code enumerations that may be extended in future releases, you should generally not handle this error code explicitly, but should instead treat any unrecognized error code as equivalent to FAILED.

Synopsis

Declaration

unit class Gnome::Glib::Error;
also is Gnome::N::TopLevelClassSupport;

Uml Diagram

No caption

Example

my Gnome::Gtk3::Builder $builder .= new;

# Try to read non existing file
my Gnome::Glib::Error $e = $builder.add-from-file('x.glade');
die $e.message if $e.is-valid;

Types

class N-GError;

  • has GQuark $.domain; The set domain.

  • has Int $.code; The set error code.

  • has Str $.message; The error message.

Methods

new

:domain, :code, :error-message

Create a new Error object. A domain, which is a string must be converted to an unsigned integer with one of the Quark conversion methods. See Gnome::Glib::Quark.

multi method new ( GQuark :$domain!, Int :$code!, Str :$error-message! )

:native-object

Create a new Error object using an other native error object.

multi method new ( N-GError() :$native-object! )

[g_] clear_error

Calls g_error_free() on the native object and sets it to Any.

method g_clear_error ( )

code

Return the error code of the error. Returns Int if object is invalid.

method code ( --> Int )

copy

Makes a copy of the native error object.

# create or get the error object from somewhere
my Gnome::Glib::Error $e = …;

# later on, you can copy the error if needed and create a second object
my Gnome::Glib::Error() $e2 = $e.copy;

Returns: a new N-GError

method copy ( --> N-GError )

domain

Get the domain code from the error object. Use to-string() from Gnome::Glib::Quark to get the domain text representation of it. Returns UInt if object is invalid.

method domain ( --> GQuark )

domain-register

This function registers an extended N-GError domain. $error_type_name will be duplicated.

$error_type_init receives a native initialized Gnome::Glib::Error and should then initialize the private data.

error_type_copy is a function that receives both original and a copy Gnome::Glib::Error and should copy the fields of the private error data. The standard Gnome::Glib::Error fields are already handled.

$error_type_clear receives the pointer to the error, and it should free the fields of the private error data. It should not free the struct itself though.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function.

Returns: Gnome::Glib::Quark representing the error domain

method domain-register (
  Str $error_type_name, UInt $error_type_private_size,
  N-GError() $error_type_init, N-GError() $error_type_copy,
  N-GError() $error_type_clear
  --> UInt
)

  • $error_type_name; string to create a Gnome::Glib::Quark from

  • $error_type_private_size; size of the private error data in bytes

  • $error_type_init; function initializing fields of the private error data

  • $error_type_copy; function copying fields of the private error data

  • $error_type_clear; function freeing fields of the private error data

domain-register-static

This function registers an extended Gnome::Glib::Error domain.

error_type_name should not be freed. error_type_private_size must be greater than 0.

error_type_init receives an initialized Gnome::Glib::Error and should then initialize the private data.

error_type_copy is a function that receives both original and a copy Gnome::Glib::Error and should copy the fields of the private error data. The standard Gnome::Glib::Error fields are already handled.

error_type_clear receives the pointer to the error, and it should free the fields of the private error data. It should not free the struct itself though.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function.

Returns: Gnome::Glib::Quark representing the error domain

method domain-register-static ( Str $error_type_name, UInt $error_type_private_size, N-GError $error_type_init, N-GError $error_type_copy, N-GError $error_type_clear --> UInt )

  • $error_type_name; static string to create a Gnome::Glib::Quark from

  • $error_type_private_size; size of the private error data in bytes

  • $error_type_init; function initializing fields of the private error data

  • $error_type_copy; function copying fields of the private error data

  • $error_type_clear; function freeing fields of the private error data

message

Return the error message in the error object. Returns Str if object is invalid.

method message ( --> Str )

matches

Returns 1 if Gnome::Glib::Error> matches $domain and $code, 0 otherwise. In particular, when error is Any, 0 will be returned.

method matches ( GQuark $domain, Int $code --> Bool )

  • $domain; an error domain

  • $code; an error code

prefix-error

Formats a string according to format and prefix it to an existing error message. If err is undefined (ie: no error variable) then do nothing.

If *err is undefined (ie: an error variable is present but there is no error condition) then also do nothing.

method prefix-error ( Str $format )

  • $format; printf()-style format string @...: arguments to format

  • $3;

prefix-error-literal

Prefix $prefix to an existing error message. This error must be a valid error to work, nothing will be done otherwise.

method prefix_error-literal ( Str $prefix )

  • $prefix; a string to prefix the error. The message of this error is modified. If you want to keep the original message, make a copy first.

[g_] propagate_error

If dest is Any, free src; otherwise, moves src into dest. The error variable dest points to must be Any.

src must be defined.

Note that src is no longer valid after this call. If you want to keep using the same GError*, you need to set it to Any after calling this function on it.

method g_propagate_error ( N-GObject $src )

  • N-GObject $src; (transfer full): error to move into the return location

[g_] propagate_prefixed_error

If dest is Any, free src; otherwise, moves src into *dest. *dest must be Any. After the move, add a prefix as with g_prefix_error().

Since: 2.16

method g_propagate_prefixed_error ( N-GObject $src, Str $format,  $4 )

  • N-GObject $src; error to move into the return location

  • Str $format; printf()-style format string @...: arguments to format

  • $4;

set_error

Does nothing if err is Any; if err is non-Any, then err must be Any. A new N-GError is created and assigned to err. message is like in g_error_new() filtered from percent characters. For these strings please use g_set_error_literal().

method g_set_error ( UInt $domain, Int $code, Str $error-message --> Int)

  • UInt $domain; error domain

  • Int $code; error code

  • Str $error-message

set-error-literal

Does nothing if err is undefined; if err is non-undefined, then *err must be undefined. A new Gnome::Glib::Error is created and assigned to *err. Unlike g_set_error(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

method set-error-literal ( GQuark $domain, Int() $code, Str $message )

  • $domain; error domain

  • $code; error code

  • $message; error message

_g_error_new

Creates a new N-GError with the given domain, code and a error-message. Originally the message is a printf like string followed with variables to be substituted in the format string. This can be easily solved in Raku and is therefore simplified here. A warning; every percent character is substituted with the text 'percent-filtered-out' to prevent crashes in the C function. If needed please use g_error_new_literal().

Returns: a new N-GError

method g_error_new ( UInt $domain, Int $code, Str $format --> N-GError)

  • N-GObject $domain; error domain

  • Int $code; error code

  • Str $error-message; the message

new_literal

Creates a new N-GError.

method g_error_new_literal (
  UInt $domain, Int $code, Str $message --> N-GError
)

  • UInt $domain; error domain

  • Int $code; error code

  • Str $message; error message

new_valist

Creates a new N-GError with the given domain and code, and a message formatted with format.

Returns: a new N-GError

method new_valist (
  N-GObject $domain, Int $code, Str $format,
  $va_list args G_GNUC_PRINTF3,  $0 --> N-GObject
)

  • N-GObject $domain; error domain

  • Int $code; error code

  • Str $format; printf()-style format for error message

  • $va_list args G_GNUC_PRINTF3; va_list of parameters for the message format

  • $0;