Sound.Libcdio

One of the goals of these bindings is to make it not only possible to interface with the libcdio library, but to do so as comfortably and safely as possible. In that, the Foreign.Libcdio interface is a bit lacking, due to its mutable state and requirement of threading IO through computations. The modules in this namespace provide an alternative which builds on that base, with a more native style. As a general rule, a project should only import modules from the Sound or the Foreign namespaces, not both, as while the types can often be interchanged, several function names have been reused and so may collide.

Types

Session

data Cdio a

A computation within the environment of the data (music or file) stored on a CD. The options for affecting that environment from within are limited by design, as this library is intended for reading discs rather than authoring them.

Instances

Monad Cdio

Defined in Sound.Libcdio.Types.Cdio

Methods

(>>=) :: Cdio a -> (a -> Cdio b) -> Cdio b

(>>) :: Cdio a -> Cdio b -> Cdio b

return :: a -> Cdio a

Functor Cdio

Defined in Sound.Libcdio.Types.Cdio

Methods

fmap :: (a -> b) -> Cdio a -> Cdio b

(<$) :: a -> Cdio b -> Cdio a

MonadFail Cdio

Wraps the text in a FreeformCdioError, for recovery with catchError.

Defined in Sound.Libcdio.Types.Cdio

Methods

fail :: String -> Cdio a

Applicative Cdio

Defined in Sound.Libcdio.Types.Cdio

Methods

pure :: a -> Cdio a

(<*>) :: Cdio (a -> b) -> Cdio a -> Cdio b

liftA2 :: (a -> b -> c) -> Cdio a -> Cdio b -> Cdio c

(*>) :: Cdio a -> Cdio b -> Cdio b

(<*) :: Cdio a -> Cdio b -> Cdio a

Alternative Cdio

empty fails with CdioEmpty.

Defined in Sound.Libcdio.Types.Cdio

Methods

empty :: Cdio a

(<|>) :: Cdio a -> Cdio a -> Cdio a

some :: Cdio a -> Cdio [a]

many :: Cdio a -> Cdio [a]

LibcdioLogger Cdio

Defined in Sound.Libcdio.Types.Cdio

Methods

logCutoff :: Cdio LogLevel

setLogCutoff :: LogLevel -> Cdio ()

readLog :: Cdio [LogEntry]

clearLog :: Cdio ()

putLog :: LogEntry -> Cdio ()

MonadError CdioError Cdio

Defined in Sound.Libcdio.Types.Cdio

Methods

throwError :: CdioError -> Cdio a

catchError :: Cdio a -> (CdioError -> Cdio a) -> Cdio a

data CdioError

Associates a well-typed error with human-readable context information.

Constructors

CdioError CdioErrorType Text

Instances

Eq CdioError

Defined in Sound.Libcdio.Types.Cdio

Methods

(==) :: CdioError -> CdioError -> Bool

(/=) :: CdioError -> CdioError -> Bool

Read CdioError

Defined in Sound.Libcdio.Types.Cdio

Methods

readsPrec :: Int -> ReadS CdioError

readList :: ReadS [CdioError]

readPrec :: ReadPrec CdioError

readListPrec :: ReadPrec [CdioError]

Show CdioError

Defined in Sound.Libcdio.Types.Cdio

Methods

showsPrec :: Int -> CdioError -> ShowS

show :: CdioError -> String

showList :: [CdioError] -> ShowS

MonadError CdioError Cdio

Defined in Sound.Libcdio.Types.Cdio

Methods

throwError :: CdioError -> Cdio a

catchError :: Cdio a -> (CdioError -> Cdio a) -> Cdio a

data CdioErrorType

Potential situations which may cause a computation to fail.

Constructors

DriverError

A requested operation failed for some unknown reason, or the operating system doesn't support the DriverId in use.

BadParameter

Some value passed to a requested operation was rejected as nonsensical or otherwise breaking the value-level invariants.

NotPermitted

The ability to perform a requested operation has been restricted (e.g., the user doesn't have permission to access the disc drive).

SessionClosed

The underlying library closed the Cdio session prematurely.

Unsupported

A requested operation isn't available with driver used by the Cdio session. Refer to capabilities and deviceCapabilities to reduce these.

CdioEmpty

empty was called and no better alternative was encountered.

FreeformCdioError Text

Escape hatch from structured typing to allow user-specified (and user-triggered) errors.

Instances

Eq CdioErrorType

Defined in Sound.Libcdio.Types.Cdio

Methods

(==) :: CdioErrorType -> CdioErrorType -> Bool

(/=) :: CdioErrorType -> CdioErrorType -> Bool

Read CdioErrorType

Defined in Sound.Libcdio.Types.Cdio

Methods

readsPrec :: Int -> ReadS CdioErrorType

readList :: ReadS [CdioErrorType]

readPrec :: ReadPrec CdioErrorType

readListPrec :: ReadPrec [CdioErrorType]

Show CdioErrorType

Defined in Sound.Libcdio.Types.Cdio

Methods

showsPrec :: Int -> CdioErrorType -> ShowS

show :: CdioErrorType -> String

showList :: [CdioErrorType] -> ShowS

data SessionArg

Metadata about the session in the form of (often freeform) text, providing a type-safe index to getArg. Note that not every driver type supports every item.

The key "access-mode" is handled separately by getAccessMode, to better reflect its restricted outputs.

Constructors

Source

Cue

ScsiTuple

MmcSupported

Instances

Bounded SessionArg

Defined in Foreign.Libcdio.Device

Methods

minBound :: SessionArg

maxBound :: SessionArg

Enum SessionArg

Defined in Foreign.Libcdio.Device

Methods

succ :: SessionArg -> SessionArg

pred :: SessionArg -> SessionArg

toEnum :: Int -> SessionArg

fromEnum :: SessionArg -> Int

enumFrom :: SessionArg -> [SessionArg]

enumFromThen :: SessionArg -> SessionArg -> [SessionArg]

enumFromTo :: SessionArg -> SessionArg -> [SessionArg]

enumFromThenTo :: SessionArg -> SessionArg -> SessionArg -> [SessionArg]

Eq SessionArg

Defined in Foreign.Libcdio.Device

Methods

(==) :: SessionArg -> SessionArg -> Bool

(/=) :: SessionArg -> SessionArg -> Bool

Ord SessionArg

Defined in Foreign.Libcdio.Device

Methods

compare :: SessionArg -> SessionArg -> Ordering

(<) :: SessionArg -> SessionArg -> Bool

(<=) :: SessionArg -> SessionArg -> Bool

(>) :: SessionArg -> SessionArg -> Bool

(>=) :: SessionArg -> SessionArg -> Bool

max :: SessionArg -> SessionArg -> SessionArg

min :: SessionArg -> SessionArg -> SessionArg

Read SessionArg

Defined in Foreign.Libcdio.Device

Methods

readsPrec :: Int -> ReadS SessionArg

readList :: ReadS [SessionArg]

readPrec :: ReadPrec SessionArg

readListPrec :: ReadPrec [SessionArg]

Show SessionArg

Defined in Foreign.Libcdio.Device

Methods

showsPrec :: Int -> SessionArg -> ShowS

show :: SessionArg -> String

showList :: [SessionArg] -> ShowS

Storable SessionArg

Defined in Foreign.Libcdio.Device

Methods

sizeOf :: SessionArg -> Int

alignment :: SessionArg -> Int

peekElemOff :: Ptr SessionArg -> Int -> IO SessionArg

pokeElemOff :: Ptr SessionArg -> Int -> SessionArg -> IO ()

peekByteOff :: Ptr b -> Int -> IO SessionArg

pokeByteOff :: Ptr b -> Int -> SessionArg -> IO ()

peek :: Ptr SessionArg -> IO SessionArg

poke :: Ptr SessionArg -> SessionArg -> IO ()

data AccessMode

Which instruction set should be used to communicate with the driver, providing a type-safe input for session initialization. Note that not every driver type supports every item.

Constructors

Image

Ioctl

The DriverLinux and DriverBsdi drivers use a different internal representation for Ioctl_.

Ioctl_

The DriverFreeBsd and DriverWin32 drivers use a different internal representation for Ioctl.

Aspi

Atapi

Cam

Scsi

ReadCd

Read10

MmcReadWrite

MmcReadWriteExclusive

Instances

Bounded AccessMode

Defined in Foreign.Libcdio.Device

Methods

minBound :: AccessMode

maxBound :: AccessMode

Enum AccessMode

Defined in Foreign.Libcdio.Device

Methods

succ :: AccessMode -> AccessMode

pred :: AccessMode -> AccessMode

toEnum :: Int -> AccessMode

fromEnum :: AccessMode -> Int

enumFrom :: AccessMode -> [AccessMode]

enumFromThen :: AccessMode -> AccessMode -> [AccessMode]

enumFromTo :: AccessMode -> AccessMode -> [AccessMode]

enumFromThenTo :: AccessMode -> AccessMode -> AccessMode -> [AccessMode]

Eq AccessMode

Defined in Foreign.Libcdio.Device

Methods

(==) :: AccessMode -> AccessMode -> Bool

(/=) :: AccessMode -> AccessMode -> Bool

Ord AccessMode

Defined in Foreign.Libcdio.Device

Methods

compare :: AccessMode -> AccessMode -> Ordering

(<) :: AccessMode -> AccessMode -> Bool

(<=) :: AccessMode -> AccessMode -> Bool

(>) :: AccessMode -> AccessMode -> Bool

(>=) :: AccessMode -> AccessMode -> Bool

max :: AccessMode -> AccessMode -> AccessMode

min :: AccessMode -> AccessMode -> AccessMode

Read AccessMode

Defined in Foreign.Libcdio.Device

Methods

readsPrec :: Int -> ReadS AccessMode

readList :: ReadS [AccessMode]

readPrec :: ReadPrec AccessMode

readListPrec :: ReadPrec [AccessMode]

Show AccessMode

Defined in Foreign.Libcdio.Device

Methods

showsPrec :: Int -> AccessMode -> ShowS

show :: AccessMode -> String

showList :: [AccessMode] -> ShowS

Storable AccessMode

Defined in Foreign.Libcdio.Device

Methods

sizeOf :: AccessMode -> Int

alignment :: AccessMode -> Int

peekElemOff :: Ptr AccessMode -> Int -> IO AccessMode

pokeElemOff :: Ptr AccessMode -> Int -> AccessMode -> IO ()

peekByteOff :: Ptr b -> Int -> IO AccessMode

pokeByteOff :: Ptr b -> Int -> AccessMode -> IO ()

peek :: Ptr AccessMode -> IO AccessMode

poke :: Ptr AccessMode -> AccessMode -> IO ()

Version

data Version

A Version represents the version of a software entity.

An instance of Eq is provided, which implements exact equality modulo reordering of the tags in the versionTags field.

An instance of Ord is also provided, which gives lexicographic ordering on the versionBranch fields (i.e. 2.1 > 2.0, 1.2.3 > 1.2.2, etc.). This is expected to be sufficient for many uses, but note that you may need to use a more specific ordering for your versioning scheme. For example, some versioning schemes may include pre-releases which have tags "pre1", "pre2", and so on, and these would need to be taken into account when determining ordering. In some cases, date ordering may be more appropriate, so the application would have to look for date tags in the versionTags field and compare those. The bottom line is, don't always assume that compare and other Ord operations are the right thing for every Version.

Similarly, concrete representations of versions may differ. One possible concrete representation is provided (see showVersion and parseVersion), but depending on the application a different concrete representation may be more appropriate.

Instances

IsList Version

Since: base-4.8.0.0

Defined in GHC.Exts

Associated Types

type Item Version

Methods

fromList :: [Item Version] -> Version

fromListN :: Int -> [Item Version] -> Version

toList :: Version -> [Item Version]

Eq Version

Since: base-2.1

Defined in Data.Version

Methods

(==) :: Version -> Version -> Bool

(/=) :: Version -> Version -> Bool

Ord Version

Since: base-2.1

Defined in Data.Version

Methods

compare :: Version -> Version -> Ordering

(<) :: Version -> Version -> Bool

(<=) :: Version -> Version -> Bool

(>) :: Version -> Version -> Bool

(>=) :: Version -> Version -> Bool

max :: Version -> Version -> Version

min :: Version -> Version -> Version

Read Version

Since: base-2.1

Defined in Data.Version

Methods

readsPrec :: Int -> ReadS Version

readList :: ReadS [Version]

readPrec :: ReadPrec Version

readListPrec :: ReadPrec [Version]

Show Version

Since: base-2.1

Defined in Data.Version

Methods

showsPrec :: Int -> Version -> ShowS

show :: Version -> String

showList :: [Version] -> ShowS

Generic Version

Since: base-4.9.0.0

Defined in Data.Version

Associated Types

type Rep Version :: Type -> Type

Methods

from :: Version -> Rep Version x

to :: Rep Version x -> Version

type Rep Version

Defined in Data.Version

type Rep Version = D1 ('MetaData "Version" "Data.Version" "base" 'False) (C1 ('MetaCons "Version" 'PrefixI 'True) (S1 ('MetaSel ('Just "versionBranch") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Int]) :*: S1 ('MetaSel ('Just "versionTags") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [String])))

type Item Version

Defined in GHC.Exts

type Item Version = Int

makeVersion :: [Int] -> Version

Construct tag-less Version

Since: base-4.8.0.0

Evaluation

open

Arguments

:: Maybe FilePath

-> Bool

Whether the disc should be ejected after the computation.

-> Cdio a

-> IO (Either CdioError a)

Open a session to read data from the disc drive/image at the given location. If passed Nothing instead, uses the path considered "default"; on operating systems with a concept of numbered devices (e.g., Window's D: drive, FreeBSD's /dev/cd0) will usually return the first such device found to be suitable.

openMode

Arguments

:: AccessMode

-> Maybe FilePath

-> Bool

Whether the disc should be ejected after the computation.

-> Cdio a

-> IO (Either CdioError a)

Open a session to read data from the disc drive/image at the given location, using a specific instruction set. If passed Nothing instead, uses the path considered "default"; on operating systems with a concept of numbered devices (e.g., Window's D: drive, FreeBSD's /dev/cd0) will usually return the first such device found to be suitable.

runCdio :: Cdio -> Cdio a -> IO (Either CdioError a)

Use a C-style Foreign.Libcdio.Cdio object as the base to run a Haskell-style Sound.Libcdio.Cdio computation.

Note that some invariants of the monadic interface may not work as expected when used with the mutable objects.

getArg :: SessionArg -> Cdio (Maybe Text)

Retrieve the session value associated with the given key. The particular case of "access-mode" is instead handled by getAccessMode.

getAccessMode :: Cdio (Maybe AccessMode)

Check what instruction set is in use for reading the disc. Other session values are handled by getArg.

Library data

cdioVersionString :: String

The value of the preprocessor macro CDIO_VERSION, listing both the SemVar-style version of libcdio and the full architecture of the system which compiled it (e.g. 2.0.0 x86_64-pc-linux-gnu).

libcdioVersionNum :: Version

The value of the preprocessor macro LIBCDIO_VERSION_NUM, containing a numeric representation of the version suitable for arithmetic testing.

apiVersion :: Word

The value of the preprocessor macro CDIO_API_VERSION, containing a single, monotonically increasing constant representing changes to the public interface. However, as it's somewhat unclear what changes warrant bumping this number, it is typically better to use libcdioVersionNum instead.