usb-safe-0.5: usb-safe.cabal

name:          usb-safe
version:       0.5
cabal-version: >=1.6
build-type:    Simple
license:       BSD3
license-file:  LICENSE
copyright:     2009 Bas van Dijk
author:        Bas van Dijk
maintainer:    Bas van Dijk <v.dijk.bas@gmail.com>
stability:     experimental
category:      System, Monadic Regions
synopsis:      Type-safe communication with USB devices.
description:
  The usb library provides a standard Haskell abstraction layer over
  bindings-libusb providing: abstract types instead of Ptrs, automatic
  marshalling and unmarshalling, automatic garbage collection,
  exceptions instead of integer return codes, etc..

  .

  While all that is very nice there are still some things that you can
  do wrong. For example doing I/O with a closed device or reading from
  or writing to an endpoint which doesn't belong to the claimed
  interface. Or reading from an Out endpoint or writing to an In
  endpoint.

  .

  usb-safe provides the following guarantees:

  .

  * You can't reference handles to devices that are closed. In other words: no
     I/O with closed handles is possible.

  .

  * The programmer specifies the region in which devices should remain open. On
    exit from the region the opened devices will be closed automatically.

  .

  * You can't reference handles to configurations that have not been set.

  .

  * You can't reference handles to interfaces that have not been claimed.

  .

  * Just like with devices, the programmer can specify the region in
    which interfaces should remain claimed. On exit from the region
    the claimed interfaces will be released automatically.

  .

  * You can't reference handles to alternates that have not been set.

  .

  * You can't reference endpoints that don't belong to a setted alternate.

  .

  * You can't read from an endpoint with an Out transfer direction.

  .

  * You can't write to an endpoint with an In transfer direction.

  .

  * You can't read from or write to endpoints with the unsupported transfer
    types Control and Isochronous. Only I/O with endpoints with the Bulk and
    Interrupt transfer types is allowed.

  .

  The primary technique used in usb-safe is called \"Lightweight monadic
  regions\" which was invented by Oleg Kiselyov and Chung-chieh Shan.
  See:

  .

  <http://okmij.org/ftp/Haskell/regions.html#light-weight>

  .

  This technique is implemented in the @regions@ package which is
  re-exported from @usb-safe@.

  .

  See the @usb-safe-examples@ package for examples how to use this library:

  .

  @darcs get@ <http://code.haskell.org/~basvandijk/code/usb-safe-examples>


source-repository head
  Type:     darcs
  Location: http://code.haskell.org/~basvandijk/code/usb-safe

Library
  GHC-Options: -O2 -Wall -fno-warn-orphans
  build-depends: base                      >= 4 && < 4.3
               , base-unicode-symbols      >= 0.1.1 && < 0.2
               , usb                       == 0.3.*
               , bytestring                == 0.9.*
               , regions                   == 0.2.*
               , transformers              >= 0.1.4 && < 0.2
               , MonadCatchIO-transformers == 0.0.2.*
  exposed-modules: System.USB.Safe