Safe Haskell | None |
---|---|
Language | Haskell2010 |
Useful tools for working with Rope
s. Support for pretty printing, multi-line
strings, and...
Synopsis
- class Render α where
- data AnsiColour
- bold :: AnsiColour -> AnsiColour
- render :: Render α => Int -> α -> Rope
- renderNoAnsi :: Render α => Int -> α -> Rope
- dullRed :: AnsiColour
- brightRed :: AnsiColour
- pureRed :: AnsiColour
- dullGreen :: AnsiColour
- brightGreen :: AnsiColour
- pureGreen :: AnsiColour
- dullBlue :: AnsiColour
- brightBlue :: AnsiColour
- pureBlue :: AnsiColour
- dullCyan :: AnsiColour
- brightCyan :: AnsiColour
- pureCyan :: AnsiColour
- dullMagenta :: AnsiColour
- brightMagenta :: AnsiColour
- pureMagenta :: AnsiColour
- dullYellow :: AnsiColour
- brightYellow :: AnsiColour
- pureYellow :: AnsiColour
- pureBlack :: AnsiColour
- dullGrey :: AnsiColour
- brightGrey :: AnsiColour
- pureGrey :: AnsiColour
- pureWhite :: AnsiColour
- dullWhite :: AnsiColour
- brightWhite :: AnsiColour
- indefinite :: Rope -> Rope
- breakWords :: Rope -> [Rope]
- breakLines :: Rope -> [Rope]
- breakPieces :: (Char -> Bool) -> Rope -> [Rope]
- isNewline :: Char -> Bool
- wrap :: Int -> Rope -> Rope
- calculatePositionEnd :: Rope -> (Int, Int)
- leftPadWith :: Char -> Int -> Rope -> Rope
- rightPadWith :: Char -> Int -> Rope -> Rope
- quote :: QuasiQuoter
- intoDocA :: α -> Doc (Token α)
Pretty printing
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
<https://hackage.haskell.org/package/core-program/docs/Core-Program-Logging.html
Control.Program.Logging>'s
<https://hackage.haskell.org/package/core-program/docs/Core-Program-Logging.html#v:writeR
writeR> if you're writing directly to console now.
colourize :: Token α -> AnsiColour Source #
Convert semantic tokens to specific ANSI escape tokens
highlight :: α -> Doc (Token α) Source #
Arrange your type as a Doc
ann
, annotated with your semantic tokens.
data AnsiColour Source #
An accumulation of ANSI escape codes used to add colour when pretty printing to console.
Instances
Semigroup AnsiColour Source # | |
Defined in Core.Text.Utilities (<>) :: AnsiColour -> AnsiColour -> AnsiColour # sconcat :: NonEmpty AnsiColour -> AnsiColour # stimes :: Integral b => b -> AnsiColour -> AnsiColour # | |
Monoid AnsiColour Source # | |
Defined in Core.Text.Utilities mempty :: AnsiColour # mappend :: AnsiColour -> AnsiColour -> AnsiColour # mconcat :: [AnsiColour] -> AnsiColour # |
bold :: AnsiColour -> AnsiColour Source #
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 Source #
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 Source #
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 Source #
Medium "Scarlet Red" (#cc0000
from the Tango color palette).
brightRed :: AnsiColour Source #
Highlighted "Scarlet Red" (#ef2929
from the Tango color palette).
pureRed :: AnsiColour Source #
Pure "Red" (full RGB red channel only).
dullGreen :: AnsiColour Source #
Shadowed "Chameleon" (#4e9a06
from the Tango color palette).
brightGreen :: AnsiColour Source #
Highlighted "Chameleon" (#8ae234
from the Tango color palette).
pureGreen :: AnsiColour Source #
Pure "Green" (full RGB green channel only).
dullBlue :: AnsiColour Source #
Medium "Sky Blue" (#3465a4
from the Tango color palette).
brightBlue :: AnsiColour Source #
Highlighted "Sky Blue" (#729fcf
from the Tango color palette).
pureBlue :: AnsiColour Source #
Pure "Blue" (full RGB blue channel only).
dullCyan :: AnsiColour Source #
Dull "Cyan" (from the gnome-terminal console theme).
brightCyan :: AnsiColour Source #
Bright "Cyan" (from the gnome-terminal console theme).
pureCyan :: AnsiColour Source #
Pure "Cyan" (full RGB blue + green channels).
dullMagenta :: AnsiColour Source #
Medium "Plum" (#75507b
from the Tango color palette).
brightMagenta :: AnsiColour Source #
Highlighted "Plum" (#ad7fa8
from the Tango color palette).
pureMagenta :: AnsiColour Source #
Pure "Magenta" (full RGB red + blue channels).
dullYellow :: AnsiColour Source #
Shadowed "Butter" (#c4a000
from the Tango color palette).
brightYellow :: AnsiColour Source #
Highlighted "Butter" (#fce94f
from the Tango color palette).
pureYellow :: AnsiColour Source #
Pure "Yellow" (full RGB red + green channels).
pureBlack :: AnsiColour Source #
Pure "Black" (zero in all RGB channels).
dullGrey :: AnsiColour Source #
Shadowed "Deep Aluminium" (#2e3436
from the Tango color palette).
brightGrey :: AnsiColour Source #
Medium "Dark Aluminium" (from the Tango color palette).
pureGrey :: AnsiColour Source #
Pure "Grey" (set at #999999
, being just over half in all RGB channels).
pureWhite :: AnsiColour Source #
Pure "White" (fully on in all RGB channels).
dullWhite :: AnsiColour Source #
Medium "Light Aluminium" (#d3d7cf
from the Tango color palette).
brightWhite :: AnsiColour Source #
Highlighted "Light Aluminium" (#eeeeec
from the Tango color palette).
Helpers
indefinite :: Rope -> Rope Source #
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] Source #
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] Source #
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] Source #
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.
wrap :: Int -> Rope -> Rope Source #
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) Source #
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 Source #
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.
Multi-line strings
quote :: QuasiQuoter Source #
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 [
literal.quote
| ... |]