The Document Type

Pandoc documents are represented as values of type Pandoc; to get its definition, type:

> :info Pandoc
data Pandoc = Pandoc Meta [Block]
...

(the ellipsis denotes details of the output that we have omitted).

Here is how you should read this: the data type Pandoc (keyword data) is declared with a single constructor, also named Pandoc, whose arguments are:

• a value of type Meta (that represents the document metadata),

• a list ([] notation) of Block values (that represent the document itself).

This is actually all the information we need to build a document – or at least the empty document – because Text.Pandoc.Definition conveniently provides an empty metadata named nullMeta. So we can define

> let meta = nullMeta

for blocks, use an empty list

> let blocks = []

and use these values to create an empty document:

> let doc = Pandoc meta blocks

Blocks and Inlines

Consider the Block type:

> :info Block
data Block
  = Plain [Inline]
  | Para [Inline]
  | CodeBlock Attr String
  | RawBlock Format String
  | BlockQuote [Block]
  | OrderedList ListAttributes [[Block]]
  | BulletList [[Block]]
  | DefinitionList [([Inline], [[Block]])]
  | Header Int Attr [Inline]
  | HorizontalRule
  | Table [Inline] [Alignment] [Double] [TableCell] [[TableCell]]
  | Div Attr [Block]
  | Null
...

Its has 13 different constructors. Some of the constructors have no arguments, for example the horizontal rule

> let block = HorizontalRule

but most of them have arguments of various types:

• String, Int and Double are Haskell primitive types that represent sequences of characters, integers and (floating-point) numbers,

• The notation [] is used for lists – homogeneous sequences of varying length – and the (,) notation for tuples – heterogeneous sequences of fixed length. Hence, [[Block]] denotes a list of list of blocks and [([Inline], [[Block]])] a list of pairs of list of inlines and list of list of blocks (ouch!).

• The burden of complex types based on lists and tuples may be reduced by the use of type aliases (defined with the keyword type). The constructs Attr, Format, ListAttributes, and TableCell are types aliases; for example:

  > :info Attr
  type Attr = (String, [String], [(String, String)])
  > let attr = ("", [], [])

• Format is declared with the newtype keyword

  > :info Format
  newtype Format = Format String
  ...

  You can think of it as an mere optimization of the data construct when the type has a simple constructor whose name is the type name. Otherwise, this type is similar to a classic data type; for example, create a Format value with:

  > let format = Format "html"

• The other types used as arguments are pandoc data types; for example

  > :info Inline
  data Inline
    = Str String
    | Emph [Inline]
    | Strong [Inline]
    | Strikeout [Inline]
    | Superscript [Inline]
    | Subscript [Inline]
    | SmallCaps [Inline]
    | Quoted QuoteType [Inline]
    | Cite [Citation] [Inline]
    | Code Attr String
    | Space
    | LineBreak
    | Math MathType String
    | RawInline Format String
    | Link [Inline] Target
    | Image [Inline] Target
    | Note [Block]
    | Span Attr [Inline]
  ...

  You should now be able to understand all constructs used in this definition.

Metadata

Let’s import some objects related to the Haskell Map type – a key-value store – extensively used in document metadata:

> import Data.Map (Map, fromList, empty)

The fromList function creates a map from a list of key-value pairs and empty is the name of the empty map:

> empty
fromList []

Consider the pandoc Meta type that represents document metadata:

> :info Meta
newtype Meta
  = Meta {unMeta :: Map String MetaValue}

Let’s discard the use of newtype keyword – we know that it’s similar to data. Meta has a single constructor which is declared as a record – using the {} syntax – with a single field named unMeta. The type of this field is a map with String keys and MetaValue values.

To define values associated to record constructors, we may use named arguments instead of positional arguments; here:

> let meta = Meta {unMeta = empty}
> meta
Meta {unMeta = fromList []}

The only other use of the record construct among pandoc types is Citation:

> :info Citation
data Citation
  = Citation {citationId :: String,
              citationPrefix :: [Inline],
              citationSuffix :: [Inline],
              citationMode :: CitationMode,
              citationNoteNum :: Int,
              citationHash :: Int}
...