echo-0.1.4: A cross-platform, cross-console way to handle echoing terminal input

Copyright | (C) 2016-2017 Ryan Scott
License | BSD-style (see the file LICENSE)
Maintainer | Ryan Scott
Stability | Provisional
Portability | Portable
Safe Haskell | Safe
Language | Haskell2010

System.IO.Echo.Internal

Contents

- Safe public interface
- Alternative (safe) interface
- Unsafe STTY internals
- MinTTY

Description

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!

Synopsis

- withoutInputEcho :: IO a -> IO a
- bracketInputEcho :: IO a -> IO a
- getInputEchoState :: IO EchoState
- setInputEchoState :: EchoState -> IO ()
- echoOff :: EchoState
- echoOn :: EchoState
- getInputEcho :: IO Bool
- setInputEcho :: Bool -> IO ()
- data EchoState
  - = MinTTY STTYSettings
  - | DefaultTTY Bool
- type STTYSettings = String
- getInputEchoSTTY :: IO STTYSettings
- setInputEchoSTTY :: STTYSettings -> IO ()
- sttyRaw :: String -> IO STTYSettings
- minTTY :: Bool

# Safe public interface

withoutInputEcho :: IO a -> IO a Source #

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)

bracketInputEcho :: IO a -> IO a Source #

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)

getInputEchoState :: IO EchoState Source #

Return the terminal's current input `EchoState`.

setInputEchoState :: EchoState -> IO () Source #

Set the terminal's input `EchoState`.

echoOff :: EchoState Source #

Indicates that the terminal's input echoing is (or should be) off.

echoOn :: EchoState Source #

Indicates that the terminal's input echoing is (or should be) on.

# Alternative (safe) interface

getInputEcho :: IO Bool Source #

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.

setInputEcho :: Bool -> IO () Source #

Set the terminal's echoing on (`True`) or off (`False`).

# Unsafe STTY internals

data EchoState Source #

A representation of the terminal input's current echoing state. Example values include `echoOff` and `echoOn`.

Constructors

MinTTY STTYSettings

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.

DefaultTTY Bool | 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.

#### Instances

Instances details

Show EchoState Source # |
Instance details Defined in System.IO.Echo.Internal Methods showsPrec :: Int -> EchoState -> ShowS Source # show :: EchoState -> String Source # showList :: [EchoState] -> ShowS Source #
Eq EchoState Source # |
Instance details Defined in System.IO.Echo.Internal Methods (==) :: EchoState -> EchoState -> Bool Source # (/=) :: EchoState -> EchoState -> Bool Source #
Ord EchoState Source # |

Instance details

Defined in System.IO.Echo.Internal

Methods

compare :: EchoState -> EchoState -> Ordering Source #

(<) :: EchoState -> EchoState -> Bool Source #

(<=) :: EchoState -> EchoState -> Bool Source #

(>) :: EchoState -> EchoState -> Bool Source #

(>=) :: EchoState -> EchoState -> Bool Source #

max :: EchoState -> EchoState -> EchoState Source #

min :: EchoState -> EchoState -> EchoState Source #

type STTYSettings = String Source #

Settings used to configure the `stty` command-line utility.

getInputEchoSTTY :: IO STTYSettings Source #

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

setInputEchoSTTY :: STTYSettings -> IO () Source #

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

sttyRaw :: String -> IO STTYSettings Source #

Create an `stty` process, wait for it to complete, and return its output.

# MinTTY

minTTY :: Bool Source #

Is the current process attached to a MinTTY console (e.g., Cygwin or MSYS)?