Copyright | Copyright (C) 2013-2019 John MacFarlane |
---|---|

License | BSD3 |

Maintainer | John MacFarlane <jgm@berkeley.edu> |

Stability | alpha |

Portability | portable |

Safe Haskell | None |

Language | Haskell98 |

Functions for manipulating `Pandoc`

documents or extracting
information from them by walking the `Pandoc`

structure (or
intermediate structures like '[Block]' or '[Inline]'.
These are faster (by a factor of four or five) than the generic
functions defined in `Text.Pandoc.Generic`

.

Here's a simple example, defining a function that replaces all the level 3+ headers in a document with regular paragraphs in ALL CAPS:

import Text.Pandoc.Definition import Text.Pandoc.Walk import Data.Char (toUpper) modHeader :: Block -> Block modHeader (Header n _ xs) | n >= 3 = Para $ walk allCaps xs modHeader x = x allCaps :: Inline -> Inline allCaps (Str xs) = Str $ map toUpper xs allCaps x = x changeHeaders :: Pandoc -> Pandoc changeHeaders = walk modHeader

`query`

can be used, for example, to compile a list of URLs
linked to in a document:

extractURL :: Inline -> [String] extractURL (Link _ _ (u,_)) = [u] extractURL (Image _ _ (u,_)) = [u] extractURL _ = [] extractURLs :: Pandoc -> [String] extractURLs = query extractURL

## Synopsis

- class Walkable a b where
- queryBlock :: (Walkable a Citation, Walkable a [Block], Walkable a [Inline], Monoid c) => (a -> c) -> Block -> c
- queryCitation :: (Walkable a [Inline], Monoid c) => (a -> c) -> Citation -> c
- queryInline :: (Walkable a Citation, Walkable a [Block], Walkable a [Inline], Monoid c) => (a -> c) -> Inline -> c
- queryMetaValue :: (Walkable a MetaValue, Walkable a [Block], Walkable a [Inline], Monoid c) => (a -> c) -> MetaValue -> c
- queryPandoc :: (Walkable a Meta, Walkable a [Block], Monoid c) => (a -> c) -> Pandoc -> c
- walkBlockM :: (Walkable a [Block], Walkable a [Inline], Monad m, Applicative m, Functor m) => (a -> m a) -> Block -> m Block
- walkCitationM :: (Walkable a [Inline], Monad m, Applicative m, Functor m) => (a -> m a) -> Citation -> m Citation
- walkInlineM :: (Walkable a Citation, Walkable a [Block], Walkable a [Inline], Monad m, Applicative m, Functor m) => (a -> m a) -> Inline -> m Inline
- walkMetaValueM :: (Walkable a MetaValue, Walkable a [Block], Walkable a [Inline], Monad f, Applicative f, Functor f) => (a -> f a) -> MetaValue -> f MetaValue
- walkPandocM :: (Walkable a Meta, Walkable a [Block], Monad m, Applicative m, Functor m) => (a -> m a) -> Pandoc -> m Pandoc

# Documentation

class Walkable a b where Source #

walk :: (a -> a) -> b -> b Source #

`walk f x`

walks the structure `x`

(bottom up) and replaces every
occurrence of an `a`

with the result of applying `f`

to it.

walkM :: (Monad m, Applicative m, Functor m) => (a -> m a) -> b -> m b Source #

A monadic version of `walk`

.

query :: Monoid c => (a -> c) -> b -> c Source #

`query f x`

walks the structure `x`

(bottom up) and applies `f`

to every `a`

, appending the results.

## Instances

queryBlock :: (Walkable a Citation, Walkable a [Block], Walkable a [Inline], Monoid c) => (a -> c) -> Block -> c Source #

Perform a query on elements nested below a

element by
querying all directly nested lists of `Block`

`Inline`

s or `Block`

s.

queryCitation :: (Walkable a [Inline], Monoid c) => (a -> c) -> Citation -> c Source #

Perform a query on elements nested below a

element by
querying the prefix and postfix `Citation`

`Inline`

lists.

queryInline :: (Walkable a Citation, Walkable a [Block], Walkable a [Inline], Monoid c) => (a -> c) -> Inline -> c Source #

Perform a query on elements nested below an

element by
querying nested lists of `Inline`

`Inline`

s, `Block`

s, or `Citation`

s.

queryMetaValue :: (Walkable a MetaValue, Walkable a [Block], Walkable a [Inline], Monoid c) => (a -> c) -> MetaValue -> c Source #

Perform a query on elements nested below a

element by
querying all directly nested lists of `MetaValue`

`Inline`

s, list of `Block`

s, or
lists or maps of `MetaValue`

s.

walkBlockM :: (Walkable a [Block], Walkable a [Inline], Monad m, Applicative m, Functor m) => (a -> m a) -> Block -> m Block Source #

walkCitationM :: (Walkable a [Inline], Monad m, Applicative m, Functor m) => (a -> m a) -> Citation -> m Citation Source #

Helper method to walk to elements nested below

nodes.`Citation`

The non-inline contents of a citation will remain unchanged during traversal. Only the inline contents, viz. the citation's prefix and postfix, will be traversed further and can thus be changed during this operation.

walkInlineM :: (Walkable a Citation, Walkable a [Block], Walkable a [Inline], Monad m, Applicative m, Functor m) => (a -> m a) -> Inline -> m Inline Source #

Helper method to walk to elements nested below

nodes.`Inline`

When walking an inline with this function, only the contents of the traversed inline element may change. The element itself, i.e. its constructor, cannot be changed.

walkMetaValueM :: (Walkable a MetaValue, Walkable a [Block], Walkable a [Inline], Monad f, Applicative f, Functor f) => (a -> f a) -> MetaValue -> f MetaValue Source #

Helper method to walk to elements nested below

nodes.`MetaValue`

When walking a meta value with this function, only the contents of the
traversed meta value element may change. `MetaBool`

and `MetaString`

will
always remain unchanged.