doclayout-0.3: A prettyprinting library for laying out text documents.

Copyright | Copyright (C) 2010-2019 John MacFarlane
License | BSD 3
Maintainer | John MacFarlane <jgm@berkeley.edu>
Stability | alpha
Portability | portable
Safe Haskell | Safe
Language | Haskell2010

Text.DocLayout

Contents

- Rendering
- Doc constructors
- Functions for concatenating documents
- Functions for querying documents
- Types

Description

A prettyprinting library for the production of text documents, including wrapped text, indentation and other prefixes, and blocks for tables.

Synopsis

- render :: HasChars a => Maybe Int -> Doc a -> a
- cr :: Doc a
- blankline :: Doc a
- blanklines :: Int -> Doc a
- space :: Doc a
- literal :: HasChars a => a -> Doc a
- text :: HasChars a => String -> Doc a
- char :: HasChars a => Char -> Doc a
- prefixed :: IsString a => String -> Doc a -> Doc a
- flush :: Doc a -> Doc a
- nest :: IsString a => Int -> Doc a -> Doc a
- hang :: IsString a => Int -> Doc a -> Doc a -> Doc a
- beforeNonBlank :: Doc a -> Doc a
- nowrap :: IsString a => Doc a -> Doc a
- afterBreak :: Text -> Doc a
- lblock :: HasChars a => Int -> Doc a -> Doc a
- cblock :: HasChars a => Int -> Doc a -> Doc a
- rblock :: HasChars a => Int -> Doc a -> Doc a
- vfill :: HasChars a => a -> Doc a
- nestle :: Doc a -> Doc a
- chomp :: Doc a -> Doc a
- inside :: Doc a -> Doc a -> Doc a -> Doc a
- braces :: HasChars a => Doc a -> Doc a
- brackets :: HasChars a => Doc a -> Doc a
- parens :: HasChars a => Doc a -> Doc a
- quotes :: HasChars a => Doc a -> Doc a
- doubleQuotes :: HasChars a => Doc a -> Doc a
- empty :: Doc a
- (<+>) :: Doc a -> Doc a -> Doc a
- ($$) :: Doc a -> Doc a -> Doc a
- ($+$) :: Doc a -> Doc a -> Doc a
- hcat :: [Doc a] -> Doc a
- hsep :: [Doc a] -> Doc a
- vcat :: [Doc a] -> Doc a
- vsep :: [Doc a] -> Doc a
- isEmpty :: Doc a -> Bool
- offset :: (IsString a, HasChars a) => Doc a -> Int
- minOffset :: HasChars a => Doc a -> Int
- updateColumn :: HasChars a => Doc a -> Int -> Int
- height :: HasChars a => Doc a -> Int
- charWidth :: Char -> Int
- realLength :: HasChars a => a -> Int
- data Doc a
  - = Text Int a
  - | Block Int [a]
  - | VFill Int a
  - | Prefixed Text (Doc a)
  - | BeforeNonBlank (Doc a)
  - | Flush (Doc a)
  - | BreakingSpace
  - | AfterBreak Text
  - | CarriageReturn
  - | NewLine
  - | BlankLines Int
  - | Concat (Doc a) (Doc a)
  - | Empty
- class (IsString a, Semigroup a, Monoid a, Show a) => HasChars a where
  - foldrChar :: (Char -> b -> b) -> b -> a -> b
  - foldlChar :: (b -> Char -> b) -> b -> a -> b
  - replicateChar :: Int -> Char -> a
  - isNull :: a -> Bool
  - splitLines :: a -> [a]

# Rendering

render :: HasChars a => Maybe Int -> Doc a -> a Source #

Render a `Doc`. `render (Just n)` will use a line length of `n` to reflow text on breakable spaces. `render Nothing` will not reflow text.

# Doc constructors

cr :: Doc a Source #

A carriage return. Does nothing if we're at the beginning of a line; otherwise inserts a newline.

blankline :: Doc a Source #

Inserts a blank line unless one exists already. (`blankline <> blankline` has the same effect as `blankline`.

blanklines :: Int -> Doc a Source #

Inserts blank lines unless they exist already. (`blanklines m <> blanklines n` has the same effect as `blanklines (max m n)`.

space :: Doc a Source #

A breaking (reflowable) space.

literal :: HasChars a => a -> Doc a Source #

Create a `Doc` from a stringlike value.

text :: HasChars a => String -> Doc a Source #

A literal string. (Like `literal`, but restricted to String.)

char :: HasChars a => Char -> Doc a Source #

A character.

prefixed :: IsString a => String -> Doc a -> Doc a Source #

Uses the specified string as a prefix for every line of the inside document (except the first, if not at the beginning of the line).

flush :: Doc a -> Doc a Source #

Makes a `Doc` flush against the left margin.

nest :: IsString a => Int -> Doc a -> Doc a Source #

Indents a `Doc` by the specified number of spaces.

hang :: IsString a => Int -> Doc a -> Doc a -> Doc a Source #

A hanging indent. `hang ind start doc` prints `start`, then `doc`, leaving an indent of `ind` spaces on every line but the first.

beforeNonBlank :: Doc a -> Doc a Source #

`beforeNonBlank d` conditionally includes `d` unless it is followed by blank space.

nowrap :: IsString a => Doc a -> Doc a Source #

Makes a `Doc` non-reflowable.

afterBreak :: Text -> Doc a Source #

Content to print only if it comes at the beginning of a line, to be used e.g. for escaping line-initial `.` in roff man.

lblock :: HasChars a => Int -> Doc a -> Doc a Source #

`lblock n d` is a block of width `n` characters, with text derived from `d` and aligned to the left.

cblock :: HasChars a => Int -> Doc a -> Doc a Source #

Like `lblock` but aligned centered.

rblock :: HasChars a => Int -> Doc a -> Doc a Source #

Like `lblock` but aligned to the right.

vfill :: HasChars a => a -> Doc a Source #

An expandable border that, when placed next to a box, expands to the height of the box. Strings cycle through the list provided.

nestle :: Doc a -> Doc a Source #

Removes leading blank lines from a `Doc`.

chomp :: Doc a -> Doc a Source #

Chomps trailing blank space off of a `Doc`.

inside :: Doc a -> Doc a -> Doc a -> Doc a Source #

Encloses a `Doc` inside a start and end `Doc`.

braces :: HasChars a => Doc a -> Doc a Source #

Puts a `Doc` in curly braces.

brackets :: HasChars a => Doc a -> Doc a Source #

Puts a `Doc` in square brackets.

parens :: HasChars a => Doc a -> Doc a Source #

Puts a `Doc` in parentheses.

quotes :: HasChars a => Doc a -> Doc a Source #

Wraps a `Doc` in single quotes.

doubleQuotes :: HasChars a => Doc a -> Doc a Source #

Wraps a `Doc` in double quotes.

empty :: Doc a Source #

The empty document.

# Functions for concatenating documents

(<+>) :: Doc a -> Doc a -> Doc a infixr 6 Source #

Concatenate a list of `Doc`s, putting breakable spaces between them.

($$) :: Doc a -> Doc a -> Doc a infixr 5 Source #

`a $$ b` puts `a` above `b`.

($+$) :: Doc a -> Doc a -> Doc a infixr 5 Source #

`a $+$ b` puts `a` above `b`, with a blank line between.

hcat :: [Doc a] -> Doc a Source #

Concatenate documents horizontally.

hsep :: [Doc a] -> Doc a Source #

Same as `hcat`, but putting breakable spaces between the `Doc`s.

vcat :: [Doc a] -> Doc a Source #

List version of `$$`.

vsep :: [Doc a] -> Doc a Source #

List version of `$+$`.

# Functions for querying documents

isEmpty :: Doc a -> Bool Source #

True if the document is empty.

offset :: (IsString a, HasChars a) => Doc a -> Int Source #

Returns the width of a `Doc`.

minOffset :: HasChars a => Doc a -> Int Source #

Returns the minimal width of a `Doc` when reflowed at breakable spaces.

updateColumn :: HasChars a => Doc a -> Int -> Int Source #

Returns the column that would be occupied by the last laid out character (assuming no wrapping).

height :: HasChars a => Doc a -> Int Source #

Returns the height of a block or other `Doc`.

charWidth :: Char -> Int Source #

Returns width of a character in a monospace font: 0 for a combining character, 1 for a regular character, 2 for an East Asian wide character.

realLength :: HasChars a => a -> Int Source #

Get real length of string, taking into account combining and double-wide characters.

# Types

data Doc a Source #

Document, including structure relevant for layout.

Constructors

Text Int a | Text with specified width.
Block Int [a] | A block with a width and lines.
VFill Int a | A vertically expandable block; when concatenated with a block, expands to height of block, with each line containing the specified text.
Prefixed Text (Doc a) | Doc with each line prefixed with text. Note that trailing blanks are omitted from the prefix when the line after it is empty.
BeforeNonBlank (Doc a) | Doc that renders only before nonblank.
Flush (Doc a) | Doc laid out flush to left margin.
BreakingSpace | A space or line break, in context.
AfterBreak Text | Text printed only at start of line.
CarriageReturn | Newline unless we're at start of line.
NewLine | newline.
BlankLines Int | Ensure a number of blank lines.
Concat (Doc a) (Doc a) | Two documents concatenated.
Empty |

#### Instances

Instances details

Functor Doc Source # |
Instance details Defined in Text.DocLayout Methods fmap :: (a -> b) -> Doc a -> Doc b (<$) :: a -> Doc b -> Doc a
Foldable Doc Source # |

Instance details

Defined in Text.DocLayout

Methods

fold :: Monoid m => Doc m -> m

foldMap :: Monoid m => (a -> m) -> Doc a -> m

foldMap' :: Monoid m => (a -> m) -> Doc a -> m

foldr :: (a -> b -> b) -> b -> Doc a -> b

foldr' :: (a -> b -> b) -> b -> Doc a -> b

foldl :: (b -> a -> b) -> b -> Doc a -> b

foldl' :: (b -> a -> b) -> b -> Doc a -> b

foldr1 :: (a -> a -> a) -> Doc a -> a

foldl1 :: (a -> a -> a) -> Doc a -> a

toList :: Doc a -> [a]

null :: Doc a -> Bool

length :: Doc a -> Int

elem :: Eq a => a -> Doc a -> Bool

maximum :: Ord a => Doc a -> a

minimum :: Ord a => Doc a -> a

sum :: Num a => Doc a -> a

product :: Num a => Doc a -> a

Traversable Doc Source # |
Instance details Defined in Text.DocLayout Methods traverse :: Applicative f => (a -> f b) -> Doc a -> f (Doc b) sequenceA :: Applicative f => Doc (f a) -> f (Doc a) mapM :: Monad m => (a -> m b) -> Doc a -> m (Doc b) sequence :: Monad m => Doc (m a) -> m (Doc a)
Eq a => Eq (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods (==) :: Doc a -> Doc a -> Bool (/=) :: Doc a -> Doc a -> Bool
Data a => Data (Doc a) Source # |

Instance details

Defined in Text.DocLayout

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Doc a -> c (Doc a)

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Doc a)

toConstr :: Doc a -> Constr

dataTypeOf :: Doc a -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Doc a))

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Doc a))

gmapT :: (forall b. Data b => b -> b) -> Doc a -> Doc a

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Doc a -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Doc a -> r

gmapQ :: (forall d. Data d => d -> u) -> Doc a -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Doc a -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Doc a -> m (Doc a)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Doc a -> m (Doc a)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Doc a -> m (Doc a)

Ord a => Ord (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods compare :: Doc a -> Doc a -> Ordering (<) :: Doc a -> Doc a -> Bool (<=) :: Doc a -> Doc a -> Bool (>) :: Doc a -> Doc a -> Bool (>=) :: Doc a -> Doc a -> Bool max :: Doc a -> Doc a -> Doc a min :: Doc a -> Doc a -> Doc a
Read a => Read (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods readsPrec :: Int -> ReadS (Doc a) readList :: ReadS [Doc a] readPrec :: ReadPrec (Doc a) readListPrec :: ReadPrec [Doc a]
Show a => Show (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods showsPrec :: Int -> Doc a -> ShowS show :: Doc a -> String showList :: [Doc a] -> ShowS
HasChars a => IsString (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods fromString :: String -> Doc a
Generic (Doc a) Source # |
Instance details Defined in Text.DocLayout Associated Types type Rep (Doc a) :: Type -> Type Methods from :: Doc a -> Rep (Doc a) x to :: Rep (Doc a) x -> Doc a
Semigroup (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods (<>) :: Doc a -> Doc a -> Doc a sconcat :: NonEmpty (Doc a) -> Doc a stimes :: Integral b => b -> Doc a -> Doc a
Monoid (Doc a) Source # |
Instance details Defined in Text.DocLayout Methods mempty :: Doc a mappend :: Doc a -> Doc a -> Doc a mconcat :: [Doc a] -> Doc a
type Rep (Doc a) Source # |

Instance details

Defined in Text.DocLayout

type Rep (Doc a) = D1 ('MetaData "Doc" "Text.DocLayout" "doclayout-0.3-HGTFPBF3YeKC1CkI7V3g7J" 'False) (((C1 ('MetaCons "Text" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: (C1 ('MetaCons "Block" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [a])) :+: C1 ('MetaCons "VFill" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))) :+: (C1 ('MetaCons "Prefixed" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a))) :+: (C1 ('MetaCons "BeforeNonBlank" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a))) :+: C1 ('MetaCons "Flush" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)))))) :+: ((C1 ('MetaCons "BreakingSpace" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "AfterBreak" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)) :+: C1 ('MetaCons "CarriageReturn" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "NewLine" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "BlankLines" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int))) :+: (C1 ('MetaCons "Concat" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a)) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Doc a))) :+: C1 ('MetaCons "Empty" 'PrefixI 'False) (U1 :: Type -> Type)))))

class (IsString a, Semigroup a, Monoid a, Show a) => HasChars a where Source #

Class abstracting over various string types that can fold over characters. Minimal definition is `foldrChar` and `foldlChar`, but defining the other methods can give better performance.

Minimal complete definition

foldrChar, foldlChar

Methods

foldrChar :: (Char -> b -> b) -> b -> a -> b Source #

foldlChar :: (b -> Char -> b) -> b -> a -> b Source #

replicateChar :: Int -> Char -> a Source #

isNull :: a -> Bool Source #

splitLines :: a -> [a] Source #

#### Instances

Instances details

HasChars String Source # |
Instance details Defined in Text.DocLayout Methods foldrChar :: (Char -> b -> b) -> b -> String -> b Source # foldlChar :: (b -> Char -> b) -> b -> String -> b Source # replicateChar :: Int -> Char -> String Source # isNull :: String -> Bool Source # splitLines :: String -> [String] Source #
HasChars Text Source # |
Instance details Defined in Text.DocLayout Methods foldrChar :: (Char -> b -> b) -> b -> Text -> b Source # foldlChar :: (b -> Char -> b) -> b -> Text -> b Source # replicateChar :: Int -> Char -> Text Source # isNull :: Text -> Bool Source # splitLines :: Text -> [Text] Source #
HasChars Text Source # |
Instance details Defined in Text.DocLayout Methods foldrChar :: (Char -> b -> b) -> b -> Text -> b Source # foldlChar :: (b -> Char -> b) -> b -> Text -> b Source # replicateChar :: Int -> Char -> Text Source # isNull :: Text -> Bool Source # splitLines :: Text -> [Text] Source #