Core.Text.Utilities

Useful tools for working with Ropes. Support for pretty printing, multi-line strings, and...

Pretty printing

class Render α where

Types which can be rendered "prettily", that is, formatted by a pretty printer and embossed with beautiful ANSI colours when printed to the terminal.

Use render to build text object for later use or Core.Program.Execute's writeR if you're writing directly to console now.

Associated Types

type Token α :: *

Which type are the annotations of your Doc going to be expressed in?

Methods

colourize :: Token α -> AnsiStyle

Convert semantic tokens to specific ANSI escape tokens

intoDocA :: α -> Doc (Token α)

Arrange your type as a Doc ann, annotated with your semantic tokens.

Instances

Render Text

Defined in Core.Text.Utilities

Associated Types

type Token Text :: Type

Methods

colourize :: Token Text -> AnsiStyle

intoDocA :: Text -> Doc (Token Text)

Render Value

Defined in Core.Encoding.Json

Associated Types

type Token Value :: Type

Methods

colourize :: Token Value -> AnsiStyle

intoDocA :: Value -> Doc (Token Value)

Render Rope

Defined in Core.Text.Utilities

Associated Types

type Token Rope :: Type

Methods

colourize :: Token Rope -> AnsiStyle

intoDocA :: Rope -> Doc (Token Rope)

Render Bytes

Defined in Core.Text.Bytes

Associated Types

type Token Bytes :: Type

Methods

colourize :: Token Bytes -> AnsiStyle

intoDocA :: Bytes -> Doc (Token Bytes)

Render JsonKey

Defined in Core.Encoding.Json

Associated Types

type Token JsonKey :: Type

Methods

colourize :: Token JsonKey -> AnsiStyle

intoDocA :: JsonKey -> Doc (Token JsonKey)

Render JsonValue

Defined in Core.Encoding.Json

Associated Types

type Token JsonValue :: Type

Methods

colourize :: Token JsonValue -> AnsiStyle

intoDocA :: JsonValue -> Doc (Token JsonValue)

Render [Char]

Defined in Core.Text.Utilities

Associated Types

type Token [Char] :: Type

Methods

colourize :: Token [Char] -> AnsiStyle

intoDocA :: [Char] -> Doc (Token [Char])

render :: Render α => Int -> α -> Rope

Given an object of a type with a Render instance, transform it into a Rope saturated with ANSI escape codes representing syntax highlighting or similar colouring, wrapping at the specified width.

The obvious expectation is that the next thing you're going to do is send the Rope to console with:

    write (render 80 thing)

However, the better thing to do is to instead use:

    writeR thing

which is able to pretty print the document text respecting the available width of the terminal.

Helpers

indefinite :: Rope -> Rope

Render "a" or "an" in front of a word depending on English's idea of whether it's a vowel or not.

wrap :: Int -> Rope -> Rope

Often the input text represents a paragraph, but does not have any internal newlines (representing word wrapping). This function takes a line of text and inserts newlines to simulate such folding. It also appends a trailing newline to finish the paragraph.

underline :: Char -> Rope -> Rope

Multi-line strings

quote :: QuasiQuoter

Multi-line string literals.

To use these you need to enable the QuasiQuotes language extension in your source file:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}

you are then able to easily write a string stretching over several lines.

How best to formatting multi-line string literal within your source code is an aesthetic judgement. Sometimes you don't care about the whitespace leading a passage (8 spaces in this example):

    let message = [quote|
        This is a test of the Emergency Broadcast System. Do not be
        alarmed. If this were a real emergency, someone would have tweeted
        about it by now.
    |]

because you are feeding it into a Doc for pretty printing and know the renderer will convert the whole text into a single line and then re-flow it. Other times you will want to have the string as is, literally:

    let poem = [quote|
If the sun
    rises
        in the
    west
you     drank
    too much
                last week.
    |]

Leading whitespace from the first line and trailing whitespace from the last line will be trimmed, so this:

    let value = [quote|
Hello
    |]

is translated to:

    let value = fromString "Hello\n"

without the leading newline or trailing four spaces. Note that as string literals they are presented to your code with fromString :: String -> α so any type with an IsString instance (as Rope has) can be constructed from a multi-line [quote| ... |] literal.