glib-0.13.2.1: Binding to the GLIB library for Gtk2Hs.

Maintainer | gtk2hs-users@lists.sourceforge.net
Stability | provisional
Portability | portable (depends on GHC)
Safe Haskell | None
Language | Haskell98

System.Glib.GError

Contents

- Data types
- Catching GError exceptions
  - Deprecated
- Checking for GErrors returned by glib/gtk functions

Description

Error Reporting, glib's system for reporting errors.

`GError`s are used by glib to report recoverable runtime errors.

This module provides functions for checking glib/gtk functions that report `GError`s. It also provides functions for throwing and catching `GError`s as Haskell exceptions.

Synopsis

- data GError = GError !GErrorDomain !GErrorCode !GErrorMessage
- type GErrorDomain = GQuark
- type GErrorCode = Int
- type GErrorMessage = Text
- catchGErrorJust :: GErrorClass err => err -> IO a -> (GErrorMessage -> IO a) -> IO a
- catchGErrorJustDomain :: GErrorClass err => IO a -> (err -> GErrorMessage -> IO a) -> IO a
- handleGErrorJust :: GErrorClass err => err -> (GErrorMessage -> IO a) -> IO a -> IO a
- handleGErrorJustDomain :: GErrorClass err => (err -> GErrorMessage -> IO a) -> IO a -> IO a
- catchGError :: IO a -> (GError -> IO a) -> IO a
- handleGError :: (GError -> IO a) -> IO a -> IO a
- failOnGError :: IO a -> IO a
- throwGError :: GError -> IO a
- class Enum err => GErrorClass err where
  - gerrorDomain :: err -> GErrorDomain
- propagateGError :: (Ptr (Ptr ()) -> IO a) -> IO a
- checkGError :: (Ptr (Ptr ()) -> IO a) -> (GError -> IO a) -> IO a

# Data types

data GError Source

A GError consists of a domain, code and a human readable message.

Constructors

GError !GErrorDomain !GErrorCode !GErrorMessage |

Instances

Show GError Source |
Storable GError Source |
Exception GError Source |

type GErrorDomain = GQuark Source

A code used to identify the 'namespace' of the error. Within each error domain all the error codes are defined in an enumeration. Each gtk/gnome module that uses GErrors has its own error domain. The rationale behind using error domains is so that each module can organise its own error codes without having to coordinate on a global error code list.

type GErrorCode = Int Source

A code to identify a specific error within a given `GErrorDomain`. Most of time you will not need to deal with this raw code since there is an enumeration type for each error domain. Of course which enumeraton to use depends on the error domain, but if you use `catchGErrorJustDomain` or `handleGErrorJustDomain`, this is worked out for you automatically.

type GErrorMessage = Text Source

A human readable error message.

# Catching GError exceptions

To catch GError exceptions thrown by Gtk2Hs functions use the catchGError* or handleGError* functions. They work in a similar way to the standard `catch` and `handle` functions.

`catchGError` / `handleGError` catches all GError exceptions, you provide a handler function that gets given the GError if an exception was thrown. This is the most general but is probably not what you want most of the time. It just gives you the raw error code rather than a Haskell enumeration of the error codes. Most of the time you will only want to catch a specific error or any error from a specific error domain. To catch just a single specific error use `catchGErrorJust` / `handleGErrorJust`. To catch any error in a particular error domain use `catchGErrorJustDomain` / `handleGErrorJustDomain`

catchGErrorJust Source

Arguments

:: GErrorClass err |
=> err | The error to catch
-> IO a | The computation to run
-> (GErrorMessage -> IO a) | Handler to invoke if an exception is raised
-> IO a |

This will catch just a specific GError exception. If you need to catch a range of related errors, `catchGErrorJustDomain` is probably more appropriate. Example:

    do image <- catchGErrorJust PixbufErrorCorruptImage
    loadImage
    (\errorMessage -> do log errorMessage
    return mssingImagePlaceholder)

catchGErrorJustDomain Source

Arguments

:: GErrorClass err |
=> IO a | The computation to run
-> (err -> GErrorMessage -> IO a) | Handler to invoke if an exception is raised
-> IO a |

Catch all GErrors from a particular error domain. The handler function should just deal with one error enumeration type. If you need to catch errors from more than one error domain, use this function twice with an appropriate handler functions for each.

    catchGErrorJustDomain
    loadImage
    (\err message -> case err of
    PixbufErrorCorruptImage -> ...
    PixbufErrorInsufficientMemory -> ...
    PixbufErrorUnknownType -> ...
    _ -> ...)

handleGErrorJust :: GErrorClass err => err -> (GErrorMessage -> IO a) -> IO a -> IO a Source

A verson of `handleGErrorJust` with the arguments swapped around.

handleGErrorJustDomain :: GErrorClass err => (err -> GErrorMessage -> IO a) -> IO a -> IO a Source

A verson of `catchGErrorJustDomain` with the arguments swapped around.

## Deprecated

catchGError Source

Arguments

:: IO a | The computation to run
-> (GError -> IO a) | Handler to invoke if an exception is raised
-> IO a |

Deprecated: Use ordinary Control.Exception.catch

This will catch any GError exception. The handler function will receive the raw GError. This is probably only useful when you want to take some action that does not depend on which GError exception has occured, otherwise it would be better to use either `catchGErrorJust` or `catchGErrorJustDomain`. For example:

    catchGError
    (do ...
    ...)
    (\(GError dom code msg) -> fail msg)

handleGError :: (GError -> IO a) -> IO a -> IO a Source

Deprecated: Use ordinary Control.Exception.handle

A verson of `catchGError` with the arguments swapped around.

    handleGError (\(GError dom code msg) -> ...) $
    ...

failOnGError :: IO a -> IO a Source

Catch all GError exceptions and convert them into a general failure.

throwGError :: GError -> IO a Source

Deprecated: Use ordinary Control.Exception.throw

Use this if you need to explicitly throw a GError or re-throw an existing GError that you do not wish to handle.

# Checking for GErrors returned by glib/gtk functions

- Note, these functions are only useful to implementors

If you are wrapping a new API that reports `GError`s you should probably use `propagateGError` to convert the GError into an exception. You should also note in the documentation for the function that it throws GError exceptions and the Haskell enumeration for the expected glib GError domain(s), so that users know what exceptions they might want to catch.

If you think it is more appropriate to use an alternate return value (eg Either/Maybe) then you should use `checkGError`.

class Enum err => GErrorClass err where Source

Each error domain's error enumeration type should be an instance of this class. This class helps to hide the raw error and domain codes from the user. This interface should be implemented by calling the approrpiate `{error_domain}_error_quark`. It is safe to use a pure FFI call for this.

Example for `PixbufError`:

    instance GErrorClass PixbufError where
    gerrorDomain _ = {#call pure unsafe pixbuf_error_quark#}

Methods

gerrorDomain Source

Arguments

:: err |
-> GErrorDomain | This must not use the value of its parameter so that it is safe to pass `undefined`.

propagateGError :: (Ptr (Ptr ()) -> IO a) -> IO a Source

Glib functions which report `GError`s take as a parameter a `GError **error`. Use this function to supply such a parameter. It checks if an error was reported and if so throws it as a Haskell exception.

Example of use:

    propagateGError $ \gerrorPtr ->
    {# call g_some_function_that_might_return_an_error #} a b gerrorPtr

checkGError :: (Ptr (Ptr ()) -> IO a) -> (GError -> IO a) -> IO a Source

Like `propagateGError` but instead of throwing the GError as an exception handles the error immediately using the supplied error handler.

Example of use:

    checkGError
    (\gerrorPtr -> {# call g_some_function_that_might_return_an_error #} a b gerrorPtr)
    (\(GError domain code msg) -> ...)