-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Haskell Open Sound Control
--
-- hosc implements a subset of the Open Sound Control
-- byte protocol, http://opensoundcontrol.org/.
--
-- Sound.OpenSoundControl implements the actual protocol.
--
-- Sound.OSC.Transport.FD implements a file descriptor
-- based transport layer for UDP and TCP.
--
-- Sound.OSC.Transport.Monad implements a monadic interface to the
-- FD transport layer.
--
-- Composite modules are at Sound.OSC and Sound.OSC.FD.
@package hosc
@version 0.13
-- | Bit-level type casts and byte layout string typecasts.
module Sound.OpenSoundControl.Coding.Cast
-- | The IEEE byte representation of a float.
f32_w32 :: Float -> Word32
-- | Inverse of f32_w32.
w32_f32 :: Word32 -> Float
-- | The IEEE byte representation of a double.
f64_w64 :: Double -> Word64
-- | Inverse of f64_i64.
w64_f64 :: Word64 -> Double
-- | Transform a haskell string into a C string (a null suffixed byte
-- string).
str_cstr :: String -> [Word8]
-- | Inverse of str_cstr.
cstr_str :: [Word8] -> String
-- | Transform a haskell string to a pascal string (a length prefixed byte
-- string).
str_pstr :: String -> [Word8]
-- | Inverse of str_pstr.
pstr_str :: [Word8] -> String
-- | Byte-level coding utility functions.
module Sound.OpenSoundControl.Coding.Byte
-- | Encode a signed 8-bit integer.
encode_i8 :: Int -> ByteString
-- | Encode a signed 16-bit integer.
encode_i16 :: Int -> ByteString
-- | Encode a signed 32-bit integer.
encode_i32 :: Int -> ByteString
-- | Encode an unsigned 16-bit integer.
encode_u32 :: Int -> ByteString
-- | Encode a signed 64-bit integer.
encode_i64 :: Int64 -> ByteString
-- | Encode an unsigned 64-bit integer.
encode_u64 :: Word64 -> ByteString
-- | Encode a 32-bit IEEE floating point number.
encode_f32 :: Double -> ByteString
-- | Encode a 64-bit IEEE floating point number.
encode_f64 :: Double -> ByteString
-- | Encode an ASCII string.
encode_str :: String -> ByteString
-- | Decode a signed 8-bit integer.
decode_i8 :: ByteString -> Int
-- | Decode a signed 16-bit integer.
decode_i16 :: ByteString -> Int
-- | Decode a signed 32-bit integer.
decode_i32 :: ByteString -> Int
-- | Decode an unsigned 32-bit integer.
decode_u32 :: ByteString -> Int
-- | Decode a signed 64-bit integer.
decode_i64 :: ByteString -> Int64
-- | Decode an unsigned 64-bit integer.
decode_u64 :: ByteString -> Word64
-- | Decode a 32-bit IEEE floating point number.
decode_f32 :: ByteString -> Double
-- | Decode a 64-bit IEEE floating point number.
decode_f64 :: ByteString -> Double
-- | Decode an ASCII string.
decode_str :: ByteString -> String
-- | Bundle header string.
bundleHeader :: ByteString
-- | The number of bytes required to align an OSC value to the next 4-byte
-- boundary.
--
--
-- map align [0::Int .. 7] == [0,3,2,1,0,3,2,1]
--
align :: (Num i, Bits i) => i -> i
module Sound.OpenSoundControl.Wait
-- | Real valued variant of timeout.
timeout_r :: Double -> IO a -> IO (Maybe a)
-- | Repeat action until predicate f is True when applied to
-- result.
untilPredicate :: Monad m => (a -> Bool) -> m a -> m a
-- | Repeat action until f does not give Nothing when applied
-- to result.
untilMaybe :: Monad m => (a -> Maybe b) -> m a -> m b
-- | OSC related timing functions. OSC timestamps are NTP values,
-- http://ntp.org/.
module Sound.OpenSoundControl.Time
-- | Type for integer (binary) representation of NTP time.
type NTPi = Word64
-- | NTP time in real-valued (fractional) form.
type Time = Double
-- | Unix/Posix epoch time in real-valued (fractional) form.
type UT = Double
-- | Convert a real-valued NTP timestamp to an NTPi timestamp.
ntpr_to_ntpi :: RealFrac n => n -> NTPi
-- | Convert an NTPi timestamp to a real-valued NTP timestamp.
ntpi_to_ntpr :: Fractional n => NTPi -> n
-- | Difference (in seconds) between NTP and UT epochs.
--
--
-- ntp_ut_epoch_diff / (24 * 60 * 60) == 25567
--
ntp_ut_epoch_diff :: Num n => n
-- | Convert a UT timestamp to an NTPi timestamp.
ut_to_ntpi :: UT -> NTPi
-- | Convert Unix/Posix to NTP.
ut_to_ntpr :: Num n => n -> n
-- | Convert NTP to Unix/Posix.
ntpr_to_ut :: Num n => n -> n
-- | Convert NTPi to Unix/Posix.
ntpi_to_ut :: NTPi -> UT
-- | Constant indicating a bundle to be executed immediately.
--
--
-- ntpr_to_ntpi immediately == 1
--
immediately :: Time
-- | The time at 1970-01-01:00:00:00.
ut_epoch :: UTCTime
-- | Convert UTCTime to Unix/Posix.
utc_to_ut :: Fractional n => UTCTime -> n
-- | Read current real-valued NTP timestamp.
--
--
-- do {ct <- fmap utc_to_ut T.getCurrentTime
-- ;pt <- fmap realToFrac T.getPOSIXTime
-- ;print (pt - ct,pt - ct < 1e-5)}
--
time :: MonadIO m => m Time
-- | The pauseThread limit (in seconds). Values larger than this
-- require a different thread delay mechanism, see sleepThread.
-- The value is the number of microseconds in maxBound::Int.
pauseThreadLimit :: Fractional n => n
-- | Pause current thread for the indicated duration (in seconds), see
-- pauseThreadLimit.
pauseThread :: (MonadIO m, Ord n, RealFrac n) => n -> m ()
-- | Type restricted pauseThread.
wait :: MonadIO m => Double -> m ()
-- | Pause current thread until the given Time, see
-- pauseThreadLimit.
pauseThreadUntil :: MonadIO m => Time -> m ()
-- | Sleep current thread for the indicated duration (in seconds). Divides
-- long sleeps into parts smaller than pauseThreadLimit.
sleepThread :: (RealFrac n, MonadIO m) => n -> m ()
-- | Sleep current thread until the given Time. Divides long sleeps
-- into parts smaller than pauseThreadLimit.
sleepThreadUntil :: MonadIO m => Time -> m ()
-- | Alegbraic data types for OSC datum and packets.
module Sound.OpenSoundControl.Type
-- | Type enumerating Datum categories.
type Datum_Type = Char
-- | The basic elements of OSC messages.
data Datum
Int :: Int -> Datum
Float :: Double -> Datum
Double :: Double -> Datum
String :: String -> Datum
Blob :: ByteString -> Datum
TimeStamp :: Time -> Datum
Midi :: (Word8, Word8, Word8, Word8) -> Datum
-- | OSC address pattern.
type Address_Pattern = String
-- | An OSC message.
data Message
Message :: Address_Pattern -> [Datum] -> Message
messageAddress :: Message -> Address_Pattern
messageDatum :: Message -> [Datum]
-- | An OSC bundle.
data Bundle
Bundle :: Time -> [Message] -> Bundle
bundleTime :: Bundle -> Time
bundleMessages :: Bundle -> [Message]
-- | An OSC Packet is either a Message or a Bundle.
data Packet
Packet_Message :: Message -> Packet
packetMessage :: Packet -> Message
Packet_Bundle :: Bundle -> Packet
packetBundle :: Packet -> Bundle
-- | Bundle constructor. It is an error if the Message
-- list is empty.
bundle :: Time -> [Message] -> Bundle
-- | Message constructor. It is an error if the
-- Address_Pattern doesn't conform to the OSC specification.
message :: Address_Pattern -> [Datum] -> Message
-- | Packet_Bundle . bundle.
p_bundle :: Time -> [Message] -> Packet
-- | Packet_Message . message.
p_message :: Address_Pattern -> [Datum] -> Packet
-- | Single character identifier of an OSC datum.
datum_tag :: Datum -> Datum_Type
-- | Variant of read.
readMaybe :: Read a => String -> Maybe a
-- | Given Datum_Type attempt to parse Datum at
-- String.
--
--
-- parse_datum 'i' "42" == Just (Int 42)
-- parse_datum 'f' "3.14159" == Just (Float 3.14159)
-- parse_datum 'd' "3.14159" == Just (Double 3.14159)
-- parse_datum 's' "\"pi\"" == Just (String "pi")
-- parse_datum 'b' "pi" == Just (Blob (B.pack [112,105]))
-- parse_datum 'm' "(0,144,60,90)" == Just (Midi (0,144,60,90))
--
parse_datum :: Datum_Type -> String -> Maybe Datum
-- | Datum as real number if Double, Float or
-- Int, else Nothing.
--
--
-- map datum_real [Int 5,Float 5,String "5"] == [Just 5,Just 5,Nothing]
--
datum_real :: Datum -> Maybe Double
-- | A fromJust variant of datum_real.
--
--
-- map datum_real_err [Int 5,Float 5] == [5,5]
--
datum_real_err :: Datum -> Double
-- | Datum as integral number if Double, Float or
-- Int, else Nothing.
--
--
-- map datum_int [Int 5,Float 5.5,String "5"] == [Just 5,Just 5,Nothing]
--
datum_int :: Integral i => Datum -> Maybe i
-- | A fromJust variant of datum_int.
--
--
-- map datum_int_err [Int 5,Float 5.5] == [5,5]
--
datum_int_err :: Integral i => Datum -> i
-- | Datum as String if String or Blob, else
-- Nothing.
--
--
-- map datum_string [String "5",Blob (B.pack [53])] == [Just "5",Just "5"]
--
datum_string :: Datum -> Maybe String
-- | A fromJust variant of datum_string.
--
--
-- map datum_string_err [String "5",Blob (B.pack [53])] == ["5","5"]
--
datum_string_err :: Datum -> String
-- | Does Message have the specified Address_Pattern.
message_has_address :: Address_Pattern -> Message -> Bool
-- | Do any of the Messages at Bundle have the specified
-- Address_Pattern.
bundle_has_address :: Address_Pattern -> Bundle -> Bool
-- | Does Packet have the specified Address_Pattern, ie.
-- message_has_address or bundle_has_address.
packet_has_address :: Address_Pattern -> Packet -> Bool
-- | The Time of Packet, if the Packet is a
-- Message this is immediately.
packetTime :: Packet -> Time
-- | Retrieve the set of Messages from a Packet.
packetMessages :: Packet -> [Message]
-- | If Packet is a Message add immediately timestamp,
-- else id.
packet_to_bundle :: Packet -> Bundle
-- | If Packet is a Message or a Bundle with an
-- immediate time tag and with one element, return the
-- Message, else Nothing.
packet_to_message :: Packet -> Maybe Message
-- | Is Packet immediate, ie. a Bundle with timestamp
-- immediately, or a plain Message.
packet_is_immediate :: Packet -> Bool
-- | Variant of either for Packet.
at_packet :: (Message -> a) -> (Bundle -> a) -> Packet -> a
-- | Pretty printer for Time.
timePP :: Time -> String
-- | Pretty printer for Datum.
--
--
-- map datumPP [Float 1.2,String "str",Midi (0,0x90,0x40,0x60)]
--
datumPP :: Datum -> String
-- | Pretty printer for Message.
messagePP :: Message -> String
-- | Pretty printer for Bundle.
bundlePP :: Bundle -> String
-- | Pretty printer for Packet.
packetPP :: Packet -> String
instance Eq Datum
instance Read Datum
instance Show Datum
instance Eq Message
instance Read Message
instance Show Message
instance Eq Bundle
instance Read Bundle
instance Show Bundle
instance Eq Packet
instance Read Packet
instance Show Packet
instance Ord Bundle
-- | OSC packet coercion and normalization.
module Sound.OpenSoundControl.Coding.Coerce
-- | Map a normalizing function over datum at an OSC Message.
message_coerce :: (Datum -> Datum) -> Message -> Message
-- | Map a normalizing function over datum at an OSC Bundle.
bundle_coerce :: (Datum -> Datum) -> Bundle -> Bundle
-- | Coerce Float to Double.
f_to_d :: Datum -> Datum
-- | Coerce Int and Float to Double.
if_to_d :: Datum -> Datum
-- | Coerce Float and Double to Int.
fd_to_i :: Datum -> Datum
-- | Base-level decode function for OSC packets (slow). For ordinary use
-- see Binary.
module Sound.OpenSoundControl.Coding.Decode.Base
-- | Decode an OSC Message.
decodeMessage :: ByteString -> Message
-- | Decode an OSC Bundle.
decodeBundle :: ByteString -> Bundle
-- | Decode an OSC Packet.
--
--
-- let b = B.pack [47,103,95,102,114,101,101,0,44,105,0,0,0,0,0,0]
-- in decodePacket b == Message "/g_free" [Int 0]
--
decodePacket :: ByteString -> Packet
-- | Optimised decode function for OSC packets.
module Sound.OpenSoundControl.Coding.Decode.Binary
-- | Get an OSC Packet.
getPacket :: Get Packet
-- | Decode an OSC packet from a lazy ByteString.
--
--
-- let b = L.pack [47,103,95,102,114,101,101,0,44,105,0,0,0,0,0,0]
-- in decodeOSC b == Message "/g_free" [Int 0]
--
decodePacket :: ByteString -> Packet
-- | Decode an OSC packet from a strict ByteString.
decodePacket_strict :: ByteString -> Packet
-- | Base-level encode function for OSC packets (slow). For ordinary use
-- see Builder.
module Sound.OpenSoundControl.Coding.Encode.Base
-- | Encode an OSC Message.
encodeMessage :: Message -> ByteString
-- | Encode an OSC Bundle.
encodeBundle :: Bundle -> ByteString
-- | Encode an OSC Packet.
encodePacket :: Packet -> ByteString
-- | Optimised encode function for OSC packets.
module Sound.OpenSoundControl.Coding.Encode.Builder
-- | Builder monoid for an OSC Packet.
build_packet :: Packet -> Builder
-- | Encode an OSC Message.
encodeMessage :: Message -> ByteString
-- | Encode an OSC Bundle.
encodeBundle :: Bundle -> ByteString
-- | Encode an OSC Packet to a lazy ByteString.
--
--
-- let b = L.pack [47,103,95,102,114,101,101,0,44,105,0,0,0,0,0,0]
-- in encodeOSC (Message "/g_free" [Int 0]) == b
--
encodePacket :: Packet -> ByteString
-- | Encode an Packet packet to a strict ByteString.
encodePacket_strict :: Packet -> ByteString
-- | A type-class to provide coding operations to different data types
-- using the same function names.
module Sound.OpenSoundControl.Coding
-- | Converting from and to binary packet representations.
class Coding a
encodePacket :: Coding a => Packet -> a
decodePacket :: Coding a => a -> Packet
-- | An encodePacket and decodePacket pair over
-- ByteString.
type Coder = (Packet -> ByteString, ByteString -> Packet)
-- | encodePacket . Packet_Message.
encodeMessage :: Coding c => Message -> c
-- | encodePacket . Packet_Bundle.
encodeBundle :: Coding c => Bundle -> c
-- | packet_to_message . decodePacket.
decodeMessage :: Coding c => c -> Maybe Message
-- | packet_to_bundle . decodePacket.
decodeBundle :: Coding c => c -> Bundle
instance Coding String
instance Coding ByteString
instance Coding ByteString
-- | Typeclass for encoding and decoding OSC packets.
module Sound.OpenSoundControl.Class
-- | A type-class for values that can be translated to and from OSC
-- Packets.
class OSC o
toPacket :: OSC o => o -> Packet
fromPacket :: OSC o => Packet -> Maybe o
-- | encodePacket . toPacket.
encodeOSC :: (Coding c, OSC o) => o -> c
-- | fromPacket . decodePacket.
decodeOSC :: (Coding c, OSC o) => c -> Maybe o
instance OSC Packet
instance OSC Bundle
instance OSC Message
-- | An abstract transport layer with implementations for UDP and
-- TCP transport.
module Sound.OSC.Transport.FD
-- | Abstract over the underlying transport protocol.
class Transport t
sendOSC :: (Transport t, OSC o) => t -> o -> IO ()
recvPacket :: Transport t => t -> IO Packet
close :: Transport t => t -> IO ()
-- | Bracket OSC communication.
withTransport :: Transport t => IO t -> (t -> IO a) -> IO a
-- | Type restricted synonym for sendOSC.
sendMessage :: Transport t => t -> Message -> IO ()
-- | Type restricted synonym for sendOSC.
sendBundle :: Transport t => t -> Bundle -> IO ()
-- | Variant of recvPacket that runs fromPacket.
recvOSC :: (Transport t, OSC o) => t -> IO (Maybe o)
-- | Variant of recvPacket that runs packet_to_bundle.
recvBundle :: Transport t => t -> IO Bundle
-- | Variant of recvPacket that runs packet_to_message.
recvMessage :: Transport t => t -> IO (Maybe Message)
-- | Variant of recvPacket that runs packetMessages.
recvMessages :: Transport t => t -> IO [Message]
-- | Variant of recvPacket that implements an n second
-- timeout.
recvPacketTimeout :: Transport t => Double -> t -> IO (Maybe Packet)
-- | Wait for a Packet where the supplied predicate is True,
-- discarding intervening packets.
waitUntil :: Transport t => t -> (Packet -> Bool) -> IO Packet
-- | Wait for a Packet where the supplied function does not give
-- Nothing, discarding intervening packets.
waitFor :: Transport t => t -> (Packet -> Maybe a) -> IO a
-- | waitUntil packet_is_immediate.
waitImmediate :: Transport t => t -> IO Packet
-- | waitFor packet_to_message, ie. an incoming
-- Message or immediate mode Bundle with one element.
waitMessage :: Transport t => t -> IO Message
-- | A waitFor for variant using packet_has_address to match
-- on the Address_Pattern of incoming Packets.
waitAddress :: Transport t => t -> Address_Pattern -> IO Packet
-- | Variant on waitAddress that returns matching Message.
waitReply :: Transport t => t -> Address_Pattern -> IO Message
-- | Variant of waitReply that runs messageDatum.
waitDatum :: Transport t => t -> Address_Pattern -> IO [Datum]
-- | OSC over UDP implementation.
module Sound.OSC.Transport.FD.UDP
-- | The UDP transport handle data type.
data UDP
UDP :: Socket -> UDP
udpSocket :: UDP -> Socket
-- | Return the port number associated with the UDP socket.
udpPort :: Integral n => UDP -> IO n
-- | Create and initialise UDP socket.
udp_socket :: (Socket -> SockAddr -> IO ()) -> String -> Int -> IO UDP
-- | Make a UDP connection.
--
--
-- let t = openUDP "127.0.0.1" 57110
-- in withTransport t (\fd -> recvT 0.5 fd >>= print)
--
openUDP :: String -> Int -> IO UDP
-- | Trivial UDP server socket.
--
--
-- import Control.Concurrent
--
--
--
-- let {f fd = forever (recvMessage fd >>= print)
-- ;t = udpServer "127.0.0.1" 57300}
-- in void (forkIO (withTransport t f))
--
--
--
-- let t = openUDP "127.0.0.1" 57300
-- in withTransport t (\fd -> sendMessage fd (message "/n" []))
--
udpServer :: String -> Int -> IO UDP
-- | Send variant to send to specified address.
sendTo :: OSC o => UDP -> o -> SockAddr -> IO ()
-- | Recv variant to collect message source address.
recvFrom :: UDP -> IO (Packet, SockAddr)
instance Transport UDP
-- | OSC over TCP implementation.
module Sound.OSC.Transport.FD.TCP
-- | The TCP transport handle data type.
data TCP
TCP :: Handle -> TCP
tcpHandle :: TCP -> Handle
-- | Make a TCP connection.
openTCP :: String -> Int -> IO TCP
-- | A trivial TCP OSC server.
tcpServer' :: Int -> (TCP -> IO ()) -> IO ()
instance Transport TCP
-- | Monad class implementing an Open Sound Control transport.
module Sound.OSC.Transport.Monad
-- | Sender monad.
class Monad m => SendOSC m
sendOSC :: (SendOSC m, OSC o) => o -> m ()
-- | Receiver monad.
class Monad m => RecvOSC m
recvPacket :: RecvOSC m => m Packet
-- | DuplexOSC is the union of SendOSC and RecvOSC.
class (SendOSC m, RecvOSC m) => DuplexOSC m
-- | Transport is DuplexOSC with a MonadIO constraint.
class (DuplexOSC m, MonadIO m) => Transport m
-- | Transport connection.
type Connection t a = ReaderT t IO a
-- | Bracket Open Sound Control communication.
withTransport :: Transport t => IO t -> Connection t a -> IO a
-- | Type restricted synonym for sendOSC.
sendMessage :: SendOSC m => Message -> m ()
-- | Type restricted synonym for sendOSC.
sendBundle :: SendOSC m => Bundle -> m ()
-- | Variant of recvPacket that runs fromPacket.
recvOSC :: (RecvOSC m, OSC o) => m (Maybe o)
-- | Variant of recvPacket that runs packet_to_bundle.
recvBundle :: RecvOSC m => m Bundle
-- | Variant of recvPacket that runs packet_to_message.
recvMessage :: RecvOSC m => m (Maybe Message)
-- | Variant of recvPacket that runs packetMessages.
recvMessages :: RecvOSC m => m [Message]
-- | Wait for a Packet where the supplied predicate is True,
-- discarding intervening packets.
waitUntil :: RecvOSC m => (Packet -> Bool) -> m Packet
-- | Wait for a Packet where the supplied function does not give
-- Nothing, discarding intervening packets.
waitFor :: RecvOSC m => (Packet -> Maybe a) -> m a
-- | waitUntil packet_is_immediate.
waitImmediate :: RecvOSC m => m Packet
-- | waitFor packet_to_message, ie. an incoming
-- Message or immediate mode Bundle with one element.
waitMessage :: RecvOSC m => m Message
-- | A waitFor for variant using packet_has_address to match
-- on the Address_Pattern of incoming Packets.
waitAddress :: RecvOSC m => Address_Pattern -> m Packet
-- | Variant on waitAddress that returns matching Message.
waitReply :: RecvOSC m => Address_Pattern -> m Message
-- | Variant of waitReply that runs messageDatum.
waitDatum :: RecvOSC m => Address_Pattern -> m [Datum]
instance (Transport t, MonadIO io) => Transport (ReaderT t io)
instance (Transport t, MonadIO io) => DuplexOSC (ReaderT t io)
instance (Transport t, MonadIO io) => RecvOSC (ReaderT t io)
instance (Transport t, MonadIO io) => SendOSC (ReaderT t io)
-- | Composite of non-transport related modules.
--
-- Provides the Datum, Message, Bundle and
-- Packet types and the OSC and Coding type-classes.
--
-- The basic constructors are message and bundle, the basic
-- coding functions are encodePacket and decodePacket.
--
--
-- import Sound.OpenSoundControl
--
-- let {o = bundle immediately [message "/g_free" [Int 0]]
-- ;e = encodeBundle o :: String}
-- in decodeBundle e == o
--
module Sound.OpenSoundControl
-- | Composite of Sound.OpenSoundControl and
-- Sound.OSC.Transport.Monad.
module Sound.OSC
-- | Composite of Sound.OpenSoundControl and
-- Sound.OSC.Transport.FD.
module Sound.OSC.FD