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 Control.Program.Logging'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 α -> AnsiColour

Convert semantic tokens to specific ANSI escape tokens

highlight :: α -> Doc (Token α)

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

Instances

Render Char

Defined in Core.Text.Utilities

Associated Types

type Token Char

Methods

colourize :: Token Char -> AnsiColour

highlight :: Char -> Doc (Token Char)

Render Text

Defined in Core.Text.Utilities

Associated Types

type Token Text

Methods

colourize :: Token Text -> AnsiColour

highlight :: Text -> Doc (Token Text)

Render Bytes

Defined in Core.Text.Utilities

Associated Types

type Token Bytes

Methods

colourize :: Token Bytes -> AnsiColour

highlight :: Bytes -> Doc (Token Bytes)

Render Rope

Defined in Core.Text.Utilities

Associated Types

type Token Rope

Methods

colourize :: Token Rope -> AnsiColour

highlight :: Rope -> Doc (Token Rope)

Render a => Render [a]

Defined in Core.Text.Utilities

Associated Types

type Token [a]

Methods

colourize :: Token [a] -> AnsiColour

highlight :: [a] -> Doc (Token [a])

data AnsiColour

An accumulation of ANSI escape codes used to add colour when pretty printing to console.

Instances

Semigroup AnsiColour

Defined in Core.Text.Utilities

Methods

(<>) :: AnsiColour -> AnsiColour -> AnsiColour

sconcat :: NonEmpty AnsiColour -> AnsiColour

stimes :: Integral b => b -> AnsiColour -> AnsiColour

Monoid AnsiColour

Defined in Core.Text.Utilities

Methods

mempty :: AnsiColour

mappend :: AnsiColour -> AnsiColour -> AnsiColour

mconcat :: [AnsiColour] -> AnsiColour

bold :: AnsiColour -> AnsiColour

Given an AnsiColour, lift it to bold intensity.

Note that many console fonts do not have a bold face variant, and terminal emulators that "support bold" do so by doubling the thickness of the lines in the glyphs. This may or may not be desirable from a readibility standpoint but really there's only so much you can do to keep users who make poor font choices from making poor font choices.

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.

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

Having gone to all the trouble to colourize your rendered types... sometimes you don't want that. This function is like render, but removes all the ANSI escape codes so it comes outformatted but as plain black & white text.

dullRed :: AnsiColour

Medium "Scarlet Red" (#cc0000 from the Tango color palette).

brightRed :: AnsiColour

Highlighted "Scarlet Red" (#ef2929 from the Tango color palette).

pureRed :: AnsiColour

Pure "Red" (full RGB red channel only).

dullGreen :: AnsiColour

Shadowed "Chameleon" (#4e9a06 from the Tango color palette).

brightGreen :: AnsiColour

Highlighted "Chameleon" (#8ae234 from the Tango color palette).

pureGreen :: AnsiColour

Pure "Green" (full RGB green channel only).

dullBlue :: AnsiColour

Medium "Sky Blue" (#3465a4 from the Tango color palette).

brightBlue :: AnsiColour

Highlighted "Sky Blue" (#729fcf from the Tango color palette).

pureBlue :: AnsiColour

Pure "Blue" (full RGB blue channel only).

dullCyan :: AnsiColour

Dull "Cyan" (from the gnome-terminal console theme).

brightCyan :: AnsiColour

Bright "Cyan" (from the gnome-terminal console theme).

pureCyan :: AnsiColour

Pure "Cyan" (full RGB blue + green channels).

dullMagenta :: AnsiColour

Medium "Plum" (#75507b from the Tango color palette).

brightMagenta :: AnsiColour

Highlighted "Plum" (#ad7fa8 from the Tango color palette).

pureMagenta :: AnsiColour

Pure "Magenta" (full RGB red + blue channels).

dullYellow :: AnsiColour

Shadowed "Butter" (#c4a000 from the Tango color palette).

brightYellow :: AnsiColour

Highlighted "Butter" (#fce94f from the Tango color palette).

pureYellow :: AnsiColour

Pure "Yellow" (full RGB red + green channels).

pureBlack :: AnsiColour

Pure "Black" (zero in all RGB channels).

dullGrey :: AnsiColour

Shadowed "Deep Aluminium" (#2e3436 from the Tango color palette).

brightGrey :: AnsiColour

Medium "Dark Aluminium" (from the Tango color palette).

pureGrey :: AnsiColour

Pure "Grey" (set at #999999, being just over half in all RGB channels).

pureWhite :: AnsiColour

Pure "White" (fully on in all RGB channels).

dullWhite :: AnsiColour

Medium "Light Aluminium" (#d3d7cf from the Tango color palette).

brightWhite :: AnsiColour

Highlighted "Light Aluminium" (#eeeeec from the Tango color palette).

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.

breakWords :: Rope -> [Rope]

Split a passage of text into a list of words. A line is broken wherever there is one or more whitespace characters, as defined by Data.Char's isSpace.

Examples:

λ> breakWords "This is a test"
["This","is","a","test"]
λ> breakWords ("St" <> "op and " <> "go left")
["Stop","and","go","left"]
λ> breakWords emptyRope
[]

breakLines :: Rope -> [Rope]

Split a paragraph of text into a list of its individual lines. The paragraph will be broken wherever there is a 'n' character.

Blank lines will be preserved. Note that as a special case you do not get a blank entry at the end of the a list of newline terminated strings.

λ> breakLines "Hello\n\nWorld\n"
["Hello","","World"]

breakPieces :: (Char -> Bool) -> Rope -> [Rope]

Break a Rope into pieces whereever the given predicate function returns True. If found, that character will not be included on either side. Empty runs, however, *will* be preserved.

isNewline :: Char -> Bool

Predicate testing whether a character is a newline. After isSpace et al in Data.Char.

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, keeping the line under the supplied maximum width.

A single word that is excessively long will be included as-is on its own line (that line will exceed the desired maxium width).

Any trailing newlines will be removed.

calculatePositionEnd :: Rope -> (Int, Int)

Calculate the line number and column number of a Rope (interpreting it as if is a block of text in a file). By the convention observed by all leading brands of text editor, lines and columns are 1 origin, so an empty Rope is position (1,1).

leftPadWith :: Char -> Int -> Rope -> Rope

Pad a pieve of text on the left with a specified character to the desired width. This function is named in homage to the famous result from Computer Science known as leftPad which has a glorious place in the history of the world-wide web.

rightPadWith :: Char -> Int -> Rope -> Rope

Right pad a text with the specified character.

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.

intoDocA :: α -> Doc (Token α)

Deprecated: methodintoDocA has been renamed highlight; implement that instead.

Nothing should be invoking intoDocA.