{-|
Module      : HsLua.Packaging.Types
Copyright   : © 2020-2023 Albert Krewinkel
License     : MIT
Maintainer  : Albert Krewinkel <tarleb@hslua.org>
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)
import HsLua.Typing (TypeSpec)

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

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

--
-- Function components
--

-- | Haskell equivallent to CFunction, i.e., function callable
-- from Lua.
data DocumentedFunction e = DocumentedFunction
  { forall e. DocumentedFunction e -> LuaE e NumResults
callFunction :: LuaE e NumResults
  , forall e. DocumentedFunction e -> Name
functionName :: Name
  , forall e. 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
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
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
Ord, Int -> FunctionDoc -> ShowS
[FunctionDoc] -> ShowS
FunctionDoc -> String
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 -> TypeSpec
parameterType :: TypeSpec
  , ParameterDoc -> Text
parameterDescription :: Text
  , ParameterDoc -> Bool
parameterIsOptional :: Bool
  }
  deriving (ParameterDoc -> ParameterDoc -> Bool
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
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
Ord, Int -> ParameterDoc -> ShowS
[ParameterDoc] -> ShowS
ParameterDoc -> String
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
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
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
Ord, Int -> ResultsDoc -> ShowS
[ResultsDoc] -> ShowS
ResultsDoc -> String
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 -> TypeSpec
resultValueType :: TypeSpec
  , ResultValueDoc -> Text
resultValueDescription :: Text
  }
  deriving (ResultValueDoc -> ResultValueDoc -> Bool
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
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
Ord, Int -> ResultValueDoc -> ShowS
[ResultValueDoc] -> ShowS
ResultValueDoc -> String
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)