commit 3aed47433d38ac77bff998cf00afcaa4f6960c0d
parent 7bd78bfcdf6f558010ff5b9ff05d1a984837ff50
Author: krasjet
Date: 2020-07-20 22:42Z
add plain text readme
Diffstat:
A | README | | | 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