Text.DocLayout

doclayout-0.3.1.1: 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-Inferred
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
- realLengthNoShortcut :: HasChars a => a -> Int
- isEmojiModifier :: Char -> Bool
- isEmojiVariation :: Char -> Bool
- isEmojiJoiner :: Char -> Bool
- 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 #

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 #

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

blankline :: Doc a #

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

blanklines :: Int -> Doc a #

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

space :: Doc a #

A breaking (reflowable) space.

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

Create a `Doc` from a stringlike value.

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

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

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

A character.

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

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 #

Makes a `Doc` flush against the left margin.

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

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

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

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 #

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

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

Makes a `Doc` non-reflowable.

afterBreak :: Text -> Doc a #

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 #

`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 #

Like `lblock` but aligned centered.

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

Like `lblock` but aligned to the right.

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

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 #

Removes leading blank lines from a `Doc`.

chomp :: Doc a -> Doc a #

Chomps trailing blank space off of a `Doc`.

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

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

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

Puts a `Doc` in curly braces.

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

Puts a `Doc` in square brackets.

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

Puts a `Doc` in parentheses.

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

Wraps a `Doc` in single quotes.

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

Wraps a `Doc` in double quotes.

empty :: Doc a #

The empty document.

# Functions for concatenating documents

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

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

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

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

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

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

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

Concatenate documents horizontally.

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

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

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

List version of `$$`.

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

List version of `$+$`.

# Functions for querying documents

isEmpty :: Doc a -> Bool #

True if the document is empty.

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

Returns the width of a `Doc`.

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

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

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

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

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

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

charWidth :: Char -> Int #

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 #

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

realLengthNoShortcut :: HasChars a => a -> Int #

Get real length of string, taking into account combining and double-wide characters, without taking any shortcuts. This should give the same answer as `updateMatchState`, but will be slower. It is here to test that the shortcuts are implemented correctly.

isEmojiModifier :: Char -> Bool #

Checks whether a character is a skin tone modifier

isEmojiVariation :: Char -> Bool #

Checks whether a character is an emoji variation modifier.

isEmojiJoiner :: Char -> Bool #

Checks whether a character is an emoji joiner.

# Types

data Doc a #

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

Foldable Doc # |
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 # |
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) #
Functor Doc # |
Instance details Defined in Text.DocLayout Methods fmap :: (a -> b) -> Doc a -> Doc b # (<$) :: a -> Doc b -> Doc a #
Data a => Data (Doc a) # |
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) #
HasChars a => IsString (Doc a) # |
Instance details Defined in Text.DocLayout Methods fromString :: String -> Doc a #
Monoid (Doc a) # |
Instance details Defined in Text.DocLayout Methods mempty :: Doc a # mappend :: Doc a -> Doc a -> Doc a # mconcat :: [Doc a] -> Doc a #
Semigroup (Doc a) # |
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 #
Generic (Doc a) # |
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 #
Read a => Read (Doc a) # |
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) # |
Instance details Defined in Text.DocLayout Methods showsPrec :: Int -> Doc a -> ShowS # show :: Doc a -> String # showList :: [Doc a] -> ShowS #
Eq a => Eq (Doc a) # |
Instance details Defined in Text.DocLayout Methods (==) :: Doc a -> Doc a -> Bool # (/=) :: Doc a -> Doc a -> Bool #
Ord a => Ord (Doc a) # |
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 #
type Rep (Doc a) # |
Instance details Defined in Text.DocLayout type Rep (Doc a) = D1 ('MetaData "Doc" "Text.DocLayout" "doclayout-0.3.1.1-L04bvYoI0SgD2S0U1EswZE" '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 #

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 #

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

replicateChar :: Int -> Char -> a #

isNull :: a -> Bool #

splitLines :: a -> [a] #

#### Instances

Instances details

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