escaped: Produce Text with terminal escape sequences

[ library, mit, program, text ] [ Propose Tags ]


[Skip to Readme]
Versions [faq]
Change log
Dependencies base (>=4.7 && <5), escaped, QuickCheck, quickcheck-instances, text, unix [details]
License MIT
Copyright 2018 Patrick Brisbin
Author Patrick Brisbin
Category Text
Home page
Bug tracker
Source repo head: git clone
Uploaded by PatrickBrisbin at Wed Nov 21 19:32:01 UTC 2018
Distributions NixOS:
Executables escaped-example
Downloads 133 total (4 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2018-11-21 [all 1 reports]


[Index] [Quick Jump]


Maintainer's Corner

For package maintainers and hackage trustees

Readme for escaped-

[back to package description]


Produce Text with terminal escape sequences.


Quick Start

{-# LANGUAGE OverloadedStrings #-}
module Main where

import Data.Semigroup ((<>))
import Data.Text.Escaped
import qualified Data.Text.IO as T

main :: IO ()
main = T.putStrLn $ render $ "This is " <> red "red" <> " text."


Running the example executable will produce everything this library currently supports:


Helper Functions

The above uses the red helper function, which prefixes the given value with the (foreground) color red, then resets after.

NOTE: this function composes Escapeds, so you can nest:

"This is " <> red (bg Blue "red on blue") <> " text."

The Escaped Type

Behind those helpers, a Semigroup instance, and the OverLoadedStrings extension, what you're actually doing is building up a value of type Escaped:

λ> :set -XOverloadedStrings
λ> "one" <> red "red" <> "three"
Many [Plain "one",FG Red,Plain "red",Reset,Plain "three"]
λ> render it

The Escaped type has constructors for the various shell escapes and is meant to be used directly for non-trivial cases.

"This is " <> Blink <> FG Red <> "blinking red" <> Reset <> " text."

If you need to interpolate non-literals of type Text, use the Plain constructor:

logMessage :: Level -> Text -> Escaped
logMessage l msg = "[" <> prefix <> "] " <> Plain msg
    prefix :: Level -> Escaped
    prefix Info = blue "INFO"
    prefix Warn = yellow "WARN"
    -- etc.

Terminal Applications

The terminalRenderer function queries if stdout is connected to a tty and returns render or plain as appropriate:

main = do
    r <- terminalRenderer

    T.putStrLn $ r $
        "This will be escaped as "
        <> red "red"
        <> " only if we're connected to a tty."

Development & Testing

stack setup
stack build --pedantic test

See also the Makefile.