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


-- | Pseudo terminal interaction with subprocesses.
--   
--   This package simplifies the creation of subprocesses that interact
--   with their parent via a pseudo terminal (see <tt>man pty</tt>).
@package posix-pty
@version 0.2.1.1


-- | A module for interacting with subprocesses through a pseudo terminal
--   (pty). Provides functions for reading from, writing to and resizing
--   pseudo terminals. Re-exports most of <a>System.Posix.Terminal</a>,
--   providing wrappers that work with the <a>Pty</a> type where necessary.
module System.Posix.Pty

-- | Create a new process that is connected to the current process through
--   a pseudo terminal. If an environment is specified, then only the
--   specified environment variables will be set. If no environment is
--   specified the process will inherit its environment from the current
--   process. Example:
--   
--   <pre>
--   pty &lt;- spawnWithPty (Just [("SHELL", "tcsh")]) True "ls" ["-l"] (20, 10)
--   </pre>
--   
--   This searches the user's PATH for a binary called <tt>ls</tt>, then
--   runs this binary with the commandline argument <tt>-l</tt> in a
--   terminal that is 20 characters wide and 10 characters high. The
--   environment of <tt>ls</tt> will contains one variable, SHELL, which
--   will be set to the value "tcsh".
spawnWithPty :: Maybe [(String, String)] -> Bool -> FilePath -> [String] -> (Int, Int) -> IO (Pty, ProcessHandle)

-- | Abstract pseudo terminal type.
data Pty

-- | Pseudo terminal control information.
--   
--   <ul>
--   <li><i>Terminal read queue</i> The terminal read queue contains the
--   data that was written from the master terminal to the slave terminal,
--   which was not read from the slave yet.</li>
--   <li><i>Terminal write queue</i> The terminal write queue contains the
--   data that was written from the slave terminal, which was not sent to
--   the master yet.</li>
--   </ul>
data PtyControlCode

-- | Terminal read queue was flushed.
FlushRead :: PtyControlCode

-- | Terminal write queue was flushed.
FlushWrite :: PtyControlCode

-- | Terminal output was stopped.
OutputStopped :: PtyControlCode

-- | Terminal output was restarted.
OutputStarted :: PtyControlCode

-- | Terminal stop and start characters are <tt>^S</tt> and <tt>^Q</tt>
--   respectively.
DoStop :: PtyControlCode

-- | Terminal stop and start characters are NOT <tt>^S</tt> and
--   <tt>^Q</tt>.
NoStop :: PtyControlCode

-- | Produces a <a>Pty</a> if the file descriptor is associated with a
--   terminal and Nothing if not.
createPty :: Fd -> IO (Maybe Pty)

-- | Close this pseudo terminal.
closePty :: Pty -> IO ()

-- | Attempt to read data from a pseudo terminal. Produces either the data
--   read or a list of <a>PtyControlCode</a><tt>s</tt> indicating which
--   control status events that have happened on the slave terminal.
--   
--   Throws an <a>IOError</a> of type <a>eofErrorType</a> when the terminal
--   has been closed, for example when the subprocess has terminated.
tryReadPty :: Pty -> IO (Either [PtyControlCode] ByteString)

-- | The same as <a>tryReadPty</a>, but discards any control status events.
readPty :: Pty -> IO ByteString

-- | Write a <a>ByteString</a> to the pseudo terminal, throws an
--   <a>IOError</a> when the terminal has been closed, for example when the
--   subprocess has terminated.
writePty :: Pty -> ByteString -> IO ()

-- | Set the pseudo terminal's dimensions to the specified width and
--   height.
resizePty :: Pty -> (Int, Int) -> IO ()

-- | Produces the pseudo terminal's current dimensions.
ptyDimensions :: Pty -> IO (Int, Int)

-- | Equivalent to <a>threadWaitRead</a>.
threadWaitReadPty :: Pty -> IO ()

-- | Equivalent to <a>threadWaitWrite</a>.
threadWaitWritePty :: Pty -> IO ()

-- | Equivalent to <a>threadWaitReadSTM</a>.
threadWaitReadPtySTM :: Pty -> IO (STM (), IO ())

-- | Equivalent to <a>threadWaitWriteSTM</a>.
threadWaitWritePtySTM :: Pty -> IO (STM (), IO ())

-- | See <a>getTerminalAttributes</a>.
getTerminalAttributes :: Pty -> IO TerminalAttributes

-- | See <a>setTerminalAttributes</a>.
setTerminalAttributes :: Pty -> TerminalAttributes -> TerminalState -> IO ()

-- | See <a>sendBreak</a>.
sendBreak :: Pty -> Int -> IO ()

-- | See <a>drainOutput</a>.
drainOutput :: Pty -> IO ()

-- | See <a>discardData</a>.
discardData :: Pty -> QueueSelector -> IO ()

-- | See <a>controlFlow</a>.
controlFlow :: Pty -> FlowAction -> IO ()

-- | See <a>getTerminalProcessGroupID</a>.
getTerminalProcessGroupID :: Pty -> IO ProcessGroupID

-- | See <a>getTerminalName</a>.
getTerminalName :: Pty -> IO FilePath

-- | See <a>getSlaveTerminalName</a>.
getSlaveTerminalName :: Pty -> IO FilePath
instance GHC.Show.Show System.Posix.Pty.PtyControlCode
instance GHC.Read.Read System.Posix.Pty.PtyControlCode
instance GHC.Classes.Eq System.Posix.Pty.PtyControlCode
