escaped: Produce Text with terminal escape sequences

[ library, mit, program, text ] [ Propose Tags ] [ Report a vulnerability ]

See README.md


[Skip to Readme]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 1.0.0.0, 1.1.0.0
Change log CHANGELOG.md
Dependencies base (>=4 && <5), escaped, QuickCheck (>=2.14.2), quickcheck-instances (>=0.3.25.2), text (>=1.2.4.1), unix (>=2.7.2.2) [details]
License MIT
Copyright 2018 Patrick Brisbin
Author Patrick Brisbin
Maintainer pbrisbin@gmail.com
Category Text
Home page https://github.com/pbrisbin/escaped#readme
Bug tracker https://github.com/pbrisbin/escaped/issues
Source repo head: git clone https://github.com/pbrisbin/escaped
Uploaded by PatrickBrisbin at 2024-08-27T13:32:37Z
Distributions NixOS:1.0.0.0
Executables escaped-example
Downloads 827 total (13 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-08-27 [all 1 reports]

Readme for escaped-1.1.0.0

[back to package description]

escaped

Produce Text with terminal escape sequences.

Usage

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

Example

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

Example

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
"one\ESC[31mred\ESC[0mthree"

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
  where
    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

CHANGELOG | LICENSE