diff --git a/Setup.hs b/Setup.hs --- a/Setup.hs +++ b/Setup.hs @@ -1,3 +1,21 @@ -import Distribution.Simple +#! /usr/bin/env runhaskell -main = defaultMain +{-# OPTIONS -Wall #-} + +import Distribution.Simple ( defaultMainWithHooks + , simpleUserHooks + , UserHooks(haddockHook) + ) +import Distribution.Simple.Setup ( HaddockFlags ) +import Distribution.Simple.Program ( userSpecifyArgs ) +import Distribution.Simple.LocalBuildInfo ( LocalBuildInfo(withPrograms) ) +import Distribution.PackageDescription ( PackageDescription ) + +main :: IO () +main = defaultMainWithHooks $ simpleUserHooks { haddockHook = haddockHook' } + +-- Define __HADDOCK__ for CPP when running haddock. +haddockHook' :: PackageDescription -> LocalBuildInfo -> UserHooks -> HaddockFlags -> IO () +haddockHook' pkg lbi = haddockHook simpleUserHooks pkg $ lbi { withPrograms = p } + where + p = userSpecifyArgs "haddock" ["--optghc=-D__HADDOCK__"] (withPrograms lbi) diff --git a/System/USB/Safe.hs b/System/USB/Safe.hs --- a/System/USB/Safe.hs +++ b/System/USB/Safe.hs @@ -11,6 +11,7 @@ , EmptyDataDecls , ViewPatterns , NamedFieldPuns + , CPP #-} ------------------------------------------------------------------------------- @@ -200,7 +201,7 @@ -- from MonadCatchIO-transformers: import Control.Monad.CatchIO ( MonadCatchIO, bracket_, throw ) --- from unicode-symbols: +-- from base-unicode-symbols: import Data.Bool.Unicode ( (∧) ) import Data.Eq.Unicode ( (≡) ) import Data.Function.Unicode ( (∘) ) @@ -273,15 +274,15 @@ , readBulk, readInterrupt , writeBulk, writeInterrupt ) +#ifdef __HADDOCK__ +import System.USB.Exceptions ( USBException(..) ) +#endif + -- from regions: -import Control.Monad.Trans.Region +import Control.Resource ( Resource, Handle, openResource, closeResource ) +import Control.Monad.Trans.Region.Unsafe ( internalHandle ) +import Control.Monad.Trans.Region -- (re-exported entirely) -import Control.Monad.Trans.Region.Unsafe ( Resource - , Handle - , openResource - , closeResource - , internalHandle - ) -------------------------------------------------------------------------------- -- * Device regions @@ -367,12 +368,12 @@ Exceptions: - * 'NotFoundException' if re-enumeration is required, or if the - device has been disconnected. - * 'SettingAlreadySet' if a configuration has been set using 'setConfig', 'useActiveConfig' and 'setConfigWhich'. + * 'NotFoundException' if re-enumeration is required, or if the + device has been disconnected. + * Another 'USBException'. -} resetDevice ∷ (pr `ParentOf` cr, MonadIO cr) @@ -395,6 +396,9 @@ Note that, just like a regional device handle, a configuration can be duplicated to a parent region using 'dup'. + +Also note that you can get the descriptor of the configuration by applying +'getDesc' to it. -} data Config (r ∷ * → *) = Config (RegionalDeviceHandle r) USB.ConfigDesc @@ -441,8 +445,8 @@ data ConfigHandle sCfg = ConfigHandle (Handle USB.Device) USB.ConfigDesc -{-| Set the active configuration for a device and then apply the given function -to the resulting configuration handle. +{-| Set the active configuration for a device and then apply the given +continuation function to the resulting configuration handle. USB devices support multiple configurations of which only one can be active at any given time. When a configuration is set using 'setConfig', 'useActiveConfig' @@ -468,16 +472,17 @@ Exceptions: + * 'SettingAlreadySet' if a configuration has already been set using + 'setConfig', 'useActiveConfig' or 'setConfigWhich'. + * 'BusyException' if interfaces are currently claimed. * 'NoDeviceException' if the device has been disconnected - * 'SettingAlreadySet' if a configuration has already been set using - 'setConfig', 'useActiveConfig' or 'setConfigWhich'. - * Another 'USBException'. -} -setConfig ∷ (pr `ParentOf` cr, MonadCatchIO cr) +setConfig ∷ ∀ pr cr α + . (pr `ParentOf` cr, MonadCatchIO cr) ⇒ Config pr -- ^ The configuration you wish to set. → (∀ sCfg. ConfigHandle sCfg → cr α) -- ^ Continuation function. → cr α @@ -517,8 +522,8 @@ instance Exception SettingAlreadySet -{-| Apply the given function to the configuration handle of the current active -configuration of the given device handle. +{-| Apply the given continuation function to the configuration handle of the +current active configuration of the given device handle. This function needs to determine the current active configuration. This information may be cached by the operating system. If it isn't cached this @@ -527,16 +532,17 @@ Exceptions: - * 'NoDeviceException' if the device has been disconnected. - * 'SettingAlreadySet' if a configuration has already been set using 'setConfig', 'useActiveConfig' or 'setConfigWhich'. * 'NoActiveConfig' if the device is not configured. + * 'NoDeviceException' if the device has been disconnected. + * Aanother 'USBException'. -} -useActiveConfig ∷ (pr `ParentOf` cr, MonadCatchIO cr) +useActiveConfig ∷ ∀ pr cr α + . (pr `ParentOf` cr, MonadCatchIO cr) ⇒ RegionalDeviceHandle pr -- ^ Regional handle to the device -- from which you want to use the -- active configuration. @@ -569,6 +575,9 @@ Exceptions: + * 'SettingAlreadySet' if a configuration has already been set using + 'setConfig', 'useActiveConfig' or 'setConfigWhich'. + * 'NotFound' if no configuration is found that satisfies the given predicate. @@ -576,12 +585,10 @@ * 'NoDeviceException' if the device has been disconnected - * 'SettingAlreadySet' if a configuration has already been set using - 'setConfig', 'useActiveConfig' or 'setConfigWhich'. - * Another 'USBException'. -} -setConfigWhich ∷ (pr `ParentOf` cr, MonadCatchIO cr) +setConfigWhich ∷ ∀ pr cr α + . (pr `ParentOf` cr, MonadCatchIO cr) ⇒ RegionalDeviceHandle pr -- ^ Regional handle to the device for -- which you want to set a -- configuration. @@ -692,7 +699,8 @@ * Another 'USBException'. -} -claim ∷ MonadCatchIO pr +claim ∷ ∀ pr sCfg s + . MonadCatchIO pr ⇒ Interface sCfg -- ^ Interface you wish to claim → RegionT s pr (RegionalIfHandle sCfg @@ -701,10 +709,11 @@ {-| Convenience function which finds the first interface of the given configuration handle which satisfies the given predicate on its descriptors, -then claims that interfaces and applies the given continuation function on the +then claims that interfaces and applies the given continuation function to the resulting regional handle. -} -withInterfaceWhich ∷ MonadCatchIO pr +withInterfaceWhich ∷ ∀ pr sCfg α + . MonadCatchIO pr ⇒ ConfigHandle sCfg -- ^ Handle to a configuration of which -- you want to claim an interface. → (USB.Interface → Bool) -- ^ Predicate on the interface descriptors. @@ -722,11 +731,12 @@ -- * Alternates -------------------------------------------------------------------------------- --- | A supported 'Interface' alternate setting. +-- | A supported 'Interface' alternate setting which you can retrieve using +-- 'getAlternates'. data Alternate sCfg (r ∷ * → *) = Alternate (RegionalIfHandle sCfg r) USB.InterfaceDesc -{-| Retrieve the supported alternate settings from the interface handle. +{-| Retrieve the supported alternate settings from the given interface handle. Note that the alternate setting is parameterized by the same type variables as the interface handle. This ensures you can never use an alternate setting @@ -761,7 +771,7 @@ USB.InterfaceDesc {-| Activate an alternate setting for an interface and then apply the given -function to the resulting alternate handle. +continuation function to the resulting alternate handle. Simillary to configurations, interfaces support multiple alternate settings of which only one can be active at any given time. When an alternate is set using @@ -783,7 +793,8 @@ * Another 'USBException'. -} -setAlternate ∷ (pr `ParentOf` cr, MonadCatchIO cr) +setAlternate ∷ ∀ pr cr sCfg α + . (pr `ParentOf` cr, MonadCatchIO cr) ⇒ Alternate sCfg pr -- ^ The alternate you wish to set. → (∀ sAlt. AlternateHandle sCfg sAlt pr → cr α) -- ^ Continuation function. @@ -819,7 +830,8 @@ * Aanother 'USBException'. -} -useActiveAlternate ∷ (pr `ParentOf` cr, MonadCatchIO cr) +useActiveAlternate ∷ ∀ pr cr sCfg α + . (pr `ParentOf` cr, MonadCatchIO cr) ⇒ RegionalIfHandle sCfg pr -- ^ Regional handle to the -- interface from which you want -- to use the active alternate. @@ -863,7 +875,8 @@ * Another 'USBException'. -} -setAlternateWhich ∷ (pr `ParentOf` cr, MonadCatchIO cr) +setAlternateWhich ∷ ∀ pr cr sCfg α + . (pr `ParentOf` cr, MonadCatchIO cr) ⇒ RegionalIfHandle sCfg pr -- ^ Regional handle to the -- interface for which you want -- to set an alternate. @@ -894,7 +907,7 @@ type-level so that I/O operations like 'readEndpoint' and 'writeEndpoint' can specify which endpoints they support. -You can retrieve the endpoints of an alternate by using 'getEndpoints'. +You can retrieve the endpoints of an alternate using 'getEndpoints'. -} data Endpoint transDir transType @@ -1027,8 +1040,7 @@ * Another 'USBException'. -} readEndpoint ∷ (pr `ParentOf` cr, MonadIO cr) - ⇒ Endpoint IN transType sAlt pr -- ^ The endpoint you wish to - -- read from. + ⇒ Endpoint IN transType sAlt pr → ReadAction cr instance ReadEndpoint BULK where @@ -1075,8 +1087,7 @@ * Another 'USBException'. -} writeEndpoint ∷ (pr `ParentOf` cr, MonadIO cr) - ⇒ Endpoint OUT transType sAlt pr -- ^ The endpoint you wish to - -- write to. + ⇒ Endpoint OUT transType sAlt pr → WriteAction cr instance WriteEndpoint BULK where @@ -1114,7 +1125,8 @@ * Another 'USBException'. -} -control ∷ (pr `ParentOf` cr, MonadIO cr) +control ∷ ∀ pr cr + . (pr `ParentOf` cr, MonadIO cr) ⇒ RegionalDeviceHandle pr -- ^ A handle for the device to communicate -- with. → RequestType -- ^ The type of request. @@ -1148,7 +1160,8 @@ * Another 'USBException'. -} -readControl ∷ (pr `ParentOf` cr, MonadIO cr) +readControl ∷ ∀ pr cr + . (pr `ParentOf` cr, MonadIO cr) ⇒ RegionalDeviceHandle pr -- ^ A handle for the device to -- communicate with. → RequestType -- ^ The type of request. @@ -1179,7 +1192,8 @@ * Another 'USBException'. -} -writeControl ∷ (pr `ParentOf` cr, MonadIO cr) +writeControl ∷ ∀ pr cr + . (pr `ParentOf` cr, MonadIO cr) ⇒ RegionalDeviceHandle pr -- ^ A handle for the device to -- communicate with. → RequestType -- ^ The type of request. diff --git a/usb-safe.cabal b/usb-safe.cabal --- a/usb-safe.cabal +++ b/usb-safe.cabal @@ -1,10 +1,10 @@ name: usb-safe -version: 0.5.1 +version: 0.5.1.1 cabal-version: >=1.6 -build-type: Simple +build-type: Custom license: BSD3 license-file: LICENSE -copyright: 2009 Bas van Dijk +copyright: 2010 Bas van Dijk author: Bas van Dijk maintainer: Bas van Dijk stability: experimental @@ -97,18 +97,17 @@ @darcs get@ - source-repository head Type: darcs Location: http://code.haskell.org/~basvandijk/code/usb-safe Library GHC-Options: -Wall -fno-warn-orphans - build-depends: base >= 4 && < 4.3 - , base-unicode-symbols >= 0.1.1 && < 0.2 + build-depends: base >= 4 && < 4.3 + , base-unicode-symbols >= 0.1.1 && < 0.2 , usb == 0.3.* , bytestring == 0.9.* - , regions == 0.3.* - , transformers >= 0.1.4 && < 0.2 - , MonadCatchIO-transformers == 0.0.2.* + , regions == 0.4.* + , transformers >= 0.1.4 && < 0.2 + , MonadCatchIO-transformers == 0.0.2.0 && < 0.1 exposed-modules: System.USB.Safe