{-|
Module      : HsLua.Packaging.Types
Copyright   : © 2020-2022 Albert Krewinkel
License     : MIT
Maintainer  : Albert Krewinkel <tarleb+hslua@zeitkraut.de>
Stability   : alpha
Portability : Portable

Marshaling and documenting Haskell functions.
-}
module HsLua.Packaging.Types
  ( -- * Documented module
    Module (..)
  , Field (..)
    -- * Documented functions
  , DocumentedFunction (..)
    -- ** Documentation types
  , FunctionDoc (..)
  , ParameterDoc (..)
  , ResultsDoc (..)
  , ResultValueDoc (..)
  ) where

import Data.Text (Text)
import Data.Version (Version)
import HsLua.Core (LuaE, Name, NumResults)
import HsLua.ObjectOrientation (Operation)

-- | Named and documented Lua module.
data Module e = Module
  { Module e -> Name
moduleName :: Name
  , Module e -> Text
moduleDescription :: Text
  , Module e -> [Field e]
moduleFields :: [Field e]
  , Module e -> [DocumentedFunction e]
moduleFunctions :: [DocumentedFunction e]
  , Module e -> [(Operation, DocumentedFunction e)]
moduleOperations :: [(Operation, DocumentedFunction e)]
  }

-- | Self-documenting module field
data Field e = Field
  { Field e -> Text
fieldName :: Text
  , Field e -> Text
fieldDescription :: Text
  , Field e -> LuaE e ()
fieldPushValue :: LuaE e ()
  }

--
-- Function components
--

-- | Haskell equivallent to CFunction, i.e., function callable
-- from Lua.
data DocumentedFunction e = DocumentedFunction
  { DocumentedFunction e -> LuaE e NumResults
callFunction :: LuaE e NumResults
  , DocumentedFunction e -> Name
functionName :: Name
  , DocumentedFunction e -> FunctionDoc
functionDoc  :: FunctionDoc
  }

--
-- Documentation types
--

-- | Documentation for a Haskell function
data FunctionDoc = FunctionDoc
  { FunctionDoc -> Text
functionDescription :: Text
  , FunctionDoc -> [ParameterDoc]
parameterDocs       :: [ParameterDoc]
  , FunctionDoc -> ResultsDoc
functionResultsDocs :: ResultsDoc
  , FunctionDoc -> Maybe Version
functionSince       :: Maybe Version  -- ^ Version in which the function
                                          -- was introduced.
  }
  deriving (FunctionDoc -> FunctionDoc -> Bool
(FunctionDoc -> FunctionDoc -> Bool)
-> (FunctionDoc -> FunctionDoc -> Bool) -> Eq FunctionDoc
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: FunctionDoc -> FunctionDoc -> Bool
$c/= :: FunctionDoc -> FunctionDoc -> Bool
== :: FunctionDoc -> FunctionDoc -> Bool
$c== :: FunctionDoc -> FunctionDoc -> Bool
Eq, Eq FunctionDoc
Eq FunctionDoc
-> (FunctionDoc -> FunctionDoc -> Ordering)
-> (FunctionDoc -> FunctionDoc -> Bool)
-> (FunctionDoc -> FunctionDoc -> Bool)
-> (FunctionDoc -> FunctionDoc -> Bool)
-> (FunctionDoc -> FunctionDoc -> Bool)
-> (FunctionDoc -> FunctionDoc -> FunctionDoc)
-> (FunctionDoc -> FunctionDoc -> FunctionDoc)
-> Ord FunctionDoc
FunctionDoc -> FunctionDoc -> Bool
FunctionDoc -> FunctionDoc -> Ordering
FunctionDoc -> FunctionDoc -> FunctionDoc
forall a.
Eq a
-> (a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
min :: FunctionDoc -> FunctionDoc -> FunctionDoc
$cmin :: FunctionDoc -> FunctionDoc -> FunctionDoc
max :: FunctionDoc -> FunctionDoc -> FunctionDoc
$cmax :: FunctionDoc -> FunctionDoc -> FunctionDoc
>= :: FunctionDoc -> FunctionDoc -> Bool
$c>= :: FunctionDoc -> FunctionDoc -> Bool
> :: FunctionDoc -> FunctionDoc -> Bool
$c> :: FunctionDoc -> FunctionDoc -> Bool
<= :: FunctionDoc -> FunctionDoc -> Bool
$c<= :: FunctionDoc -> FunctionDoc -> Bool
< :: FunctionDoc -> FunctionDoc -> Bool
$c< :: FunctionDoc -> FunctionDoc -> Bool
compare :: FunctionDoc -> FunctionDoc -> Ordering
$ccompare :: FunctionDoc -> FunctionDoc -> Ordering
$cp1Ord :: Eq FunctionDoc
Ord, Int -> FunctionDoc -> ShowS
[FunctionDoc] -> ShowS
FunctionDoc -> String
(Int -> FunctionDoc -> ShowS)
-> (FunctionDoc -> String)
-> ([FunctionDoc] -> ShowS)
-> Show FunctionDoc
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [FunctionDoc] -> ShowS
$cshowList :: [FunctionDoc] -> ShowS
show :: FunctionDoc -> String
$cshow :: FunctionDoc -> String
showsPrec :: Int -> FunctionDoc -> ShowS
$cshowsPrec :: Int -> FunctionDoc -> ShowS
Show)

-- | Documentation for function parameters.
data ParameterDoc = ParameterDoc
  { ParameterDoc -> Text
parameterName :: Text
  , ParameterDoc -> Text
parameterType :: Text
  , ParameterDoc -> Text
parameterDescription :: Text
  , ParameterDoc -> Bool
parameterIsOptional :: Bool
  }
  deriving (ParameterDoc -> ParameterDoc -> Bool
(ParameterDoc -> ParameterDoc -> Bool)
-> (ParameterDoc -> ParameterDoc -> Bool) -> Eq ParameterDoc
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: ParameterDoc -> ParameterDoc -> Bool
$c/= :: ParameterDoc -> ParameterDoc -> Bool
== :: ParameterDoc -> ParameterDoc -> Bool
$c== :: ParameterDoc -> ParameterDoc -> Bool
Eq, Eq ParameterDoc
Eq ParameterDoc
-> (ParameterDoc -> ParameterDoc -> Ordering)
-> (ParameterDoc -> ParameterDoc -> Bool)
-> (ParameterDoc -> ParameterDoc -> Bool)
-> (ParameterDoc -> ParameterDoc -> Bool)
-> (ParameterDoc -> ParameterDoc -> Bool)
-> (ParameterDoc -> ParameterDoc -> ParameterDoc)
-> (ParameterDoc -> ParameterDoc -> ParameterDoc)
-> Ord ParameterDoc
ParameterDoc -> ParameterDoc -> Bool
ParameterDoc -> ParameterDoc -> Ordering
ParameterDoc -> ParameterDoc -> ParameterDoc
forall a.
Eq a
-> (a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
min :: ParameterDoc -> ParameterDoc -> ParameterDoc
$cmin :: ParameterDoc -> ParameterDoc -> ParameterDoc
max :: ParameterDoc -> ParameterDoc -> ParameterDoc
$cmax :: ParameterDoc -> ParameterDoc -> ParameterDoc
>= :: ParameterDoc -> ParameterDoc -> Bool
$c>= :: ParameterDoc -> ParameterDoc -> Bool
> :: ParameterDoc -> ParameterDoc -> Bool
$c> :: ParameterDoc -> ParameterDoc -> Bool
<= :: ParameterDoc -> ParameterDoc -> Bool
$c<= :: ParameterDoc -> ParameterDoc -> Bool
< :: ParameterDoc -> ParameterDoc -> Bool
$c< :: ParameterDoc -> ParameterDoc -> Bool
compare :: ParameterDoc -> ParameterDoc -> Ordering
$ccompare :: ParameterDoc -> ParameterDoc -> Ordering
$cp1Ord :: Eq ParameterDoc
Ord, Int -> ParameterDoc -> ShowS
[ParameterDoc] -> ShowS
ParameterDoc -> String
(Int -> ParameterDoc -> ShowS)
-> (ParameterDoc -> String)
-> ([ParameterDoc] -> ShowS)
-> Show ParameterDoc
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [ParameterDoc] -> ShowS
$cshowList :: [ParameterDoc] -> ShowS
show :: ParameterDoc -> String
$cshow :: ParameterDoc -> String
showsPrec :: Int -> ParameterDoc -> ShowS
$cshowsPrec :: Int -> ParameterDoc -> ShowS
Show)

-- | Documentation for the return values of a function.
data ResultsDoc
  = ResultsDocList [ResultValueDoc]  -- ^ List of individual results
  | ResultsDocMult Text              -- ^ Flexible results
  deriving (ResultsDoc -> ResultsDoc -> Bool
(ResultsDoc -> ResultsDoc -> Bool)
-> (ResultsDoc -> ResultsDoc -> Bool) -> Eq ResultsDoc
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: ResultsDoc -> ResultsDoc -> Bool
$c/= :: ResultsDoc -> ResultsDoc -> Bool
== :: ResultsDoc -> ResultsDoc -> Bool
$c== :: ResultsDoc -> ResultsDoc -> Bool
Eq, Eq ResultsDoc
Eq ResultsDoc
-> (ResultsDoc -> ResultsDoc -> Ordering)
-> (ResultsDoc -> ResultsDoc -> Bool)
-> (ResultsDoc -> ResultsDoc -> Bool)
-> (ResultsDoc -> ResultsDoc -> Bool)
-> (ResultsDoc -> ResultsDoc -> Bool)
-> (ResultsDoc -> ResultsDoc -> ResultsDoc)
-> (ResultsDoc -> ResultsDoc -> ResultsDoc)
-> Ord ResultsDoc
ResultsDoc -> ResultsDoc -> Bool
ResultsDoc -> ResultsDoc -> Ordering
ResultsDoc -> ResultsDoc -> ResultsDoc
forall a.
Eq a
-> (a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
min :: ResultsDoc -> ResultsDoc -> ResultsDoc
$cmin :: ResultsDoc -> ResultsDoc -> ResultsDoc
max :: ResultsDoc -> ResultsDoc -> ResultsDoc
$cmax :: ResultsDoc -> ResultsDoc -> ResultsDoc
>= :: ResultsDoc -> ResultsDoc -> Bool
$c>= :: ResultsDoc -> ResultsDoc -> Bool
> :: ResultsDoc -> ResultsDoc -> Bool
$c> :: ResultsDoc -> ResultsDoc -> Bool
<= :: ResultsDoc -> ResultsDoc -> Bool
$c<= :: ResultsDoc -> ResultsDoc -> Bool
< :: ResultsDoc -> ResultsDoc -> Bool
$c< :: ResultsDoc -> ResultsDoc -> Bool
compare :: ResultsDoc -> ResultsDoc -> Ordering
$ccompare :: ResultsDoc -> ResultsDoc -> Ordering
$cp1Ord :: Eq ResultsDoc
Ord, Int -> ResultsDoc -> ShowS
[ResultsDoc] -> ShowS
ResultsDoc -> String
(Int -> ResultsDoc -> ShowS)
-> (ResultsDoc -> String)
-> ([ResultsDoc] -> ShowS)
-> Show ResultsDoc
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [ResultsDoc] -> ShowS
$cshowList :: [ResultsDoc] -> ShowS
show :: ResultsDoc -> String
$cshow :: ResultsDoc -> String
showsPrec :: Int -> ResultsDoc -> ShowS
$cshowsPrec :: Int -> ResultsDoc -> ShowS
Show)

-- | Documentation for a single return value of a function.
data ResultValueDoc = ResultValueDoc
  { ResultValueDoc -> Text
resultValueType :: Text
  , ResultValueDoc -> Text
resultValueDescription :: Text
  }
  deriving (ResultValueDoc -> ResultValueDoc -> Bool
(ResultValueDoc -> ResultValueDoc -> Bool)
-> (ResultValueDoc -> ResultValueDoc -> Bool) -> Eq ResultValueDoc
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: ResultValueDoc -> ResultValueDoc -> Bool
$c/= :: ResultValueDoc -> ResultValueDoc -> Bool
== :: ResultValueDoc -> ResultValueDoc -> Bool
$c== :: ResultValueDoc -> ResultValueDoc -> Bool
Eq, Eq ResultValueDoc
Eq ResultValueDoc
-> (ResultValueDoc -> ResultValueDoc -> Ordering)
-> (ResultValueDoc -> ResultValueDoc -> Bool)
-> (ResultValueDoc -> ResultValueDoc -> Bool)
-> (ResultValueDoc -> ResultValueDoc -> Bool)
-> (ResultValueDoc -> ResultValueDoc -> Bool)
-> (ResultValueDoc -> ResultValueDoc -> ResultValueDoc)
-> (ResultValueDoc -> ResultValueDoc -> ResultValueDoc)
-> Ord ResultValueDoc
ResultValueDoc -> ResultValueDoc -> Bool
ResultValueDoc -> ResultValueDoc -> Ordering
ResultValueDoc -> ResultValueDoc -> ResultValueDoc
forall a.
Eq a
-> (a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
min :: ResultValueDoc -> ResultValueDoc -> ResultValueDoc
$cmin :: ResultValueDoc -> ResultValueDoc -> ResultValueDoc
max :: ResultValueDoc -> ResultValueDoc -> ResultValueDoc
$cmax :: ResultValueDoc -> ResultValueDoc -> ResultValueDoc
>= :: ResultValueDoc -> ResultValueDoc -> Bool
$c>= :: ResultValueDoc -> ResultValueDoc -> Bool
> :: ResultValueDoc -> ResultValueDoc -> Bool
$c> :: ResultValueDoc -> ResultValueDoc -> Bool
<= :: ResultValueDoc -> ResultValueDoc -> Bool
$c<= :: ResultValueDoc -> ResultValueDoc -> Bool
< :: ResultValueDoc -> ResultValueDoc -> Bool
$c< :: ResultValueDoc -> ResultValueDoc -> Bool
compare :: ResultValueDoc -> ResultValueDoc -> Ordering
$ccompare :: ResultValueDoc -> ResultValueDoc -> Ordering
$cp1Ord :: Eq ResultValueDoc
Ord, Int -> ResultValueDoc -> ShowS
[ResultValueDoc] -> ShowS
ResultValueDoc -> String
(Int -> ResultValueDoc -> ShowS)
-> (ResultValueDoc -> String)
-> ([ResultValueDoc] -> ShowS)
-> Show ResultValueDoc
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [ResultValueDoc] -> ShowS
$cshowList :: [ResultValueDoc] -> ShowS
show :: ResultValueDoc -> String
$cshow :: ResultValueDoc -> String
showsPrec :: Int -> ResultValueDoc -> ShowS
$cshowsPrec :: Int -> ResultValueDoc -> ShowS
Show)