packages feed

duckdb-simple-1.0.0.0: src/Database/DuckDB/Simple/V2/FunctionDocs.hs

{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE NamedFieldPuns #-}

-- |
-- Module      : Database.DuckDB.Simple.V2.FunctionDocs
-- Description : Documentation attached to scalar, aggregate, table, macro, and pragma functions.
--
-- The examples use the imports of the module header of "Database.DuckDB.Simple.V2.Registration".
module Database.DuckDB.Simple.V2.FunctionDocs (
  FunctionDocs (..),
  defaultFunctionDocs,
  setFunctionDocs,
) where

import Control.Monad (forM_)
import Data.Text (Text)
import Database.DuckDB.Simple.Native

-- | A description, titled SQL examples, and category names.
-- Each example is a pair of a title and the SQL text:
--
-- > Docs.FunctionDocs (Just "Preserve the input type.") [("Example", "SELECT managed_resolved(42)")] ["test"]
data FunctionDocs = FunctionDocs
  { functionDescription :: Maybe Text
  , functionExamples :: [(Text, Text)]
  , functionCategories :: [Text]
  }
  deriving (Eq, Show, Read)

-- | Leave the description unset and add no examples or categories.
defaultFunctionDocs :: FunctionDocs
defaultFunctionDocs = FunctionDocs Nothing [] []

-- | Apply documentation to a borrowed native documentation handle.
-- Get the handle from the function builder in its configuration action.
-- The action replaces the description when present and appends examples and categories.
-- DuckDB copies all text before the action returns.
-- For example, in the configuration action of
-- 'Database.DuckDB.Simple.V2.Registration.registerScalarFunctionWith':
--
-- > docs <- R.output (c_duckdb_v2_scalar_function_get_docs function)
-- > Docs.setFunctionDocs docs Docs.defaultFunctionDocs{Docs.functionDescription = Just "Add two BIGINT values."}
setFunctionDocs :: DuckDBV2FunctionDocsHandle -> FunctionDocs -> IO ()
setFunctionDocs docs FunctionDocs{functionDescription, functionExamples, functionCategories} = do
  forM_ functionDescription \description ->
    withText description (checked . c_duckdb_v2_function_docs_set_description docs)
  forM_ functionExamples \(title, sql) ->
    withText title \nativeTitle ->
      withText sql \nativeSQL -> checked (c_duckdb_v2_function_docs_add_example docs nativeTitle nativeSQL)
  forM_ functionCategories \category ->
    withText category (checked . c_duckdb_v2_function_docs_add_category docs)