pandoc-types-1.23.1.1: Types for representing a structured document

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

Text.Pandoc.Builder

Contents

- Document builders
- Inline list builders
- Block list builders
- Table processing

Description

Convenience functions for building pandoc documents programmatically.

Example of use (with `OverloadedStrings` pragma):

    import Text.Pandoc.Builder

    myDoc :: Pandoc
    myDoc = setTitle "My title" $ doc $
      para "This is the first paragraph" <>
      para ("And " <> emph "another" <> ".") <>
      bulletList [ para "item one" <> para "continuation"
                 , plain ("item two and a " <>
                     link "/url" "go to url" "link")
                 ]

Isn't that nicer than writing the following?

    import Text.Pandoc.Definition
    import Data.Map (fromList)

    myDoc :: Pandoc
    myDoc = Pandoc (Meta {unMeta = fromList [("title",
              MetaInlines [Str "My",Space,Str "title"])]})
            [Para [Str "This",Space,Str "is",Space,Str "the",Space,Str "first",
             Space,Str "paragraph"],Para [Str "And",Space,Emph [Str "another"],
             Str "."]
            ,BulletList [
              [Para [Str "item",Space,Str "one"]
              ,Para [Str "continuation"]]
             ,[Plain [Str "item",Space,Str "two",Space,Str "and",Space,
                      Str "a",Space,Link nullAttr [Str "link"] ("/url","go to url")]]]]

And of course, you can use Haskell to define your own builders:

    import Text.Pandoc.Builder
    import Text.JSON
    import Control.Arrow ((***))
    import Data.Monoid (mempty)

    -- | Converts a JSON document into 'Blocks'.
    json :: String -> Blocks
    json x =
      case decode x of
           Ok y    -> jsValueToBlocks y
           Error y -> error y
       where jsValueToBlocks x =
              case x of
               JSNull         -> mempty
               JSBool x       -> plain $ text $ show x
               JSRational _ x -> plain $ text $ show x
               JSString x     -> plain $ text $ fromJSString x
               JSArray xs     -> bulletList $ map jsValueToBlocks xs
               JSObject x     -> definitionList $
                                  map (text *** (:[]) . jsValueToBlocks) $
                                  fromJSObject x

Synopsis

- module Text.Pandoc.Definition
- newtype Many a = Many {
  - unMany :: Seq a
  }
- type Inlines = Many Inline
- type Blocks = Many Block
- (<>) :: Semigroup a => a -> a -> a
- singleton :: a -> Many a
- toList :: Many a -> [a]
- fromList :: [a] -> Many a
- isNull :: Many a -> Bool
- doc :: Blocks -> Pandoc
- class ToMetaValue a where
  - toMetaValue :: a -> MetaValue
- class HasMeta a where
  - setMeta :: ToMetaValue b => Text -> b -> a -> a
  - deleteMeta :: Text -> a -> a
- setTitle :: Inlines -> Pandoc -> Pandoc
- setAuthors :: [Inlines] -> Pandoc -> Pandoc
- setDate :: Inlines -> Pandoc -> Pandoc
- text :: Text -> Inlines
- str :: Text -> Inlines
- emph :: Inlines -> Inlines
- underline :: Inlines -> Inlines
- strong :: Inlines -> Inlines
- strikeout :: Inlines -> Inlines
- superscript :: Inlines -> Inlines
- subscript :: Inlines -> Inlines
- smallcaps :: Inlines -> Inlines
- singleQuoted :: Inlines -> Inlines
- doubleQuoted :: Inlines -> Inlines
- cite :: [Citation] -> Inlines -> Inlines
- codeWith :: Attr -> Text -> Inlines
- code :: Text -> Inlines
- space :: Inlines
- softbreak :: Inlines
- linebreak :: Inlines
- math :: Text -> Inlines
- displayMath :: Text -> Inlines
- rawInline :: Text -> Text -> Inlines
- link :: Text -> Text -> Inlines -> Inlines
- linkWith :: Attr -> Text -> Text -> Inlines -> Inlines
- image :: Text -> Text -> Inlines -> Inlines
- imageWith :: Attr -> Text -> Text -> Inlines -> Inlines
- note :: Blocks -> Inlines
- spanWith :: Attr -> Inlines -> Inlines
- trimInlines :: Inlines -> Inlines
- para :: Inlines -> Blocks
- plain :: Inlines -> Blocks
- lineBlock :: [Inlines] -> Blocks
- codeBlockWith :: Attr -> Text -> Blocks
- codeBlock :: Text -> Blocks
- rawBlock :: Text -> Text -> Blocks
- blockQuote :: Blocks -> Blocks
- bulletList :: [Blocks] -> Blocks
- orderedListWith :: ListAttributes -> [Blocks] -> Blocks
- orderedList :: [Blocks] -> Blocks
- definitionList :: [(Inlines, [Blocks])] -> Blocks
- header :: Int -> Inlines -> Blocks
- headerWith :: Attr -> Int -> Inlines -> Blocks
- horizontalRule :: Blocks
- cell :: Alignment -> RowSpan -> ColSpan -> Blocks -> Cell
- simpleCell :: Blocks -> Cell
- emptyCell :: Cell
- cellWith :: Attr -> Alignment -> RowSpan -> ColSpan -> Blocks -> Cell
- table :: Caption -> [ColSpec] -> TableHead -> [TableBody] -> TableFoot -> Blocks
- simpleTable :: [Blocks] -> [[Blocks]] -> Blocks
- tableWith :: Attr -> Caption -> [ColSpec] -> TableHead -> [TableBody] -> TableFoot -> Blocks
- figure :: Caption -> Blocks -> Blocks
- figureWith :: Attr -> Caption -> Blocks -> Blocks
- caption :: Maybe ShortCaption -> Blocks -> Caption
- simpleCaption :: Blocks -> Caption
- emptyCaption :: Caption
- simpleFigureWith :: Attr -> Inlines -> Text -> Text -> Blocks
- simpleFigure :: Inlines -> Text -> Text -> Blocks
- divWith :: Attr -> Blocks -> Blocks
- normalizeTableHead :: Int -> TableHead -> TableHead
- normalizeTableBody :: Int -> TableBody -> TableBody
- normalizeTableFoot :: Int -> TableFoot -> TableFoot
- placeRowSection :: [RowSpan] -> [Cell] -> ([RowSpan], [Cell], [Cell])
- clipRows :: [Row] -> [Row]

# Documentation

module Text.Pandoc.Definition

newtype Many a Source #

Constructors

Many |

Fields

- unMany :: Seq a

#### Instances

Instances details

Arbitrary Blocks Source # |
Instance details Defined in Text.Pandoc.Arbitrary Methods arbitrary :: Gen Blocks Source # shrink :: Blocks -> [Blocks] Source #
Arbitrary Inlines Source # |
Instance details Defined in Text.Pandoc.Arbitrary Methods arbitrary :: Gen Inlines Source # shrink :: Inlines -> [Inlines] Source #
Functor Many Source # |
Instance details Defined in Text.Pandoc.Builder Methods fmap :: (a -> b) -> Many a -> Many b Source # (<$) :: a -> Many b -> Many a Source #
Monoid Blocks Source # |
Instance details Defined in Text.Pandoc.Builder Methods mempty :: Blocks Source # mappend :: Blocks -> Blocks -> Blocks Source # mconcat :: [Blocks] -> Blocks Source #
Monoid Inlines Source # |
Instance details Defined in Text.Pandoc.Builder Methods mempty :: Inlines Source # mappend :: Inlines -> Inlines -> Inlines Source # mconcat :: [Inlines] -> Inlines Source #
Semigroup Blocks Source # |
Instance details Defined in Text.Pandoc.Builder Methods (<>) :: Blocks -> Blocks -> Blocks Source # sconcat :: NonEmpty Blocks -> Blocks Source # stimes :: Integral b => b -> Blocks -> Blocks Source #
Semigroup Inlines Source # |
Instance details Defined in Text.Pandoc.Builder Methods (<>) :: Inlines -> Inlines -> Inlines Source # sconcat :: NonEmpty Inlines -> Inlines Source # stimes :: Integral b => b -> Inlines -> Inlines Source #
Foldable Many Source # |

Instance details

Defined in Text.Pandoc.Builder

Methods

fold :: Monoid m => Many m -> m Source #

foldMap :: Monoid m => (a -> m) -> Many a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Many a -> m Source #

foldr :: (a -> b -> b) -> b -> Many a -> b Source #

foldr' :: (a -> b -> b) -> b -> Many a -> b Source #

foldl :: (b -> a -> b) -> b -> Many a -> b Source #

foldl' :: (b -> a -> b) -> b -> Many a -> b Source #

foldr1 :: (a -> a -> a) -> Many a -> a Source #

foldl1 :: (a -> a -> a) -> Many a -> a Source #

toList :: Many a -> [a] Source #

null :: Many a -> Bool Source #

length :: Many a -> Int Source #

elem :: Eq a => a -> Many a -> Bool Source #

maximum :: Ord a => Many a -> a Source #

minimum :: Ord a => Many a -> a Source #

sum :: Num a => Many a -> a Source #

product :: Num a => Many a -> a Source #

IsString Inlines Source # |
Instance details Defined in Text.Pandoc.Builder Methods fromString :: String -> Inlines Source #
Traversable Many Source # |
Instance details Defined in Text.Pandoc.Builder Methods traverse :: Applicative f => (a -> f b) -> Many a -> f (Many b) Source # sequenceA :: Applicative f => Many (f a) -> f (Many a) Source # mapM :: Monad m => (a -> m b) -> Many a -> m (Many b) Source # sequence :: Monad m => Many (m a) -> m (Many a) Source #
ToMetaValue Blocks Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Blocks -> MetaValue Source #
ToMetaValue Inlines Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Inlines -> MetaValue Source #
Data a => Data (Many a) Source # |

Instance details

Defined in Text.Pandoc.Builder

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Many a -> c (Many a) Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Many a) Source #

toConstr :: Many a -> Constr Source #

dataTypeOf :: Many a -> DataType Source #

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

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

gmapT :: (forall b. Data b => b -> b) -> Many a -> Many a Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Many a -> r Source #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Many a -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> Many a -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Many a -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Many a -> m (Many a) Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Many a -> m (Many a) Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Many a -> m (Many a) Source #

Generic (Many a) Source # |

Instance details

Defined in Text.Pandoc.Builder

Associated Types

type Rep (Many a) |
Instance details Defined in Text.Pandoc.Builder type Rep (Many a) = D1 ('MetaData "Many" "Text.Pandoc.Builder" "pandoc-types-1.23.1.1-7EsQOX1JvASJuDrNxfLPBC" 'True) (C1 ('MetaCons "Many" 'PrefixI 'True) (S1 ('MetaSel ('Just "unMany") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Seq a))))

Methods

from :: Many a -> Rep (Many a) x Source #

to :: Rep (Many a) x -> Many a Source #

Read a => Read (Many a) Source # |
Instance details Defined in Text.Pandoc.Builder Methods readsPrec :: Int -> ReadS (Many a) Source # readList :: ReadS [Many a] Source # readPrec :: ReadPrec (Many a) Source # readListPrec :: ReadPrec [Many a] Source #
Show a => Show (Many a) Source # |
Instance details Defined in Text.Pandoc.Builder Methods showsPrec :: Int -> Many a -> ShowS Source # show :: Many a -> String Source # showList :: [Many a] -> ShowS Source #
Eq a => Eq (Many a) Source # |
Instance details Defined in Text.Pandoc.Builder Methods (==) :: Many a -> Many a -> Bool Source # (/=) :: Many a -> Many a -> Bool Source #
Ord a => Ord (Many a) Source # |
Instance details Defined in Text.Pandoc.Builder Methods compare :: Many a -> Many a -> Ordering Source # (<) :: Many a -> Many a -> Bool Source # (<=) :: Many a -> Many a -> Bool Source # (>) :: Many a -> Many a -> Bool Source # (>=) :: Many a -> Many a -> Bool Source # max :: Many a -> Many a -> Many a Source # min :: Many a -> Many a -> Many a Source #
type Rep (Many a) Source # |
Instance details Defined in Text.Pandoc.Builder type Rep (Many a) = D1 ('MetaData "Many" "Text.Pandoc.Builder" "pandoc-types-1.23.1.1-7EsQOX1JvASJuDrNxfLPBC" 'True) (C1 ('MetaCons "Many" 'PrefixI 'True) (S1 ('MetaSel ('Just "unMany") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Seq a))))

type Inlines = Many Inline Source #

type Blocks = Many Block Source #

(<>) :: Semigroup a => a -> a -> a infixr 6 Source #

An associative operation.

#### Examples

Expand

    >>> [1,2,3] <> [4,5,6]
    [1,2,3,4,5,6]

    >>> Just [1, 2, 3] <> Just [4, 5, 6]
    Just [1,2,3,4,5,6]

    >>> putStr "Hello, " <> putStrLn "World!"
    Hello, World!

singleton :: a -> Many a Source #

toList :: Many a -> [a] Source #

fromList :: [a] -> Many a Source #

isNull :: Many a -> Bool Source #

Deprecated: Use null instead

# Document builders

doc :: Blocks -> Pandoc Source #

class ToMetaValue a where Source #

Methods

toMetaValue :: a -> MetaValue Source #

#### Instances

Instances details

ToMetaValue Blocks Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Blocks -> MetaValue Source #
ToMetaValue Inlines Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Inlines -> MetaValue Source #
ToMetaValue MetaValue Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: MetaValue -> MetaValue Source #
ToMetaValue Text Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Text -> MetaValue Source #
ToMetaValue String Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: String -> MetaValue Source #
ToMetaValue Bool Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Bool -> MetaValue Source #
ToMetaValue a => ToMetaValue [a] Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: [a] -> MetaValue Source #
ToMetaValue a => ToMetaValue (Map Text a) Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Map Text a -> MetaValue Source #
ToMetaValue a => ToMetaValue (Map String a) Source # |
Instance details Defined in Text.Pandoc.Builder Methods toMetaValue :: Map String a -> MetaValue Source #

class HasMeta a where Source #

Methods

setMeta :: ToMetaValue b => Text -> b -> a -> a Source #

deleteMeta :: Text -> a -> a Source #

#### Instances

Instances details

HasMeta Meta Source # |
Instance details Defined in Text.Pandoc.Builder Methods setMeta :: ToMetaValue b => Text -> b -> Meta -> Meta Source # deleteMeta :: Text -> Meta -> Meta Source #
HasMeta Pandoc Source # |
Instance details Defined in Text.Pandoc.Builder Methods setMeta :: ToMetaValue b => Text -> b -> Pandoc -> Pandoc Source # deleteMeta :: Text -> Pandoc -> Pandoc Source #

setTitle :: Inlines -> Pandoc -> Pandoc Source #

setAuthors :: [Inlines] -> Pandoc -> Pandoc Source #

setDate :: Inlines -> Pandoc -> Pandoc Source #

# Inline list builders

text :: Text -> Inlines Source #

Convert a `Text` to `Inlines`, treating interword spaces as `Space`s or `SoftBreak`s. If you want a `Str` with literal spaces, use `str`.

str :: Text -> Inlines Source #

emph :: Inlines -> Inlines Source #

underline :: Inlines -> Inlines Source #

strong :: Inlines -> Inlines Source #

strikeout :: Inlines -> Inlines Source #

superscript :: Inlines -> Inlines Source #

subscript :: Inlines -> Inlines Source #

smallcaps :: Inlines -> Inlines Source #

singleQuoted :: Inlines -> Inlines Source #

doubleQuoted :: Inlines -> Inlines Source #

cite :: [Citation] -> Inlines -> Inlines Source #

codeWith :: Attr -> Text -> Inlines Source #

Inline code with attributes.

code :: Text -> Inlines Source #

Plain inline code.

space :: Inlines Source #

softbreak :: Inlines Source #

linebreak :: Inlines Source #

math :: Text -> Inlines Source #

Inline math

displayMath :: Text -> Inlines Source #

Display math

rawInline :: Text -> Text -> Inlines Source #

link Source #

Arguments

:: Text | URL
-> Text | Title
-> Inlines | Label
-> Inlines |

linkWith Source #

Arguments

:: Attr | Attributes
-> Text | URL
-> Text | Title
-> Inlines | Label
-> Inlines |

image Source #

Arguments

:: Text | URL
-> Text | Title
-> Inlines | Alt text
-> Inlines |

imageWith Source #

Arguments

:: Attr | Attributes
-> Text | URL
-> Text | Title
-> Inlines | Alt text
-> Inlines |

note :: Blocks -> Inlines Source #

spanWith :: Attr -> Inlines -> Inlines Source #

trimInlines :: Inlines -> Inlines Source #

Trim leading and trailing spaces and softbreaks from an Inlines.

# Block list builders

para :: Inlines -> Blocks Source #

plain :: Inlines -> Blocks Source #

lineBlock :: [Inlines] -> Blocks Source #

codeBlockWith :: Attr -> Text -> Blocks Source #

A code block with attributes.

codeBlock :: Text -> Blocks Source #

A plain code block.

rawBlock :: Text -> Text -> Blocks Source #

blockQuote :: Blocks -> Blocks Source #

bulletList :: [Blocks] -> Blocks Source #

orderedListWith :: ListAttributes -> [Blocks] -> Blocks Source #

Ordered list with attributes.

orderedList :: [Blocks] -> Blocks Source #

Ordered list with default attributes.

definitionList :: [(Inlines, [Blocks])] -> Blocks Source #

header Source #

Arguments

:: Int | Level
-> Inlines |
-> Blocks |

headerWith :: Attr -> Int -> Inlines -> Blocks Source #

horizontalRule :: Blocks Source #

cell :: Alignment -> RowSpan -> ColSpan -> Blocks -> Cell Source #

simpleCell :: Blocks -> Cell Source #

A 1×1 cell with default alignment.

emptyCell :: Cell Source #

A 1×1 empty cell.

cellWith :: Attr -> Alignment -> RowSpan -> ColSpan -> Blocks -> Cell Source #

table :: Caption -> [ColSpec] -> TableHead -> [TableBody] -> TableFoot -> Blocks Source #

Table builder. Performs normalization with `normalizeTableHead`, `normalizeTableBody`, and `normalizeTableFoot`. The number of table columns is given by the length of `[`ColSpec`]`.

simpleTable Source #

Arguments

:: [Blocks] | Headers
-> [[Blocks]] | Rows
-> Blocks |

A simple table without a caption.

tableWith :: Attr -> Caption -> [ColSpec] -> TableHead -> [TableBody] -> TableFoot -> Blocks Source #

figure :: Caption -> Blocks -> Blocks Source #

figureWith :: Attr -> Caption -> Blocks -> Blocks Source #

caption :: Maybe ShortCaption -> Blocks -> Caption Source #

simpleCaption :: Blocks -> Caption Source #

emptyCaption :: Caption Source #

simpleFigureWith :: Attr -> Inlines -> Text -> Text -> Blocks Source #

Creates a simple figure from attributes, a figure caption, an image path and image title. The attributes are used as the image attributes.

simpleFigure :: Inlines -> Text -> Text -> Blocks Source #

divWith :: Attr -> Blocks -> Blocks Source #

# Table processing

normalizeTableHead :: Int -> TableHead -> TableHead Source #

Normalize the `TableHead` with `clipRows` and `placeRowSection` so that when placed on a grid with the given width and a height equal to the number of rows in the initial `TableHead`, there will be no empty spaces or overlapping cells, and the cells will not protrude beyond the grid.

normalizeTableBody :: Int -> TableBody -> TableBody Source #

Normalize the intermediate head and body section of a `TableBody`, as in `normalizeTableHead`, but additionally ensure that row head cells do not go beyond the row head inside the intermediate body.

normalizeTableFoot :: Int -> TableFoot -> TableFoot Source #

Normalize the `TableFoot`, as in `normalizeTableHead`.

placeRowSection Source #

Arguments

:: [RowSpan] | The overhang of the previous grid row
-> [Cell] | The cells to lay on the grid row
-> ([RowSpan], [Cell], [Cell]) | The overhang of the current grid row, the normalized cells that fit on the current row, and the remaining unmodified cells

Normalize the given list of cells so that they fit on a single grid row. The `RowSpan` values of the cells are assumed to be valid (clamped to lie between 1 and the remaining grid height). The cells in the list are also assumed to be able to fill the entire grid row. These conditions can be met by appending `repeat `emptyCell`` to the `[`Cell`]` list and using `clipRows` on the entire table section beforehand.

Normalization follows the principle that cells are placed on a grid row in order, each at the first available grid position from the left, having their `ColSpan` reduced if they would overlap with a previous cell, stopping once the row is filled. Only the dimensions of cells are changed, and only of those cells that fit on the row.

Possible overlap is detected using the given `[`RowSpan`]`, which is the "overhang" of the previous grid row, a list of the heights of cells that descend through the previous row, reckoned only from the previous row. Its length should be the width (number of columns) of the current grid row.

For example, the numbers in the following headerless grid table represent the overhang at each grid position for that table:

        1   1   1   1
      +---+---+---+---+
      | 1 | 2   2 | 3 |
      +---+       +   +
      | 1 | 1   1 | 2 |
      +---+---+---+   +
      | 1   1 | 1 | 1 |
      +---+---+---+---+

In any table, the row before the first has an overhang of `replicate tableWidth 1`, since there are no cells to descend into the table from there. The overhang of the first row in the example is `[1, 2, 2, 3]`.

So if after `clipRows` the unnormalized second row of that example table were

    r = [("a", 1, 2),("b", 2, 3)] -- the cells displayed as (label, RowSpan, ColSpan) only

a correct invocation of `placeRowSection` to normalize it would be

    >>> placeRowSection [1, 2, 2, 3] $ r ++ repeat emptyCell
    ([1, 1, 1, 2], [("a", 1, 1)], [("b", 2, 3)] ++ repeat emptyCell) -- wouldn't stop printing, of course

and if the third row were only `[("c", 1, 2)]`, then the expression would be

    >>> placeRowSection [1, 1, 1, 2] $ [("c", 1, 2)] ++ repeat emptyCell
    ([1, 1, 1, 1], [("c", 1, 2), emptyCell], repeat emptyCell)

clipRows :: [Row] -> [Row] Source #

Ensure that the height of each cell in a table section lies between 1 and the distance from its row to the end of the section. So if there were four rows in the input list, the cells in the second row would have their height clamped between 1 and 3.