summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2017-10-25 17:05:37 -0700
committerJohn MacFarlane <jgm@berkeley.edu>2017-10-25 17:05:37 -0700
commite23d293915bcdd72429eacaa0b9ea9cec0c93bce (patch)
tree0204e81c3f66cf5576c9ca44d937777928329e2a /doc
parentdb715dc9d79c49493ddb19f29d98790abb474b49 (diff)
More work on using-the-pandoc-api.md.
Diffstat (limited to 'doc')
-rw-r--r--doc/using-the-pandoc-api.md68
1 files changed, 51 insertions, 17 deletions
diff --git a/doc/using-the-pandoc-api.md b/doc/using-the-pandoc-api.md
index da96a1902..6054df77d 100644
--- a/doc/using-the-pandoc-api.md
+++ b/doc/using-the-pandoc-api.md
@@ -188,20 +188,40 @@ Some particularly important options to know about:
# Builder
+Sometimes it's useful to construct a Pandoc document
+programatically. To make this easier we provide the
+module [Text.Pandoc.Builder](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html) in `pandoc-types`.
-Inlines vs Inline, etc.
+Because concatenating lists is slow, we use special
+types `Inlines` and `Blocks` that wrap a `Sequence` of
+`Inline` and `Block` elements. These are instances
+of the Monoid typeclass and can easily be concatenated:
-Concatenating lists is slow. So we use special types Inlines and Blocks that wrap Sequences of Inline and Block elements.
+```haskell
+import Text.Pandoc.Builder
-Monoid - makes it easy to build up docs programatically.
+mydoc :: Pandoc
+mydoc = doc $ header 1 (text "Hello!")
+ <> para (emph (text "hello world") <> text ".")
-Example.
-Here’s a JSON data source about CNG fueling stations in the
-Chicago area: cng_fuel_chicago.json. Boss says: write me a
-letter in Word listing all the stations that take the Voyager
-card.
+main :: IO ()
+main = print mydoc
+```
+If you use the `{-# LANGUAGE OverloadedStrings #-}`, you can
+simplify this further:
+
+```haskell
+mydoc = doc $ header 1 "Hello!"
+ <> para (emph "hello world" <> ".")
```
+
+Here's a more realistic example. Suppose your boss says: write
+me a letter in Word listing all the filling stations in Chicago
+that take the Voyager card. You find some JSON data in this
+format (`fuel.json`):
+
+```json
[ {
"state" : "IL",
"city" : "Chicago",
@@ -213,9 +233,10 @@ card.
}, ...
```
-No need to open Word for this job! fuel.hs
+And then use aeson and pandoc to parse the JSON and create
+the Word document:
-```
+```haskell
{-# LANGUAGE OverloadedStrings #-}
import Text.Pandoc.Builder
import Text.Pandoc
@@ -252,31 +273,43 @@ createLetter stations = doc $
stationToRow station =
[ plain (text $ name station)
, plain (text $ address station)
- , plain (mconcat $ intersperse linebreak $ map text $ cardsAccepted station)
+ , plain (mconcat $ intersperse linebreak
+ $ map text $ cardsAccepted station)
]
main :: IO ()
main = do
- json <- BL.readFile "cng_fuel_chicago.json"
+ json <- BL.readFile "fuel.json"
let letter = case decode json of
Just stations -> createLetter [s | s <- stations,
"Voyager" `elem` cardsAccepted s]
Nothing -> error "Could not decode JSON"
- BL.writeFile "letter.docx" =<< writeDocx def letter
+ docx <- runIO (writeDocx def letter) >>= handleError
+ BL.writeFile "letter.docx" docx
putStrLn "Created letter.docx"
```
-
+Voila! You've written the letter without using Word and
+without looking at the data.
# Templates and other data files
readDataFile
+getTemplate
+
# Handling errors and warnings
-# Generic transformations
+Text.Pandoc.Error
+Text.Pandoc.Logging
+getLog
+verbosity
+
+# Walking the AST
-Walk and syb for AST transformations
+Text.Pandoc.Walk for AST transformations
+walk and query, with examples
+(don't bother mentioning syb)
# Filters
@@ -284,8 +317,9 @@ Filters: see filters.md
applyFilters, applyLuaFilters from Text.Pandoc.App.
-# PDF
+# Creating a PDF
+Text.Pandoc.PDF
# Creating a front-end