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


-- | 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 -> String -> String -> IO SerialManager

-- | Having multiple serial managers running on the same port is a disaster
--   waiting to happen. When you're done with a <a>SerialManager</a>, run
--   <a>closeSerialManager</a> on it to shut it down.
closeSerialManager :: SerialManager -> IO ()

-- | 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 = ("2LOG" `isPrefixOf`)
--   </pre>
--   
--   <pre>
--   login mgr = wrapCommand "\r\n" "2LOG IN" p
--   </pre>
--   
--   <a>wrapCommand</a> uses functions of type 'String -&gt; Bool' 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.
wrapCommand :: String -> (String -> Bool) -> SerialManager -> IO String

-- | Sometimes we don't want the current thread to block, but we still want
--   some action when the a command returns from the serial port. To that
--   end, <a>wrapCommandWithCallback</a> lets us pass a function of type
--   'String -&gt; IO ()' to be executed when a response is recognized by
--   the predicate.
wrapCommandWithCallback :: String -> (String -> Bool) -> (String -> IO ()) -> SerialManager -> IO ThreadId
data SerialManager
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