-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell Open Sound Control
--   
--   <tt>hosc</tt> provides <a>Sound.OpenSoundControl</a>, an
--   implementation of a subset of the <i>Open Sound Control</i> byte
--   protocol documented at <a>http://opensoundcontrol.org/</a>.
@package hosc
@version 0.11


-- | 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 <a>f32_w32</a>.
w32_f32 :: Word32 -> Float

-- | The IEEE byte representation of a double.
f64_w64 :: Double -> Word64

-- | Inverse of <tt>f64_i64</tt>.
w64_f64 :: Word64 -> Double

-- | Transform a haskell string into a C string (a null suffixed byte
--   string).
str_cstr :: String -> [Word8]

-- | Inverse of <a>str_cstr</a>.
cstr_str :: [Word8] -> String

-- | Transform a haskell string to a pascal string (a length prefixed byte
--   string).
str_pstr :: String -> [Word8]

-- | Inverse of <a>str_pstr</a>.
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.
align :: Bits i => i -> i


-- | Temporal representations and clock operations (read current time and
--   pause thread).
module Sound.OpenSoundControl.Time

-- | Type for integer representation of NTP time.
type NTPi = Word64

-- | Time is represented in either <tt>UTC</tt> or <tt>NTP</tt> form. The
--   <tt>NTP</tt> form may be either integral or real.
data Time
UTCr :: Double -> Time
NTPr :: Double -> Time
NTPi :: NTPi -> Time

-- | Coerce <a>Time</a> to integral <tt>NTP</tt> form.
as_ntpi :: Time -> NTPi

-- | Coerce <a>Time</a> to real-valued <tt>UTC</tt> form.
as_utcr :: Time -> Double

-- | Convert a real-valued NTP timestamp to an <a>NTPi</a> timestamp.
ntpr_ntpi :: Double -> NTPi

-- | Convert an <a>NTPi</a> timestamp to a real-valued NTP timestamp.
ntpi_ntpr :: NTPi -> Double

-- | Convert a real-valued UTC timestamp to an <a>NTPi</a> timestamp.
utcr_ntpi :: Double -> NTPi

-- | Convert a real-valued NTP timestamp to a real-valued UTC timestamp.
ntpr_utcr :: Double -> Double

-- | Convert an <a>NTPi</a> timestamp to a real-valued UTC timestamp.
ntpi_utcr :: NTPi -> Double

-- | The time at 1970-01-01:00:00:00.
utc_base :: UTCTime

-- | Constant indicating the bundle is to be executed immediately.
immediately :: Time

-- | Read current real-valued <tt>UTC</tt> timestamp.
utcr :: IO Double

-- | Read current <a>NTPi</a> timestamp.
ntpi :: IO NTPi

-- | The <a>pauseThread</a> limit (in seconds). Values larger than this
--   require a different thread delay mechanism, see <a>sleepThread</a>.
--   The value is the number of microseconds in <tt>maxBound::Int</tt>.
pauseThreadLimit :: Double

-- | Pause current thread for the indicated duration (in seconds), see
--   <a>pauseThreadLimit</a>. Note also that this function does not attempt
--   pauses less than <tt>1e-4</tt>.
pauseThread :: Double -> IO ()

-- | Pause current thread until the given real-valued <tt>UTC</tt> time,
--   see <a>pauseThreadLimit</a>.
pauseThreadUntil :: Double -> IO ()

-- | Sleep current thread for the indicated duration (in seconds). Divides
--   long sleeps into parts smaller than <a>pauseThreadLimit</a>.
sleepThread :: Double -> IO ()

-- | Sleep current thread until the given real-valued <tt>UTC</tt> time.
--   Divides long sleeps into parts smaller than <a>pauseThreadLimit</a>.
sleepThreadUntil :: Double -> IO ()
instance Read Time
instance Show Time
instance Ord Time
instance Eq Time


-- | Alegbraic data types for OSC datum and packets.
module Sound.OpenSoundControl.Type

-- | An OSC packet.
data OSC
Message :: String -> [Datum] -> OSC
Bundle :: Time -> [OSC] -> OSC

-- | 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

-- | Message constructor. It is an <a>error</a> if the address doesn't
--   conform to the OSC specification.
message :: String -> [Datum] -> OSC

-- | Bundle constructor. It is an <a>error</a> if the <a>OSC</a> list is
--   empty.
bundle :: Time -> [OSC] -> OSC

-- | Single character identifier of an OSC datum.
tag :: Datum -> Char
instance Eq Datum
instance Read Datum
instance Show Datum
instance Eq OSC
instance Read OSC
instance Show OSC
instance Ord OSC


-- | An abstract transport layer. hosc provides implementations for UDP and
--   TCP transport.
module Sound.OpenSoundControl.Transport

-- | Abstract over the underlying transport protocol.
class Transport t
send :: Transport t => t -> OSC -> IO ()
recv :: Transport t => t -> IO OSC
close :: Transport t => t -> IO ()

-- | Bracket OSC communication.
withTransport :: Transport t => IO t -> (t -> IO a) -> IO a

-- | Variant that wraps <a>recv</a> in an <i>n</i> second <a>timeout</a>.
recvT :: Transport t => Double -> t -> IO (Maybe OSC)

-- | Wait for an OSC message where the supplied function does not give
--   Nothing, discarding intervening messages.
waitFor :: Transport t => t -> (OSC -> Maybe a) -> IO a

-- | A <a>waitFor</a> for variant matching on the address string of
--   incoming messages.
wait :: Transport t => t -> String -> IO OSC


-- | Optimised decode function for OSC packets.
module Sound.OpenSoundControl.Coding.Decode.Binary

-- | Get an OSC packet.
getOSC :: Get OSC

-- | Decode an OSC packet from a lazy ByteString.
--   
--   <pre>
--   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]
--   </pre>
decodeOSC :: ByteString -> OSC

-- | Decode an OSC packet from a strict ByteString.
decodeOSC' :: ByteString -> OSC


-- | Optimised encode function for OSC packets.
module Sound.OpenSoundControl.Coding.Encode.Builder

-- | Builder monoid for an OSC packet.
buildOSC :: OSC -> Builder

-- | Encode an OSC packet to a lazy ByteString.
--   
--   <pre>
--   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
--   </pre>
encodeOSC :: OSC -> ByteString

-- | Encode an OSC packet to a strict ByteString.
encodeOSC' :: OSC -> 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
encodeOSC :: Coding a => OSC -> a
decodeOSC :: Coding a => a -> OSC

-- | An <a>encodeOSC</a> and <a>decodeOSC</a> pair over <a>ByteString</a>.
type Coder = (OSC -> ByteString, ByteString -> OSC)
instance Coding String
instance Coding ByteString
instance Coding ByteString


-- | OSC over UDP implementation.
module Sound.OpenSoundControl.Transport.UDP

-- | The UDP transport handle data type.
data UDP
UDP :: (OSC -> ByteString) -> (ByteString -> OSC) -> Socket -> UDP
udpEncode :: UDP -> OSC -> ByteString
udpDecode :: UDP -> ByteString -> OSC
udpSocket :: UDP -> Socket

-- | Return the port number associated with the UDP socket.
udpPort :: Integral n => UDP -> IO n

-- | Make a UDP connection with specified coder.
openUDP' :: Coder -> String -> Int -> IO UDP

-- | Trivial udp server with specified coder.
udpServer' :: Coder -> String -> Int -> IO UDP

-- | Send variant to send to specified address.
sendTo :: UDP -> OSC -> SockAddr -> IO ()

-- | Recv variant to collect message source address.
recvFrom :: UDP -> IO (OSC, SockAddr)
instance Transport UDP


-- | OSC over TCP implementation.
module Sound.OpenSoundControl.Transport.TCP

-- | The TCP transport handle data type.
data TCP
TCP :: (OSC -> ByteString) -> (ByteString -> OSC) -> Handle -> TCP
tcpEncode :: TCP -> OSC -> ByteString
tcpDecode :: TCP -> ByteString -> OSC
tcpHandle :: TCP -> Handle

-- | Make a TCP connection using specified coder.
openTCP' :: Coder -> String -> Int -> IO TCP

-- | A trivial TCP OSC server using specified coder.
tcpServer' :: Coder -> Int -> (TCP -> IO ()) -> IO ()
instance Transport TCP


-- | OSC packet coercion and normalization.
module Sound.OpenSoundControl.Coding.Coerce

-- | Map a normalizing function over datum at an osc packet.
coerce :: (Datum -> Datum) -> OSC -> OSC

-- | 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

-- | A normalized osc packet has only Int and Double numerical values.
normalize :: OSC -> OSC


-- | Base-level decode function for OSC packets (slow). For ordinary use
--   see <tt>Sound.OpenSoundControl.Coding.Decode.Binary</tt>.
module Sound.OpenSoundControl.Coding.Decode.Base

-- | Decode an OSC packet.
--   
--   <pre>
--   let b = B.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]
--   </pre>
decodeOSC :: ByteString -> OSC


-- | Base-level encode function for OSC packets (slow). For ordinary use
--   see <tt>Sound.OpenSoundControl.Coding.Encode.Builder</tt>.
module Sound.OpenSoundControl.Coding.Encode.Base

-- | Encode an OSC packet.
encodeOSC :: OSC -> ByteString


-- | An implementation of a subset of the <i>Open Sound Control</i> byte
--   protocol, documented at <a>http://opensoundcontrol.org/</a>.
--   
--   For the most part this top-level module is the only import required.
--   It provides the <a>Datum</a> and <a>OSC</a> types, <a>encodeOSC</a>
--   and <a>decodeOSC</a> functions, basic <a>UDP</a> and <a>TCP</a>
--   <a>Transport</a> layers, and basic temporal operations <a>utcr</a> to
--   access the current time and <a>pauseThread</a> to delay the current
--   thread.
--   
--   <pre>
--   let o = Bundle immediately [Message "/g_free" [Int 0]]
--   in decodeOSC (encodeOSC o) == o
--   </pre>
module Sound.OpenSoundControl

-- | Encode an OSC packet to a lazy ByteString.
--   
--   <pre>
--   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
--   </pre>
encodeOSC :: OSC -> ByteString

-- | Decode an OSC packet from a lazy ByteString.
--   
--   <pre>
--   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]
--   </pre>
decodeOSC :: ByteString -> OSC

-- | Make a UDP connection.
--   
--   <pre>
--   let t = openUDP "127.0.0.1" 57110
--   in withTransport t (\fd -&gt; recvT 0.5 fd &gt;&gt;= print)
--   </pre>
openUDP :: String -> Int -> IO UDP

-- | Trivial udp server.
udpServer :: String -> Int -> IO UDP

-- | Make a TCP connection.
openTCP :: String -> Int -> IO TCP

-- | A trivial TCP OSC server.
tcpServer :: Int -> (TCP -> IO ()) -> IO ()