commit 3aed47433d38ac77bff998cf00afcaa4f6960c0d
parent 7bd78bfcdf6f558010ff5b9ff05d1a984837ff50
Author: krasjet
Date: 2020-07-20 22:42Z

add plain text readme

Diffstat:
AREADME | 117+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 117 insertions(+), 0 deletions(-)

diff --git a/README b/README @@ -0,0 +1,117 @@ +pandoc-utils +============ + +This package contains some useful functions for writing Pandoc filters and +integrating Pandoc into Haskell applications such as Hakyll. + +It provides a composable wrapper for filters acting on nodes of the Pandoc AST +[1] and a few functions to convert between filters. The package also provides +an attributes builder to work with attributes and some string utility functions +to handle the switch from `String` to `Text` in pandoc-types 1.20. + +Filter conversion/composition +----------------------------- + +As an example, let us look at the `behead` and `delink` filter from Pandoc's +tutorial [3]. + + behead :: Block -> Block + behead (Header n _ xs) | n >= 2 = Para [Emph xs] + behead x = x + + delink :: Inline -> [Inline] + delink (Link _ txt _) = txt + delink x = [x] + +Since `behead` has type `Block -> Block`, while `delink` has type +`Inline -> [Inline]`, they are not naturally composable. However, this package +provides a utility function `mkFilter` to convert them into a wrapped `PandocFilter`. + + import Text.Pandoc.Utils + + beheadFilter :: PandocFilter + beheadFilter = mkFilter behead + + delinkFilter :: PandocFilter + delinkFilter = mkFilter delink + +`PandocFilter` is an alias for `PartialFilter Pandoc`, so you can also have +`PartialFilter Inline`, etc. There is also a monadic version called +`PartialFilterM` for encapsulating monadic filter functions. + +The `PandocFilter` is a monoid so you can do something like, + + myFilter :: PandocFilter + myFilter = beheadFilter <> delinkFilter + +where `myFilter` would apply `beheadFilter` first, then the `delinkFilter`. You +can apply the filter using `applyFilter`, + + import Text.Pandoc + import Data.Default (def) + + mdToHtml + :: Text -- ^ Input markdown string + -> Either PandocError Text -- ^ Html string or error + mdToHtml md = runPure $ do + doc <- readMarkdown def md + let doc' = applyFilter myFilter doc + writeHtml5String def doc' + +or get an unwrapped `Pandoc -> Pandoc` filter function using `getFilter` (this +function is also capable of doing implicit conversion from `PartialFilter a` to +`b -> b`). + + myPandocFilter :: Pandoc -> Pandoc + myPandocFilter = getFilter myFilter + +If you just want to convert between Pandoc filter functions, e.g. +`Inline -> [Inline]` to `Pandoc -> Pandoc` without using the wrapped filter, +there is also `convertFilter` and `convertFilterM` + + delinkPandoc :: Pandoc -> Pandoc + delinkPandoc = convertFilter delink + +This function is slightly more powerful than `walk` and `walkM` in that it is +also able to handle filter functions of type `a -> [a]` and `a -> m [a]`. + +For applying multiple filters, there is also a function called +`sequenceFilters`, which takes a list of wrapped filters and apply it to a +`Pandoc` document (or subnode) sequentially, from left to right. + + myFilters :: [PandocFilter] + myFilters = + [ beheadFilter + , delinkFilter + ] + + mdToHtml' + :: Text -- ^ Input markdown string + -> Either PandocError Text -- ^ Html string or error + mdToHtml' md = runPure $ do + doc <- readMarkdown def md + let doc' = sequenceFilters myFilters doc + writeHtml5String def doc' + +Attribute builder +================ + +pandoc-utils also provides an attribute builder for handling attributes. You +can create a new attributes by + + ghci> import Text.Pandoc.Utils + ghci> import Text.Pandoc.Definition + ghci> nullAttr `setId` "id" `addClass` "class" `addKVPair` ("key","value") + ("id",["class"],[("key","value")]) + +or modifying an existing attributes by + + ghci> attr = ("id",[],[]) + ghci> attr `setId` "newId" + ("newId",[],[]) + +For more examples, please read the spec [3]. + +[1]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html +[2]: https://pandoc.org/filters.html +[3]: ./test/Spec.hs