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


-- | A cross-platform, cross-console way to handle echoing terminal input
--   
--   The <tt>base</tt> library exposes the <tt>hGetEcho</tt> and
--   <tt>hSetEcho</tt> functions for querying and setting echo status, but
--   unfortunately, neither function works with MinTTY consoles on Windows.
--   This is a serious issue, since <tt>hGetEcho</tt> and <tt>hSetEcho</tt>
--   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 <tt>-fexample</tt> flag.
@package echo
@version 0.1.2


-- | Exports functions that handle whether or not terminal input is handled
--   in a way that should be portable across different platforms and
--   consoles.
--   
--   Unlike <a>System.IO.Echo</a>, 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 <a>EchoState</a>
--   is saved, and the saved <a>EchoState</a> is restored after the
--   computation finishes.
--   
--   <pre>
--   withoutInputEcho action = <a>bracketInputEcho</a> (<a>setInputEchoState</a> <a>echoOff</a> &gt;&gt; action)
--   </pre>
withoutInputEcho :: IO a -> IO a

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

-- | Return the terminal's current input <a>EchoState</a>.
getInputEchoState :: IO EchoState

-- | Set the terminal's input <a>EchoState</a>.
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 (<a>True</a>) or off
--   (<a>False</a>).
--   
--   Note that while this works on MinTTY, it is not as efficient as
--   <a>getInputEchoState</a>, as it involves a somewhat expensive
--   substring computation.
getInputEcho :: IO Bool

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

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

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

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

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

-- | Return all of <tt>stty</tt>'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 <a>STTYSettings</a> that can be fed back into
--   <a>setInputEchoState</a>.
getInputEchoSTTY :: IO STTYSettings

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

-- | Create an <tt>stty</tt> 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.Show.Show System.IO.Echo.Internal.EchoState
instance GHC.Classes.Ord System.IO.Echo.Internal.EchoState
instance GHC.Classes.Eq 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 <a>EchoState</a>
--   is saved, and the saved <a>EchoState</a> is restored after the
--   computation finishes.
--   
--   <pre>
--   withoutInputEcho action = <a>bracketInputEcho</a> (<a>setInputEchoState</a> <a>echoOff</a> &gt;&gt; action)
--   </pre>
withoutInputEcho :: IO a -> IO a

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

-- | Return the terminal's current input <a>EchoState</a>.
getInputEchoState :: IO EchoState

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

-- | A representation of the terminal input's current echoing state.
--   Example values include <a>echoOff</a> and <a>echoOn</a>.
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 (<a>True</a>) or off
--   (<a>False</a>).
--   
--   Note that while this works on MinTTY, it is not as efficient as
--   <a>getInputEchoState</a>, as it involves a somewhat expensive
--   substring computation.
getInputEcho :: IO Bool

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