{-# LANGUAGE ScopedTypeVariables,DeriveDataTypeable #-}{-# LINE 2 "./System/Glib/GError.chs" #-}-- -*-haskell-*--- GIMP Toolkit (GTK) GError API---- Author : Duncan Coutts---- Created: 2 July 2004---- Copyright (C) 2004 Duncan Coutts-- parts derived from Structs.hsc Copyright (c) 1999..2002 Axel Simon---- This library is free software; you can redistribute it and/or-- modify it under the terms of the GNU Lesser General Public-- License as published by the Free Software Foundation; either-- version 2.1 of the License, or (at your option) any later version.---- This library is distributed in the hope that it will be useful,-- but WITHOUT ANY WARRANTY; without even the implied warranty of-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU-- Lesser General Public License for more details.---- |-- Maintainer : gtk2hs-users@lists.sourceforge.net-- Stability : provisional-- Portability : portable (depends on GHC)---- 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.--moduleSystem.Glib.GError(-- * Data types--GError(..),GErrorDomain,GErrorCode,GErrorMessage,-- * 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 'Control.Exception.catch' and 'Control.Exception.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,catchGErrorJustDomain,handleGErrorJust,handleGErrorJustDomain,-- ** DeprecatedcatchGError,handleGError,failOnGError,throwGError,-- * 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'.GErrorClass(..),propagateGError,checkGError)whereimportForeignimportForeign.CimportSystem.Glib.UTFStringimportControl.ExceptionimportData.TypeableimportPreludehiding(catch)-- | A GError consists of a domain, code and a human readable message.dataGError=GError!GErrorDomain!GErrorCode!GErrorMessagederivingTypeableinstanceShowGErrorwhereshow(GError__msg)=msginstanceExceptionGErrortypeGQuark=(CUInt){-# LINE 108 "./System/Glib/GError.chs" #-}-- | 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.typeGErrorDomain=GQuark-- | 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.typeGErrorCode=Int-- | A human readable error message.typeGErrorMessage=StringinstanceStorableGErrorwheresizeOf_=12{-# LINE 128 "./System/Glib/GError.chs" #-}alignment_=alignment(undefined::GQuark)peekptr=do(domain::GQuark)<-(\ptr->do{peekByteOffptr0::IOCUInt})ptr(code::(CInt))<-(\ptr->do{peekByteOffptr4::IOCInt})ptr(msgPtr::CString)<-(\ptr->do{peekByteOffptr8::IO(PtrCChar)})ptrmsg<-peekUTFStringmsgPtrreturn$GError(fromIntegraldomain)(fromIntegralcode)msgpoke_=error"GError::poke: not implemented"-- | 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 'Graphics.UI.Gtk.Gdk.Pixbuf.PixbufError':---- > instance GErrorClass PixbufError where-- > gerrorDomain _ = {#call pure unsafe pixbuf_error_quark#}--classEnumerr=>GErrorClasserrwheregerrorDomain::err->GErrorDomain-- ^ This must not use the value of its-- parameter so that it is safe to pass-- 'undefined'.-- | 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--propagateGError::(Ptr(Ptr())->IOa)->IOapropagateGErroraction=checkGErroractionthrowGError-- | 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) -> ...)--checkGError::(Ptr(Ptr())->IOa)->(GError->IOa)->IOacheckGErroractionhandler=alloca$\(errPtrPtr::Ptr(PtrGError))->dopokeerrPtrPtrnullPtrresult<-action(castPtrerrPtrPtr)errPtr<-peekerrPtrPtriferrPtr==nullPtrthenreturnresultelsedogerror<-peekerrPtrg_error_free(castPtrerrPtr)handlergerror-- | Use this if you need to explicitly throw a GError or re-throw an existing-- GError that you do not wish to handle.throwGError::GError->IOathrowGError=throw{-# DEPRECATED throwGError "Use ordinary Control.Exception.throw" #-}-- | 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)--catchGError::IOa-- ^ The computation to run->(GError->IOa)-- ^ Handler to invoke if an exception is raised->IOacatchGError=catch{-# DEPRECATED catchGError "Use ordinary Control.Exception.catch" #-}-- | 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)--catchGErrorJust::GErrorClasserr=>err-- ^ The error to catch->IOa-- ^ The computation to run->(GErrorMessage->IOa)-- ^ Handler to invoke if an exception is raised->IOacatchGErrorJustcodeactionhandler=catchactionhandler'wherehandler'gerror@(GErrordomaincode'msg)|fromIntegraldomain==gerrorDomaincode&&code'==fromEnumcode=handlermsg|otherwise=throwgerror-- | 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 -> ...-- > _ -> ...)--catchGErrorJustDomain::GErrorClasserr=>IOa-- ^ The computation to run->(err->GErrorMessage->IOa)-- ^ Handler to invoke if an exception is raised->IOacatchGErrorJustDomainaction(handler::err->GErrorMessage->IOa)=catchactionhandler'wherehandler'gerror@(GErrordomaincodemsg)|fromIntegraldomain==gerrorDomain(undefined::err)=handler(toEnumcode)msg|otherwise=throwGErrorgerror-- | A verson of 'catchGError' with the arguments swapped around.---- > handleGError (\(GError dom code msg) -> ...) $-- > ...--handleGError::(GError->IOa)->IOa->IOahandleGError=handle{-# DEPRECATED handleGError "Use ordinary Control.Exception.handle" #-}-- | A verson of 'handleGErrorJust' with the arguments swapped around.handleGErrorJust::GErrorClasserr=>err->(GErrorMessage->IOa)->IOa->IOahandleGErrorJustcode=flip(catchGErrorJustcode)-- | A verson of 'catchGErrorJustDomain' with the arguments swapped around.handleGErrorJustDomain::GErrorClasserr=>(err->GErrorMessage->IOa)->IOa->IOahandleGErrorJustDomain=flipcatchGErrorJustDomain-- | Catch all GError exceptions and convert them into a general failure.failOnGError::IOa->IOafailOnGErroraction=catchGErroraction(\(GErrordomcodemsg)->failmsg)foreignimportccallunsafe"g_error_free"g_error_free::((Ptr())->(IO()))