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

-- | A cross-platform, cross-console way to handle echoing terminal input
--   
--   The base library exposes the hGetEcho and
--   hSetEcho functions for querying and setting echo status, but
--   unfortunately, neither function works with MinTTY consoles on Windows.
--   This is a serious issue, since hGetEcho and hSetEcho
--   are often used to disable input echoing when a program prompts for a
--   password, so many programs will reveal your password as you type it on
--   MinTTY!
--   
--   This library provides an alternative interface which works with both
--   MinTTY and other consoles. An example is included which demonstrates
--   how one might prompt for a password using this library. To build it,
--   make sure to configure with the -fexample flag.
@package echo
@version 0.1.4

-- | Exports functions that handle whether or not terminal input is handled
--   in a way that should be portable across different platforms and
--   consoles.
--   
--   Unlike System.IO.Echo, this module exports internal
--   functionality which, if used improperly, can lead to runtime errors.
--   Make sure to read the documentation beforehand!
module System.IO.Echo.Internal

-- | Perform a computation with the terminal's input echoing disabled.
--   Before running the computation, the terminal's input EchoState
--   is saved, and the saved EchoState is restored after the
--   computation finishes.
--   
--   
--   withoutInputEcho action = bracketInputEcho (setInputEchoState echoOff >> action)
--   
withoutInputEcho :: IO a -> IO a

-- | Save the terminal's current input EchoState, perform a
--   computation, restore the saved EchoState, and then return the
--   result of the computation.
--   
--   
--   bracketInputEcho action = bracket getInputEchoState setInputEchoState (const action)
--   
bracketInputEcho :: IO a -> IO a

-- | Return the terminal's current input EchoState.
getInputEchoState :: IO EchoState

-- | Set the terminal's input EchoState.
setInputEchoState :: EchoState -> IO ()

-- | Indicates that the terminal's input echoing is (or should be) off.
echoOff :: EchoState

-- | Indicates that the terminal's input echoing is (or should be) on.
echoOn :: EchoState

-- | Return whether the terminal's echoing is on (True) or off
--   (False).
--   
--   Note that while this works on MinTTY, it is not as efficient as
--   getInputEchoState, as it involves a somewhat expensive
--   substring computation.
getInputEcho :: IO Bool

-- | Set the terminal's echoing on (True) or off (False).
setInputEcho :: Bool -> IO ()

-- | A representation of the terminal input's current echoing state.
--   Example values include echoOff and echoOn.
data EchoState

-- | The argument to (or value returned from) an invocation of the
--   stty command-line utility. Most POSIX-like shells have
--   stty, including MinTTY on Windows. Since neither
--   hGetEcho nor hSetEcho work on MinTTY, when
--   getInputEchoState runs on MinTTY, it returns a value built with
--   this constructor.
--   
--   However, native Windows consoles like cmd.exe or PowerShell
--   do not have stty, so if you construct an EchoState
--   with this constructor manually, take care not to use it with a native
--   Windows console.
MinTTY :: STTYSettings -> EchoState

-- | A simple on (True) or off (False) toggle. This is
--   returned by hGetEcho and given as an argument to
--   hSetEcho, which work on most consoles, with the notable
--   exception of MinTTY on Windows. If you construct an EchoState
--   with this constructor manually, take care not to use it with MinTTY.
DefaultTTY :: Bool -> EchoState

-- | Settings used to configure the stty command-line utility.
type STTYSettings = String

-- | Return all of stty's current settings in a non-human-readable
--   format.
--   
--   This function is not very useful on its own. Its greater purpose is to
--   provide a compact STTYSettings that can be fed back into
--   setInputEchoState.
getInputEchoSTTY :: IO STTYSettings

-- | Create an stty process and wait for it to complete. This is
--   useful for changing stty's settings, after which
--   stty does not output anything.
--   
--   
--   setInputEchoSTTY = void . sttyRaw
--   
setInputEchoSTTY :: STTYSettings -> IO ()

-- | Create an stty process, wait for it to complete, and return
--   its output.
sttyRaw :: String -> IO STTYSettings

-- | Is the current process attached to a MinTTY console (e.g., Cygwin or
--   MSYS)?
minTTY :: Bool
instance GHC.Classes.Eq System.IO.Echo.Internal.EchoState
instance GHC.Classes.Ord System.IO.Echo.Internal.EchoState
instance GHC.Internal.Show.Show System.IO.Echo.Internal.EchoState

-- | Exports functions that handle whether or not terminal input is handled
--   in a way that should be portable across different platforms and
--   consoles.
module System.IO.Echo

-- | Perform a computation with the terminal's input echoing disabled.
--   Before running the computation, the terminal's input EchoState
--   is saved, and the saved EchoState is restored after the
--   computation finishes.
--   
--   
--   withoutInputEcho action = bracketInputEcho (setInputEchoState echoOff >> action)
--   
withoutInputEcho :: IO a -> IO a

-- | Save the terminal's current input EchoState, perform a
--   computation, restore the saved EchoState, and then return the
--   result of the computation.
--   
--   
--   bracketInputEcho action = bracket getInputEchoState setInputEchoState (const action)
--   
bracketInputEcho :: IO a -> IO a

-- | Return the terminal's current input EchoState.
getInputEchoState :: IO EchoState

-- | Set the terminal's input EchoState.
setInputEchoState :: EchoState -> IO ()

-- | A representation of the terminal input's current echoing state.
--   Example values include echoOff and echoOn.
data EchoState

-- | Indicates that the terminal's input echoing is (or should be) off.
echoOff :: EchoState

-- | Indicates that the terminal's input echoing is (or should be) on.
echoOn :: EchoState

-- | Return whether the terminal's echoing is on (True) or off
--   (False).
--   
--   Note that while this works on MinTTY, it is not as efficient as
--   getInputEchoState, as it involves a somewhat expensive
--   substring computation.
getInputEcho :: IO Bool

-- | Set the terminal's echoing on (True) or off (False).
setInputEcho :: Bool -> IO ()
