diff options
Diffstat (limited to 'doc/using-the-pandoc-api.md')
| -rw-r--r-- | doc/using-the-pandoc-api.md | 37 |
1 files changed, 25 insertions, 12 deletions
diff --git a/doc/using-the-pandoc-api.md b/doc/using-the-pandoc-api.md index df9380313..d44e82e9b 100644 --- a/doc/using-the-pandoc-api.md +++ b/doc/using-the-pandoc-api.md @@ -14,7 +14,7 @@ and types is available at Pandoc is structured as a set of *readers*, which translate various input formats into an abstract syntax tree (the Pandoc AST) representing a structured document, and a set of -*writers*, which render this AST into various input formats. +*writers*, which render this AST into various output formats. Pictorially: ``` @@ -90,8 +90,14 @@ Some notes: Let's look at the types of `readMarkdown` and `writeRST`: ```haskell -readMarkdown :: PandocMonad m => ReaderOptions -> Text -> m Pandoc -writeRST :: PandocMonad m => WriterOptions -> Pandoc -> m Text +readMarkdown :: (PandocMonad m, ToSources a) + => ReaderOptions + -> a + -> m Pandoc +writeRST :: PandocMonad m + => WriterOptions + -> Pandoc + -> m Text ``` The `PandocMonad m =>` part is a typeclass constraint. @@ -133,7 +139,7 @@ report :: PandocMonad m => LogMessage -> m () -- | Fetch an image or other item from the local filesystem or the net. -- Returns raw content and maybe mime type. fetchItem :: PandocMonad m - => String + => Text -> m (B.ByteString, Maybe MimeType) -- Set the resource path searched by 'fetchItem'. @@ -155,6 +161,13 @@ Note that `PandocIO` is an instance of `MonadIO`, so you can use `liftIO` to perform arbitrary IO operations inside a pandoc conversion chain. +`readMarkdown` is polymorphic in its second argument, which +can be any type that is an instance of the `ToSources` +typeclass. You can use `Text`, as in the example above. +But you can also use `[(FilePath, Text)]`, if the input comes +from multiple files and you want to track source positions +accurately. + # Options The first argument of each reader or writer is for @@ -200,8 +213,8 @@ of the Monoid typeclass and can easily be concatenated: import Text.Pandoc.Builder mydoc :: Pandoc -mydoc = doc $ header 1 (text "Hello!") - <> para (emph (text "hello world") <> text ".") +mydoc = doc $ header 1 (text (T.pack "Hello!")) + <> para (emph (text (T.pack "hello world")) <> text (T.pack ".")) main :: IO () main = print mydoc @@ -248,16 +261,16 @@ import qualified Data.Text as T import Data.List (intersperse) data Station = Station{ - address :: String - , name :: String - , cardsAccepted :: [String] + address :: T.Text + , name :: T.Text + , cardsAccepted :: [T.Text] } deriving Show instance FromJSON Station where parseJSON (Object v) = Station <$> v .: "street_address" <*> v .: "station_name" <*> - (words <$> (v .:? "cards_accepted" .!= "")) + (T.words <$> (v .:? "cards_accepted" .!= "")) parseJSON _ = mzero createLetter :: [Station] -> Pandoc @@ -315,7 +328,7 @@ users to override the system defaults. If you want to disable this behavior, use `setUserDataDir Nothing`. To render a template, use `renderTemplate'`, which takes two -arguments, a template (String) and a context (any instance +arguments, a template (Text) and a context (any instance of ToJSON). If you want to create a context from the metadata part of a Pandoc document, use `metaToJSON'` from [Text.Pandoc.Writers.Shared]. If you also want to incorporate @@ -413,7 +426,7 @@ concatenated together. Here's an example that returns a list of the URLs linked to in a document: ```haskell -listURLs :: Pandoc -> [String] +listURLs :: Pandoc -> [Text] listURLs = query urls where urls (Link _ _ (src, _)) = [src] urls _ = [] |