{- | Parse and render an API type, write documentation to file, stdout

__Example script__

[Writing documentation to file](https://github.com/Holmusk/servant-docs-simple/blob/master/examples/generate.hs)

/With the following language extensions/

> DataKinds
> TypeApplications
> TypeOperators

/Using this script/

> module Main where
>
> import Servant.API ((:>), Post, ReqBody)
> import Servant.Docs.Simple (writeDocsJson, writeDocsPlainText)
>
> -- Our API type
> type API = "hello" :> "world" :> Request :> Response
> type Request = ReqBody '[()] ()
> type Response = Post '[()] ()
>
> main :: IO ()
> main = do
>   -- Writes to the file $PWD/docsJson
>   writeDocsJson @API "docs.json"
>
>   -- Writes to the file $PWD/docsPlainText
>   writeDocsPlainText @API "docs.txt"

__Expected Output__

/Files should be generated relative to @$PWD@/

> $ ls | grep docs
> docs.json
> docs.txt

/docs.json/

> {
>     "/hello/world": {
>         "Response": {
>             "Format": "': * () ('[] *)",
>             "ContentType": "()"
>         },
>         "RequestType": "'POST",
>         "RequestBody": {
>             "Format": "': * () ('[] *)",
>             "ContentType": "()"
>         }
>     }
> }

/docs.txt/

> /hello/world:
> RequestBody:
>     Format: ': * () ('[] *)
>     ContentType: ()
> RequestType: 'POST
> Response:
>     Format: ': * () ('[] *)
>     ContentType: ()

-}

module Servant.Docs.Simple ( document
                           , documentWith
                           , stdoutJson
                           , stdoutPlainText
                           , writeDocsJson
                           , writeDocsPlainText
                           ) where

import Data.Aeson.Encode.Pretty (encodePretty)
import qualified Data.ByteString.Lazy as B (writeFile)
import qualified Data.ByteString.Lazy.Char8 as BC (putStrLn)
import qualified Data.Text.IO as T (putStrLn, writeFile)
import Servant.Docs.Simple.Parse (HasParsable (..))
import Servant.Docs.Simple.Render (Json (..), PlainText (..), Renderable (..))


-- | Write documentation as PlainText to file
writeDocsPlainText :: forall api. HasParsable api => FilePath -> IO ()
writeDocsPlainText :: FilePath -> IO ()
writeDocsPlainText fp :: FilePath
fp = FilePath -> Text -> IO ()
T.writeFile FilePath
fp (Text -> IO ()) -> (PlainText -> Text) -> PlainText -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. PlainText -> Text
getPlainText (PlainText -> IO ()) -> PlainText -> IO ()
forall a b. (a -> b) -> a -> b
$ HasParsable api => PlainText
forall k (api :: k). HasParsable api => PlainText
document @api

-- | Write documentation as JSON to file
writeDocsJson :: forall api. HasParsable api => FilePath -> IO ()
writeDocsJson :: FilePath -> IO ()
writeDocsJson fp :: FilePath
fp = FilePath -> ByteString -> IO ()
B.writeFile FilePath
fp (ByteString -> IO ()) -> (Json -> ByteString) -> Json -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Value -> ByteString
forall a. ToJSON a => a -> ByteString
encodePretty (Value -> ByteString) -> (Json -> Value) -> Json -> ByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Json -> Value
getJson (Json -> IO ()) -> Json -> IO ()
forall a b. (a -> b) -> a -> b
$ (HasParsable api, Renderable Json) => Json
forall k (api :: k) a. (HasParsable api, Renderable a) => a
documentWith @api @Json

-- | Write documentation as PlainText to stdout
stdoutPlainText :: forall api. HasParsable api => IO ()
stdoutPlainText :: IO ()
stdoutPlainText = Text -> IO ()
T.putStrLn (Text -> IO ()) -> (PlainText -> Text) -> PlainText -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. PlainText -> Text
getPlainText (PlainText -> IO ()) -> PlainText -> IO ()
forall a b. (a -> b) -> a -> b
$ HasParsable api => PlainText
forall k (api :: k). HasParsable api => PlainText
document @api

-- | Write documentation as JSON to stdout
stdoutJson :: forall api. HasParsable api => IO ()
stdoutJson :: IO ()
stdoutJson = ByteString -> IO ()
BC.putStrLn (ByteString -> IO ()) -> (Json -> ByteString) -> Json -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Value -> ByteString
forall a. ToJSON a => a -> ByteString
encodePretty (Value -> ByteString) -> (Json -> Value) -> Json -> ByteString
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Json -> Value
getJson (Json -> IO ()) -> Json -> IO ()
forall a b. (a -> b) -> a -> b
$ (HasParsable api, Renderable Json) => Json
forall k (api :: k) a. (HasParsable api, Renderable a) => a
documentWith @api @Json

-- | Convert API type into PlainText format
document :: forall api. HasParsable api => PlainText
document :: PlainText
document = (HasParsable api, Renderable PlainText) => PlainText
forall k (api :: k) a. (HasParsable api, Renderable a) => a
documentWith @api @PlainText

-- | Convert API type into specified formats
documentWith :: forall api a. (HasParsable api, Renderable a) => a
documentWith :: a
documentWith = ApiDocs -> a
forall a. Renderable a => ApiDocs -> a
render @a (HasParsable api => ApiDocs
forall k (api :: k). HasParsable api => ApiDocs
parse @api)