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


-- | POSIX serial port wrapper
--   
--   Provides a clean interface to working with POSIX serial ports in
--   Haskell
@package serial
@version 0.2.2


-- | This is a largely drop-in replacement for <a>System.Serial.Manager</a>
--   which sends and receives one command at a time from the port, and so
--   is garuanteed to send the write information back to the right
--   function. It may be necessary when working with devices that have
--   ambiguous returns, such as a single acknowledgement character for all
--   successful commands. See the analagous functions in
--   <a>System.Serial.Manager</a> for the full documentation. The notes
--   here only point out the differences.
module System.Serial.BlockingManager

-- | The blocking <a>serialManager</a> function takes one additional
--   argument, the timeout (since it cannot continue executing commands in
--   parallel while one command freezes).
serialManager :: Handle -> Int -> IO BlockingSerialManager

-- | Wrapping commands is identical to the non-blocking version except that
--   there is no predicate to recognize return values.
wrapCommand :: String -> String -> BlockingSerialManager -> IO (Maybe String)
type BlockingSerialManager = MVar BlockingSerialCommand
type BlockingSerialCommand = (String, MVar (Maybe String))


-- | Many serial devices allow multiple commands to run at once, and |
--   return their results as they finish. To make use of this, | multiple
--   commands needs to read and write to the serial port at | once, and the
--   return values must somehow be sorted and returned | back to the
--   callers.
module System.Serial.Manager

-- | <a>serialManager</a> takes produces a structure around a <a>Handle</a>
--   to | handle multiple callers to the serial port. The return value is |
--   the channel to which all commands will flow. Users should use | the
--   <a>wrapCommand</a> function to access it instead of trying to | access
--   its details directly.
serialManager :: Handle -> IO SerialManager

-- | All the commands to operate a <a>SerialManager</a> should be
--   specializations of <a>wrapCommand</a>, created by applying it to the
--   first three arguments, then using that thereafter as the command to
--   the serial port.
--   
--   For example, the Olympus IX-81 requires a login command from the user
--   (<tt>2LOG IN</tt>) followed by <tt>rn</tt> as an end of line. The
--   response will be <tt>2LOG +</tt> followed by <tt>r</tt>. So a login
--   command would look like
--   
--   <pre>
--   p = do string "2LOG +\r"
--          return True
--   </pre>
--   
--   <pre>
--   login mgr = wrapCommand "\r\n" "2LOG IN" p
--   </pre>
--   
--   <a>wrapCommand</a> uses parsers that return <a>Bool</a> so users can
--   choose whether or not to match any given command based upon its
--   contents, rather than just blindly saying whether it matches or not.
--   This may change to simple predicates of <tt>String -&gt; Bool</tt> in
--   future.
wrapCommand :: String -> String -> (String -> Bool) -> SerialManager -> IO String
type SerialManager = MVar (Either SerialCommand String)
type SerialCommand = (String, String -> Bool, MVar String)


-- | Serial provides access to serial ports on POSIX compatible systems.
--   The utility functions in <a>System.Serial</a> are in line-at-a-time
--   mode by default, but you can set other, more raw modes with
--   <a>hSetBuffering</a> from <a>System.IO</a>. The serial port managers
--   in <a>System.Serial.Manager</a> and
--   <a>System.Serial.BlockingManager</a> only work with line-at-a-time
--   mode.
--   
--   Most devices hanging off of serial ports today work by reading and
--   writing commands. In many cases, commands are non-blocking and you can
--   send additional commands before you receive the response to the last
--   one. <a>System.Serial.SerialManager</a> provides a wrapper around this
--   access which tries to match up responses to waiting functions which
--   have called it.
--   
--   The only function here is <a>openSerial</a>, since thereafter the
--   normal functions from <a>System.IO</a> such as <a>hClose</a>,
--   <a>hGetLine</a>, and <a>hPutStr</a> work normally. Just be sure you
--   send the right end of line sequence for your hardware! Some devices
--   want CR-LF, others just LF, others just CR, and they may return their
--   results using a different end of line than they accept.
module System.Serial

-- | <a>openSerial</a> opens the serial port and sets the options the user
--   passes, makes its buffering line oriented, and returns the handle to
--   control it. For example, an Olympus IX-81 microscope attached to the
--   first serial port on Linux would be opened with
--   
--   <pre>
--   openSerial "/dev/ttyS0" B19200 8 One Even Software
--   </pre>
openSerial :: String -> BaudRate -> Int -> StopBits -> Parity -> FlowControl -> IO Handle

-- | <a>Serial</a> lets the user set the number of stop bits, the parity,
--   flow control (there is no hardware flow control, since it isn't
--   supported in the <a>System.Posix.IO</a> library), number of bits per
--   byte, and the baud rate. The baud rate is declared by the
--   <a>BaudRate</a> in <a>System.Posix.Terminal</a>. <a>StopBits</a>,
--   <a>Parity</a>, and <a>FlowControl</a> are defined here.
data StopBits
One :: StopBits
Two :: StopBits
data Parity
Even :: Parity
Odd :: Parity
NoParity :: Parity
data FlowControl
Software :: FlowControl
NoFlowControl :: FlowControl