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

License | BSD3 |

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

Stability | alpha |

Portability | portable |

Safe Haskell | Safe-Inferred |

Language | Haskell2010 |

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 -> [Text] extractURL (Link _ _ (u,_)) = [u] extractURL (Image _ _ (u,_)) = [u] extractURL _ = [] extractURLs :: Pandoc -> [Text] extractURLs = query extractURL

## Synopsis

- class Walkable a b where
- queryBlock :: (Walkable a Citation, Walkable a [Block], Walkable a Row, Walkable a Caption, Walkable a TableHead, Walkable a TableBody, Walkable a TableFoot, Walkable a [Inline], Monoid c) => (a -> c) -> Block -> c
- queryCaption :: (Walkable a [Block], Walkable a [Inline], Walkable a ShortCaption, Monoid c) => (a -> c) -> Caption -> c
- queryRow :: (Walkable a Cell, Monoid c) => (a -> c) -> Row -> c
- queryTableHead :: (Walkable a Row, Monoid c) => (a -> c) -> TableHead -> c
- queryTableBody :: (Walkable a Row, Monoid c) => (a -> c) -> TableBody -> c
- queryTableFoot :: (Walkable a Row, Monoid c) => (a -> c) -> TableFoot -> c
- queryCell :: (Walkable a [Block], Monoid c) => (a -> c) -> Cell -> 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
- queryMetaValue' :: Monoid c => (MetaValue -> c) -> MetaValue -> c
- queryPandoc :: (Walkable a Meta, Walkable a [Block], Monoid c) => (a -> c) -> Pandoc -> c
- walkBlockM :: (Walkable a [Block], Walkable a [Inline], Walkable a Row, Walkable a Caption, Walkable a TableHead, Walkable a TableBody, Walkable a TableFoot, Monad m, Applicative m, Functor m) => (a -> m a) -> Block -> m Block
- walkCaptionM :: (Walkable a [Block], Walkable a [Inline], Monad m, Walkable a ShortCaption) => (a -> m a) -> Caption -> m Caption
- walkRowM :: (Walkable a Cell, Monad m) => (a -> m a) -> Row -> m Row
- walkTableHeadM :: (Walkable a Row, Monad m) => (a -> m a) -> TableHead -> m TableHead
- walkTableBodyM :: (Walkable a Row, Monad m) => (a -> m a) -> TableBody -> m TableBody
- walkTableFootM :: (Walkable a Row, Monad m) => (a -> m a) -> TableFoot -> m TableFoot
- walkCellM :: (Walkable a [Block], Monad m) => (a -> m a) -> Cell -> m Cell
- 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
- walkMetaValueM' :: (Monad f, Applicative f, Functor f) => (MetaValue -> f MetaValue) -> 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 Row, Walkable a Caption, Walkable a TableHead, Walkable a TableBody, Walkable a TableFoot, 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.

queryCaption :: (Walkable a [Block], Walkable a [Inline], Walkable a ShortCaption, Monoid c) => (a -> c) -> Caption -> c Source #

Query the elements below a `Cell`

element.

queryRow :: (Walkable a Cell, Monoid c) => (a -> c) -> Row -> c Source #

Query the elements below a `Row`

element.

queryTableHead :: (Walkable a Row, Monoid c) => (a -> c) -> TableHead -> c Source #

Query the elements below a `TableHead`

element.

queryTableBody :: (Walkable a Row, Monoid c) => (a -> c) -> TableBody -> c Source #

Query the elements below a `TableBody`

element.

queryTableFoot :: (Walkable a Row, Monoid c) => (a -> c) -> TableFoot -> c Source #

Query the elements below a `TableFoot`

element.

queryCell :: (Walkable a [Block], Monoid c) => (a -> c) -> Cell -> c Source #

Query the elements below a `Cell`

element.

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], Walkable a Row, Walkable a Caption, Walkable a TableHead, Walkable a TableBody, Walkable a TableFoot, Monad m, Applicative m, Functor m) => (a -> m a) -> Block -> m Block Source #

walkCaptionM :: (Walkable a [Block], Walkable a [Inline], Monad m, Walkable a ShortCaption) => (a -> m a) -> Caption -> m Caption Source #

Helper method to walk the elements nested below `Caption`

nodes.

walkTableBodyM :: (Walkable a Row, Monad m) => (a -> m a) -> TableBody -> m TableBody Source #

Helper method to walk the elements nested below

nodes. The `TableBody`

and `Attr`

components are not
changed by this operation.`RowHeadColumns`

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.

walkMetaValueM' :: (Monad f, Applicative f, Functor f) => (MetaValue -> f MetaValue) -> MetaValue -> f MetaValue Source #