prettyprinter-ansi-terminal-1.1.3: ANSI terminal backend for the »prettyprinter« package.

Safe Haskell | Safe-Inferred
Language | Haskell2010

Prettyprinter.Render.Terminal

Contents

- Styling
  - Font color
  - Background color
  - Font style
  - Internal markers
- Conversion to ANSI-infused `Text`
- Render directly to `stdout`
  - Convenience functions

Description

Render `SimpleDocStream` in a terminal.

Synopsis

- data AnsiStyle
- data Color
  - = Black
  - | Red
  - | Green
  - | Yellow
  - | Blue
  - | Magenta
  - | Cyan
  - | White
- color :: Color -> AnsiStyle
- colorDull :: Color -> AnsiStyle
- bgColor :: Color -> AnsiStyle
- bgColorDull :: Color -> AnsiStyle
- bold :: AnsiStyle
- italicized :: AnsiStyle
- underlined :: AnsiStyle
- data Intensity
  - = Vivid
  - | Dull
- data Bold = Bold
- data Underlined = Underlined
- data Italicized = Italicized
- renderLazy :: SimpleDocStream AnsiStyle -> Text
- renderStrict :: SimpleDocStream AnsiStyle -> Text
- renderIO :: Handle -> SimpleDocStream AnsiStyle -> IO ()
- putDoc :: Doc AnsiStyle -> IO ()
- hPutDoc :: Handle -> Doc AnsiStyle -> IO ()

# Styling

data AnsiStyle Source #

Render the annotated document in a certain style. Styles not set in the annotation will use the style of the surrounding document, or the terminal’s default if none has been set yet.

    style = color Green <> bold
    styledDoc = annotate style "hello world"

#### Instances

Instances details

Monoid AnsiStyle Source # | `mempty` does nothing, which is equivalent to inheriting the style of the surrounding doc, or the terminal’s default if no style has been set yet.
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods mempty :: AnsiStyle Source # mappend :: AnsiStyle -> AnsiStyle -> AnsiStyle Source # mconcat :: [AnsiStyle] -> AnsiStyle Source #

Semigroup AnsiStyle Source #

Keep the first decision for each of foreground color, background color, boldness, italication, and underlining. If a certain style is not set, the terminal’s default will be used.

Example:

    color Red <> color Green

is red because the first color wins, and not bold because (or if) that’s the terminal’s default.

Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (<>) :: AnsiStyle -> AnsiStyle -> AnsiStyle Source # sconcat :: NonEmpty AnsiStyle -> AnsiStyle Source # stimes :: Integral b => b -> AnsiStyle -> AnsiStyle Source #
Show AnsiStyle Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods showsPrec :: Int -> AnsiStyle -> ShowS Source # show :: AnsiStyle -> String Source # showList :: [AnsiStyle] -> ShowS Source #
Eq AnsiStyle Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (==) :: AnsiStyle -> AnsiStyle -> Bool Source # (/=) :: AnsiStyle -> AnsiStyle -> Bool Source #
Ord AnsiStyle Source # |

Instance details

Defined in Prettyprinter.Render.Terminal.Internal

Methods

compare :: AnsiStyle -> AnsiStyle -> Ordering Source #

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

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

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

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

max :: AnsiStyle -> AnsiStyle -> AnsiStyle Source #

min :: AnsiStyle -> AnsiStyle -> AnsiStyle Source #

data Color Source #

The 8 ANSI terminal colors.

Constructors

Black |
Red |
Green |
Yellow |
Blue |
Magenta |
Cyan |
White |

#### Instances

Instances details

Show Color Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods showsPrec :: Int -> Color -> ShowS Source # show :: Color -> String Source # showList :: [Color] -> ShowS Source #
Eq Color Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (==) :: Color -> Color -> Bool Source # (/=) :: Color -> Color -> Bool Source #
Ord Color Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods compare :: Color -> Color -> Ordering Source # (<) :: Color -> Color -> Bool Source # (<=) :: Color -> Color -> Bool Source # (>) :: Color -> Color -> Bool Source # (>=) :: Color -> Color -> Bool Source # max :: Color -> Color -> Color Source # min :: Color -> Color -> Color Source #

## Font color

color :: Color -> AnsiStyle Source #

Style the foreground with a vivid color.

colorDull :: Color -> AnsiStyle Source #

Style the foreground with a dull color.

## Background color

bgColor :: Color -> AnsiStyle Source #

Style the background with a vivid color.

bgColorDull :: Color -> AnsiStyle Source #

Style the background with a dull color.

## Font style

bold :: AnsiStyle Source #

Render in bold.

italicized :: AnsiStyle Source #

Render in italics.

underlined :: AnsiStyle Source #

Render underlined.

## Internal markers

These should only be used for writing adaptors to other libraries; for the average use case, use `bold`, `bgColorDull`, etc.

data Intensity Source #

Dull or vivid coloring, as supported by ANSI terminals.

Constructors

Vivid |
Dull |

#### Instances

Instances details

Show Intensity Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods showsPrec :: Int -> Intensity -> ShowS Source # show :: Intensity -> String Source # showList :: [Intensity] -> ShowS Source #
Eq Intensity Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (==) :: Intensity -> Intensity -> Bool Source # (/=) :: Intensity -> Intensity -> Bool Source #
Ord Intensity Source # |

Instance details

Defined in Prettyprinter.Render.Terminal.Internal

Methods

compare :: Intensity -> Intensity -> Ordering Source #

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

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

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

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

max :: Intensity -> Intensity -> Intensity Source #

min :: Intensity -> Intensity -> Intensity Source #

data Bold Source #

Constructors

Bold |

#### Instances

Instances details

Show Bold Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods showsPrec :: Int -> Bold -> ShowS Source # show :: Bold -> String Source # showList :: [Bold] -> ShowS Source #
Eq Bold Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (==) :: Bold -> Bold -> Bool Source # (/=) :: Bold -> Bold -> Bool Source #
Ord Bold Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods compare :: Bold -> Bold -> Ordering Source # (<) :: Bold -> Bold -> Bool Source # (<=) :: Bold -> Bold -> Bool Source # (>) :: Bold -> Bold -> Bool Source # (>=) :: Bold -> Bold -> Bool Source # max :: Bold -> Bold -> Bold Source # min :: Bold -> Bold -> Bold Source #

data Underlined Source #

Constructors

Underlined |

#### Instances

Instances details

Show Underlined Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods showsPrec :: Int -> Underlined -> ShowS Source # show :: Underlined -> String Source # showList :: [Underlined] -> ShowS Source #
Eq Underlined Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (==) :: Underlined -> Underlined -> Bool Source # (/=) :: Underlined -> Underlined -> Bool Source #
Ord Underlined Source # |

Instance details

Defined in Prettyprinter.Render.Terminal.Internal

Methods

compare :: Underlined -> Underlined -> Ordering Source #

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

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

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

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

max :: Underlined -> Underlined -> Underlined Source #

min :: Underlined -> Underlined -> Underlined Source #

data Italicized Source #

Constructors

Italicized |

#### Instances

Instances details

Show Italicized Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods showsPrec :: Int -> Italicized -> ShowS Source # show :: Italicized -> String Source # showList :: [Italicized] -> ShowS Source #
Eq Italicized Source # |
Instance details Defined in Prettyprinter.Render.Terminal.Internal Methods (==) :: Italicized -> Italicized -> Bool Source # (/=) :: Italicized -> Italicized -> Bool Source #
Ord Italicized Source # |

Instance details

Defined in Prettyprinter.Render.Terminal.Internal

Methods

compare :: Italicized -> Italicized -> Ordering Source #

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

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

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

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

max :: Italicized -> Italicized -> Italicized Source #

min :: Italicized -> Italicized -> Italicized Source #

# Conversion to ANSI-infused `Text`

renderLazy :: SimpleDocStream AnsiStyle -> Text Source #

`(`renderLazy` doc)` takes the output `doc` from a rendering function and transforms it to lazy text, including ANSI styling directives for things like colorization.

ANSI color information will be discarded by this function unless you are running on a Unix-like operating system. This is due to a technical limitation in Windows ANSI support.

With a bit of trickery to make the ANSI codes printable, here is an example that would render colored in an ANSI terminal:

    >>> let render = TL.putStrLn . TL.replace "\ESC" "\\e" . renderLazy . layoutPretty defaultLayoutOptions
    >>> let doc = annotate (color Red) ("red" <+> align (vsep [annotate (color Blue <> underlined) ("blue+u" <+> annotate bold "bold" <+> "blue+u"), "red"]))
    >>> render (unAnnotate doc)
    red blue+u bold blue+u
        red
    >>> render doc
    \e[0;91mred \e[0;94;4mblue+u \e[0;94;1;4mbold\e[0;94;4m blue+u\e[0;91m
        red\e[0m

Run the above via `echo -e `...`` in your terminal to see the coloring.

renderStrict :: SimpleDocStream AnsiStyle -> Text Source #

`(`renderStrict` sdoc)` takes the output `sdoc` from a rendering and transforms it to strict text.

# Render directly to `stdout`

renderIO :: Handle -> SimpleDocStream AnsiStyle -> IO () Source #

`(`renderIO` h sdoc)` writes `sdoc` to the handle `h`.

    >>> let render = renderIO System.IO.stdout . layoutPretty defaultLayoutOptions
    >>> let doc = annotate (color Red) ("red" <+> align (vsep [annotate (color Blue <> underlined) ("blue+u" <+> annotate bold "bold" <+> "blue+u"), "red"]))

We render the `unAnnotate`d version here, since the ANSI codes don’t display well in Haddock,

    >>> render (unAnnotate doc)
    red blue+u bold blue+u
        red

This function behaves just like

    renderIO h sdoc = hPutStr h (renderLazy sdoc)

but will not generate any intermediate text, rendering directly to the handle.

## Convenience functions

putDoc :: Doc AnsiStyle -> IO () Source #

`(`putDoc` doc)` prettyprints document `doc` to standard output using `defaultLayoutOptions`.

    >>> putDoc ("hello" <+> "world")
    hello world

    putDoc = hPutDoc stdout

hPutDoc :: Handle -> Doc AnsiStyle -> IO () Source #

Like `putDoc`, but instead of using `stdout`, print to a user-provided handle, e.g. a file or a socket using `defaultLayoutOptions`.

    main = withFile "someFile.txt" (\h -> hPutDoc h (vcat ["vertical", "text"]))

    hPutDoc h doc = renderIO h (layoutPretty defaultLayoutOptions doc)