escape-artist

A Haskell library for text decoration with ANSI escape sequences made easy. Decorate your terminal text easily and expressively.

Getting Started

Building from Source

Prerequisites

To build this project from source, you will need to install stack. See https://docs.haskellstack.org/en/stable/README/#how-to-install for detailed installation instructions for your operating system.

Building

git clone https://github.com/EarthCitizen/escape-artist
cd escape-artist
stack setup
stack build

Using

The data type used to perform text decoration is Escapable. This defines the constructors for the decoration. Each constructor takes a single argument. It can be any type that has implemented the ToEscapable class. This means that all of the following are perfectly valid:

{-# LANGUAGE ExtendedDefaultRules #-}

FgRed 6
FgRed "6"
FgRed '6'
FgRed (6 :: Float)
FgRed (6 :: Double)

And can all dwell in the same list:

{-# LANGUAGE ExtendedDefaultRules #-}

import Data.List (intersperse)
import Text.EscapeArtist

let redList = [FgRed 6, FgRed "6", FgRed '6', FgRed (6 :: Float), FgRed (6 :: Double)]

putEscLn $ mconcat $ intersperse (Inherit " ") redList

The following data types already come with an implementation of ToEscapable:

• Char
• ByteString of Data.ByteString
• ByteString of Data.ByteString.Lazy
• Text of Data.Text
• Text of Data.Text.Lazy
• Double
• Float
• Int
• Integer
• String
• Word
• Word8
• Word16
• Word32
• Word64

Implementing ToEscapable for other data types is fairly simple:

import Data.Monoid ((<>))
import Text.EscapeArtist

data ABC = A | B deriving (Show, Eq)

instance ToEscapable ABC where
   toEscapable (A) = FgRed $ show A
   toEscapable (B) = FgGreen $ show B

instance (ToEscapable a) => ToEscapable (Maybe a) where
    toEscapable (Just a) = FgGreen "Just" <> Inherit " " <> FgYellow a
    toEscapable a = FgRed $ show a

putEscLn A
putEscLn B
putEscLn $ Just 15
putEscLn (Nothing :: Maybe Int)

When constructors are combined with the application operator ($), the effects accumulate and wrap around the applied value:

import Text.EscapeArtist

let combined = FgRed $ Underline $ Blink "Hello World!"

would be equivalent to the following in XML:

<red>
    <underline>
        <blink>
            Hello World!
        </blink>
    </underline>
</red>

NOTE: This library does not produce nor interact with XML. This example is just for the purpose of explanation.

Escapable is an instance of Monoid, so a series of Escapables can be appended together into a single value:

{-# LANGUAGE ExtendedDefaultRules #-}

import Data.Monoid ((<>))
import Text.EscapeArtist

let series = FgYellow 5 <> FgWhite 6

putEscLn series

When a constructor is applied to a series of appended Escapables using the $, the constructor will be applied to each member of the series.

{-# LANGUAGE ExtendedDefaultRules #-}

import Data.Monoid ((<>))
import Text.EscapeArtist

let result = Underline $ FgYellow 5 <> FgWhite 6

putEscLn result

XML equivalent:

<underline>
    <yellow>5</yellow>
</underline>
<underline>
    <white>6</white>
</underline>

NOTE: The Underline is re-applied to each member of the series, and not once for all of them.

Constructors

Foreground Color

FgBlack FgRed FgGreen FgYellow FgBlue FgMagenta FgCyan FgWhite

Background Color

BgBlack BgRed BgGreen BgYellow BgBlue BgMagenta BgCyan BgWhite

Other Types

Functions

Operators

Examples

Inherit

import Data.Monoid ((<>))
import Text.EscapeArtist

spacesInherit = FgRed '@' <> Inherit ' ' <> FgYellow '@' <> Inherit ' ' <> FgGreen '@'

putEscLn spacesInherit

putEscLn $ Underline spacesInherit

putEscLn $ Inverse spacesInherit

putEscLn $ BgBlue spacesInherit

UnderlineOff

import Data.Monoid ((<>))
import Text.EscapeArtist

underlines = Underline $ FgCyan "I am underlined" <> UnderlineOff " but I am not " <> FgMagenta "and I am over here"

putEscLn underlines

The same type of functionality applies as well to BlinkOff, BrightOff and InverseOff.

Operator ^$

This operator allows you to avoid parentheses in cases where you need to use $ and <> in he same expression.

import Data.Monoid ((<>))
import Text.EscapeArtist

op1 = Underline $ Bright ^$ FgGreen "GREEN" <> Default " " <> FgYellow "YELLOW"

putEscLn op1

Without ^$, this would have to be written as:

Underline $ (Bright $ FgGreen "GREEN") <> Default " " <> FgYellow "YELLOW"

Operator /<>/

This operator allows Inherit to be omitted.

BgRed $ Inherit 4 <> BgCyan " " <> Inherit 5 <> BgGreen " " <> Inherit 9

can simply be written as:

BgRed $ 4 /<>/ BgCyan " " /<>/ 5 /<>/ BgGreen " " /<>/ 9

Advanced Examples

Fun with Colors

import Data.Monoid (mempty, (<>))
import Text.EscapeArtist

rainbowString :: String -> Escapable
rainbowString s = fn s (cycle [FgRed, FgWhite, FgGreen, FgBlue, FgYellow, FgCyan])
    where fn [] _ = mempty
          fn _ [] = mempty
          fn (s:ss) ca@(c:cs)
              | s `elem` " \t\n\r" = Inherit s <> fn ss ca
              | otherwise = c s <> fn ss cs

putEscLn $ rainbowString "Hello World!"

Colorize Sections of a String

import Text.EscapeArtist
import Text.Regex

replaceNumbers :: String -> String
replaceNumbers searchIn = subRegex (mkRegex "([0-9]+)") searchIn (escToString $ FgRed "\\1")

putStrLn $ replaceNumbers "Line 7 of 23"

Implement ToEscapable for Custom and Existing Data Types

{-# LANGUAGE FlexibleInstances #-}

import Data.Monoid ((<>))
import Text.EscapeArtist

type FileName = String
type LineNumber = Integer
type ColumnNumber = Integer
data ErrorType = SyntaxError FileName LineNumber ColumnNumber deriving (Show)

instance ToEscapable ErrorType where
    toEscapable (SyntaxError fn ln cn) = Default "Syntax error in file "
                                       <> FgYellow ^$ Underline fn
                                       <> Default " at "
                                       <> FgRed (show ln ++ ":" ++ show cn)

instance ToEscapable (Either ErrorType String) where
    toEscapable (Left e) = toEscapable e
    toEscapable (Right m) = FgGreen m

mkSyntaxError :: FileName -> LineNumber -> ColumnNumber -> Either ErrorType String
mkSyntaxError fn ln cn = Left $ SyntaxError fn ln cn

mkStatusOK :: Either ErrorType String
mkStatusOK = Right "Status OK"

putEscLn $ mkSyntaxError "some/File.hs" 1 23
putEscLn mkStatusOK