From bdf8228f2399628669d897717e5ef30c64ed32b1 Mon Sep 17 00:00:00 2001 From: Reiner Pope Date: Thu, 29 Mar 2012 15:32:39 +1030 Subject: [PATCH] Documentation --- .../System/CoreFoundation/Array/Mutable.chs | 11 ++++ .../System/CoreFoundation/Bundle.chs | 34 ++++++++++- .../System/CoreFoundation/Error.chs | 58 +++++++++++++++---- .../CoreFoundation/NotificationCenter.chs | 41 ++++++++++++- .../System/CoreFoundation/Number.chs | 10 +++- 5 files changed, 138 insertions(+), 16 deletions(-) diff --git a/CoreFoundation/System/CoreFoundation/Array/Mutable.chs b/CoreFoundation/System/CoreFoundation/Array/Mutable.chs index c7af570..a7cb541 100644 --- a/CoreFoundation/System/CoreFoundation/Array/Mutable.chs +++ b/CoreFoundation/System/CoreFoundation/Array/Mutable.chs @@ -19,6 +19,7 @@ import System.CoreFoundation.Foreign #include +-- | Mutable arrays type MArray s a = Mutable s (Array a) type MArrayRef = Ptr (MutableRepr CFArray) @@ -40,9 +41,19 @@ getCount arr = unsafePrimToPrim $ c_getCount arr {#fun unsafe CFArrayGetCount as c_getCount { withMutableObject* `Mutable s (Array a)' } -> `Int' #} +{- | +Construct an empty array with the given capacity. + + [capacity] The maximum number of values that can be contained by the new array. The array starts empty and can grow to this number of values (and it can have less). Pass 0 to specify that the maximum capacity is not limited. The value must not be negative. +-} newMutableArray :: (PrimMonad m, Object a) => Int -> m (MArray (PrimState m) a) newMutableArray n = unsafePrimToPrim . getOwned $ cfNewMutableArray n +{- | +Adds a value to an array giving it the new largest index. If the array is a limited-capacity array and it is full before this operation, the behavior is undefined. + + [Discussion] The value parameter is assigned to the index one larger than the previous largest index and the count of the Array is increased by one. +-} appendValue :: (PrimMonad m, Object a) => MArray (PrimState m) a -> a -> m () appendValue arr v = unsafePrimToPrim $ c_appendValue arr v diff --git a/CoreFoundation/System/CoreFoundation/Bundle.chs b/CoreFoundation/System/CoreFoundation/Bundle.chs index 0c200b6..9d46fa2 100644 --- a/CoreFoundation/System/CoreFoundation/Bundle.chs +++ b/CoreFoundation/System/CoreFoundation/Bundle.chs @@ -26,12 +26,18 @@ import Control.DeepSeq declareCFType "Bundle" {#pointer CFBundleRef as BundleRef nocode#} +{- | +Returns an application’s main bundle. +-} {#fun CFBundleGetMainBundle as getMainBundle { } -> `Bundle' getAndRetain* #} {#fun CFBundleCopyExecutableURL as cfGetExecutableURL { withObject* `Bundle' } -> `URLRef' id #} +{- | +Returns the location of a bundle’s main executable code. +-} getExecutableURL :: Bundle -> IO URL getExecutableURL bundle = getOwned $ cfGetExecutableURL bundle @@ -39,6 +45,12 @@ getExecutableURL bundle = getOwned $ cfGetExecutableURL bundle { withObject* `Bundle' , withObject* `String' } -> `URLRef' id #} +{- | +Returns the location of a bundle’s auxiliary executable code. + + [Discussion] This function can be used to find executables other than your main executable. This is useful, for instance, for applications that have some command line tool that is packaged with and used by the application. The tool can be packaged in the various platform executable directories in the bundle and can be located with this function. This allows an application to ship versions of the tool for each platform as it does for the main application executable. + +-} getAuxiliaryExecutableURL :: Bundle -> String -> IO URL getAuxiliaryExecutableURL bundle str = getOwned $ cfGetAuxiliaryExecutableURL bundle str @@ -49,7 +61,27 @@ getAuxiliaryExecutableURL bundle str = getOwned $ cfGetAuxiliaryExecutableURL bu , withMaybeObject* `Maybe String' } -> `URLRef' id #} -getResourceURL :: Bundle -> String -> Maybe String -> Maybe String -> IO URL +{- | +Returns the location of a resource contained in the specified bundle. + +For example, if a bundle contains a subdirectory WaterSounds that includes a file Water1.aiff, you can retrieve the URL for the file using + +> getResourceURL bundle "Water1" (Just "aiff") (Just "WaterSounds") + +-} +getResourceURL :: + Bundle + -- ^ The bundle to examine. + + -> String + -- ^ The name of the requested resource + -> Maybe String + -- ^ The abstract type of the requested resource. The type is expressed as a filename extension, such as jpg. Pass @Nothing@ if you don't need to search by type. + + -> Maybe String + -- ^ The name of the subdirectory of the bundle's resources directory to search. Pass @Nothing@ to search the standard Bundle resource locations. + + -> IO URL getResourceURL a b c d = getOwned $ cfGetResourceURL a b c d deriving instance Typeable Bundle diff --git a/CoreFoundation/System/CoreFoundation/Error.chs b/CoreFoundation/System/CoreFoundation/Error.chs index 96af941..b5e7a35 100644 --- a/CoreFoundation/System/CoreFoundation/Error.chs +++ b/CoreFoundation/System/CoreFoundation/Error.chs @@ -2,9 +2,11 @@ -- It is toll-free bridged with the @NSData@ type. module System.CoreFoundation.Error ( -- * The Error type + -- $error Error, ErrorRef, - cfError, + mkError, + ErrorCode, -- * Error properties errorDescription, errorFailureReason, @@ -13,6 +15,7 @@ module System.CoreFoundation.Error ( errorDomain, errorCode, -- * Error domains + ErrorDomain, domainPOSIX, domainOSStatus, domainMach, @@ -38,12 +41,19 @@ import System.CoreFoundation.Foreign import System.CoreFoundation.Internal.TH import Data.Typeable import Control.DeepSeq +import Control.Exception #include declareCFType "Error" {#pointer CFErrorRef as ErrorRef nocode#} +{- $error +An 'Error' object encapsulates rich and extensible error information than is possible using only an error code or error string. The core attributes of an 'Error' object are an error domain (represented by a string), a domain-specific error code and a user info dictionary containing application specific information. Errors are required to have a domain and an error code within that domain. The optional 'userInfo' dictionary may provide additional information that might be useful for the interpretation and reporting of the error. This dictionary can even contain an \"underlying\" error, which is wrapped as an error bubbles up through various layers. See for further details. + +The 'Error' type is an instance of 'Exception', so it may be thrown using 'throw'. +-} + importCFStringAs "kCFErrorLocalizedDescriptionKey" "localizedDescriptionKey" importCFStringAs "kCFErrorLocalizedFailureReasonKey" "localizedFailureReasonKey" importCFStringAs "kCFErrorLocalizedRecoverySuggestionKey" "localizedRecoverySuggestionKey" @@ -55,41 +65,68 @@ importCFStringAs "kCFErrorDomainOSStatus" "domainOSStatus" importCFStringAs "kCFErrorDomainMach" "domainMach" importCFStringAs "kCFErrorDomainCocoa" "domainCocoa" +-- | Error domains +type ErrorDomain = String +domainPOSIX, domainOSStatus, domainMach, domainCocoa :: ErrorDomain + +-- | Error codes +type ErrorCode = CFIndex + {#fun CFErrorCreate as newError { withDefaultAllocator- `AllocatorPtr' , withObject* `String' - , `Int' - , maybeWithObject* `Maybe (Dictionary k v)' + , id `ErrorCode' + , maybeWithObject* `Maybe (Dictionary DynObj DynObj)' } -> `ErrorRef' id #} -cfError :: String -- ^ The error domain. - -> Int -- ^ The error code. - -> Maybe (Dictionary k v) -- ^ User info. +-- | Construct a new error +mkError :: ErrorDomain -- ^ The error domain. + -> ErrorCode -- ^ The error code. + -> Maybe (Dictionary DynObj DynObj) -- ^ User info. -> Error -cfError domain code userInfo = unsafePerformIO $ getOwned +mkError domain code userInfo = unsafePerformIO $ getOwned $ newError domain code userInfo maybeWithObject Nothing = ($ nullPtr) maybeWithObject (Just o) = withObject o +{- | +Returns a human-presentable description for a given error. This is a complete sentence or two which says what failed and why it failed. The structure of the description depends on the details provided in the user info dictionary. See for the precise rules used. +-} {#fun pure CFErrorCopyDescription as errorDescription { withObject* `Error' } -> `String' getAndRetain* #} -- The docs say that the CFErrorCopyDescription will never return NULL. +{- | +Returns a human-presentable failure reason for a given error. See for details. + +-} {#fun pure CFErrorCopyFailureReason as errorFailureReason { withObject* `Error' } -> `Maybe String' maybeGetAndRetain* #} +{- | +Returns a human presentable recovery suggestion for a given error. See for details. +-} {#fun pure CFErrorCopyRecoverySuggestion as errorRecoverySuggestion { withObject* `Error' } -> `Maybe String' maybeGetAndRetain* #} +{- | +Returns the user info dictionary. +-} {#fun pure CFErrorCopyUserInfo as userInfo - { withObject* `Error' } -> `Maybe (Dictionary k v)' maybeGetAndRetain* #} + { withObject* `Error' } -> `Maybe (Dictionary DynObj DynObj)' maybeGetAndRetain* #} +{- | +Returns the error domain. +-} {#fun pure CFErrorGetDomain as errorDomain - { withObject* `Error' } -> `String' getAndRetain* #} + { withObject* `Error' } -> `ErrorDomain' getAndRetain* #} +{- | +Returns the error code. +-} {#fun pure CFErrorGetCode as errorCode - { withObject* `Error' } -> `CFIndex' id #} + { withObject* `Error' } -> `ErrorCode' id #} toPair :: Error -> (String, CFIndex) toPair err = (errorDomain err, errorCode err) @@ -102,3 +139,4 @@ instance Ord Error where compare a b = compare (toPair a) (toPair b) instance Show Error where show = getChars . errorDescription +instance Exception Error diff --git a/CoreFoundation/System/CoreFoundation/NotificationCenter.chs b/CoreFoundation/System/CoreFoundation/NotificationCenter.chs index 7e444e9..88aaa0e 100644 --- a/CoreFoundation/System/CoreFoundation/NotificationCenter.chs +++ b/CoreFoundation/System/CoreFoundation/NotificationCenter.chs @@ -1,4 +1,8 @@ --- | Notification centers. This is *not* toll-free bridged with @NSNotificationCenter@. +{- | Notification centers. This is *not* toll-free bridged with @NSNotificationCenter@. + +A 'NotificationCentre' object provides the means by which you can send a message, or notification, to any number of recipients, or observers, without having to know anything about the recipients. A notification message consists of a notification name (a 'String'), a pointer value that identifies the object posting the notification, and an optional dictionary that contains additional information about the particular notification. See for further details. +-} + module System.CoreFoundation.NotificationCenter ( NotificationCenter, NotificationCenterRef, @@ -6,6 +10,7 @@ module System.CoreFoundation.NotificationCenter ( postNotification, ) where +import Foreign.Marshal import Foreign.Ptr import Foreign.C import Prelude hiding (String) @@ -24,15 +29,45 @@ import System.CoreFoundation.Internal.TH declareCFType "NotificationCenter" {#pointer CFNotificationCenterRef as NotificationCenterRef nocode#} +{- | +Returns the application's local notification center. An application has only one local notification center, so this function returns the same value each time it is called. +-} {#fun CFNotificationCenterGetLocalCenter as getLocalCenter { } -> `NotificationCenter' getAndRetain* #} -{#fun CFNotificationCenterPostNotification as postNotification +-- | Posts a notification for an object. For more details, see +postNotification :: + NotificationCenter + -- ^ The notification center to post the notification. + + -> String + -- ^ The name of the notification to post. + + -> Ptr () + -- ^ The object posting the notification. + + -> Maybe (Dictionary k v) + -- ^ A dictionary passed to observers. You populate + -- this dictionary with additional information describing + -- the notification. For distributed notifications, the + -- dictionary must contain only property list objects. + + -> Bool + -- ^ If True, the notification is delivered to all observers + -- immediately, even if some observers are in suspended + -- (background) applications and they requested different + -- suspension behavior when registering for the notification. + -- If False, each observer’s requested suspension behavior is respected. + + -> IO () +postNotification = cfPostNotification + +{#fun CFNotificationCenterPostNotification as cfPostNotification { withObject* `NotificationCenter' , withObject* `String' , id `Ptr ()' , withMaybeObject* `Maybe (Dictionary k v)' - , id `CBoolean' + , `Bool' } -> `()' #} deriving instance Typeable NotificationCenter diff --git a/CoreFoundation/System/CoreFoundation/Number.chs b/CoreFoundation/System/CoreFoundation/Number.chs index 6f599aa..4c8583e 100644 --- a/CoreFoundation/System/CoreFoundation/Number.chs +++ b/CoreFoundation/System/CoreFoundation/Number.chs @@ -1,14 +1,19 @@ -- | 'Number' is a class which wraps basic C scalar (numeric) types. -- It is toll-free bridged with 'NSNumber'. module System.CoreFoundation.Number( + -- * Types Number, NumberRef, + -- * Converting to basic types number, value, + NumberType(..), numberType, IsNumberType, - NumberType(..), isFloatType, + -- * Simple view + NumberView, + viewNumber, ) where import Foreign.Ptr @@ -56,7 +61,7 @@ declareCFType "Number" , kCFNumberCGFloatType as CGFloatType } deriving (Show,Eq) #} --- Returns the type used by the 'Number' object to store its value. +-- | Returns the type used by the 'Number' object to store its value. -- -- The type specified by 'number' is not necessarily preserved when -- a new 'Number' is created --- it uses whatever internal storage type @@ -144,6 +149,7 @@ value n = unsafePerformIO $ alloca $ \p -> do , castPtr `Ptr a' } -> `NumberRef' id #} +-- | Convert to a 'Number'. number :: forall a . IsNumberType a => a -> Number number n = unsafePerformIO $ with n $ \np -> getOwned $ cfNumberCreate (numberTypeOf (undefined :: a)) np