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


-- | 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 -> Parser Bool -> SerialManager -> IO String
type SerialManager = MVar (Either SerialCommand String)
type SerialCommand = (String, Parser Bool, MVar String)


-- | Serial provides line-oriented access to serial ports on POSIX
--   compatible systems. If you need low level access, character-at-a-time
--   reading and writing, or other such procedures, you need to access the
--   serial port directly; this library won't help you. However, 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