haskell-gi-base-0.21.1: Foundation for libraries generated by haskell-gi

Safe HaskellNone
LanguageHaskell98

Data.GI.Base.GError

Contents

Description

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

To catch just a single specific error use catchGErrorJust / handleGErrorJust. To catch any error in a particular error domain use catchGErrorJustDomain / handleGErrorJustDomain

For convenience, generated code also includes specialized variants of catchGErrorJust / handleGErrorJust for each error type. For example, for errors of type PixbufError one could invoke catchPixbufError / handlePixbufError. The definition is simply

catchPixbufError :: IO a -> (PixbufError -> GErrorMessage -> IO a) -> IO a
catchPixbufError = catchGErrorJustDomain

Notice that the type is suitably specialized, so only errors of type PixbufError will be caught.

Synopsis

Unpacking GError

newtype GError Source #

A GError, consisting of a domain, code and a human readable message. These can be accessed by gerrorDomain, gerrorCode and gerrorMessage below.

Constructors

GError (ManagedPtr GError) 
Instances
Show GError Source # 
Instance details
Exception GError Source # 
Instance details
BoxedObject GError Source # 
Instance details

gerrorDomain :: GError -> IO GQuark Source #

Return the domain for the given GError. This is a GQuark, a textual representation can be obtained with quarkToString.

gerrorCode :: GError -> IO GErrorCode Source #

The numeric code for the given GError.

gerrorMessage :: GError -> IO GErrorMessage Source #

A text message describing the GError.

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 = Int32 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 enumeration 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

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.

Creating new GErrors

Implementation specific details

The following are used in the implementation of the bindings, and are in general not necessary for using the API.

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.

Example for PixbufError:

instance GErrorClass PixbufError where
  gerrorClassDomain _ = "gdk-pixbuf-error-quark"

Minimal complete definition

gerrorClassDomain

Methods

gerrorClassDomain Source #

Arguments

:: err 
-> Text

This must not use the value of its parameter so that it is safe to pass undefined.

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

Run the given function catching possible GErrors in its execution. If a GError is emitted this throws the corresponding exception.

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

Like propagateGError, but allows to specify a custom handler instead of just throwing the exception.

maybePokeGError :: Ptr (Ptr GError) -> Maybe GError -> IO () Source #

If the passed in Maybe GError is not Nothing, store a copy in the passed in pointer, unless the pointer is nullPtr.