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

This module provides types and functions to use Haskell values as
userdata objects in Lua. These objects wrap a Haskell value and provide
methods and properties to interact with the Haskell value.

The terminology in this module refers to the userdata values as /UD
objects/, and to their type as /UD type/.
-}
module HsLua.Packaging.UDType
  ( DocumentedType
  , DocumentedTypeWithList
  , deftype
  , deftype'
  , method
  , property
  , possibleProperty
  , readonly
  , alias
  , operation
  , peekUD
  , pushUD
  , udparam
  , udresult
    -- * Helper types for building
  , Member
  , Operation (..)
  , Property
  , Possible (..)
  ) where

import Data.Text (Text)
import HsLua.Core
import HsLua.ObjectOrientation
import HsLua.ObjectOrientation.Operation (metamethodName)
import HsLua.Packaging.Function
import qualified HsLua.Core.Utf8 as Utf8

-- | Type definitions containing documented functions.
type DocumentedType e a = UDType e (DocumentedFunction e) a

-- | A userdata type, capturing the behavior of Lua objects that wrap
-- Haskell values. The type name must be unique; once the type has been
-- used to push or retrieve a value, the behavior can no longer be
-- modified through this type.
type DocumentedTypeWithList e a itemtype =
  UDTypeWithList e (DocumentedFunction e) a itemtype

-- | Defines a new type, defining the behavior of objects in Lua.
-- Note that the type name must be unique.
deftype :: LuaError e
        => Name                                 -- ^ type name
        -> [(Operation, DocumentedFunction e)]  -- ^ operations
        -> [Member e (DocumentedFunction e) a]  -- ^ methods
        -> DocumentedType e a
deftype :: Name
-> [(Operation, DocumentedFunction e)]
-> [Member e (DocumentedFunction e) a]
-> DocumentedType e a
deftype = Pusher e (DocumentedFunction e)
-> Name
-> [(Operation, DocumentedFunction e)]
-> [Member e (DocumentedFunction e) a]
-> DocumentedType e a
forall e fn a.
Pusher e fn
-> Name -> [(Operation, fn)] -> [Member e fn a] -> UDType e fn a
deftypeGeneric Pusher e (DocumentedFunction e)
forall e. LuaError e => DocumentedFunction e -> LuaE e ()
pushDocumentedFunction

-- | Defines a new type that could also be treated as a list; defines
-- the behavior of objects in Lua. Note that the type name must be
-- unique.
deftype' :: LuaError e
         => Name                                 -- ^ type name
         -> [(Operation, DocumentedFunction e)]  -- ^ operations
         -> [Member e (DocumentedFunction e) a]  -- ^ methods
         -> Maybe (ListSpec e a itemtype)  -- ^ list access
         -> DocumentedTypeWithList e a itemtype
deftype' :: Name
-> [(Operation, DocumentedFunction e)]
-> [Member e (DocumentedFunction e) a]
-> Maybe (ListSpec e a itemtype)
-> DocumentedTypeWithList e a itemtype
deftype' = Pusher e (DocumentedFunction e)
-> Name
-> [(Operation, DocumentedFunction e)]
-> [Member e (DocumentedFunction e) a]
-> Maybe (ListSpec e a itemtype)
-> DocumentedTypeWithList e a itemtype
forall e fn a itemtype.
Pusher e fn
-> Name
-> [(Operation, fn)]
-> [Member e fn a]
-> Maybe (ListSpec e a itemtype)
-> UDTypeWithList e fn a itemtype
deftypeGeneric' Pusher e (DocumentedFunction e)
forall e. LuaError e => DocumentedFunction e -> LuaE e ()
pushDocumentedFunction

-- | Use a documented function as an object method.
method :: DocumentedFunction e
       -> Member e (DocumentedFunction e) a
method :: DocumentedFunction e -> Member e (DocumentedFunction e) a
method DocumentedFunction e
f = Name -> DocumentedFunction e -> Member e (DocumentedFunction e) a
forall fn e a. Name -> fn -> Member e fn a
methodGeneric (DocumentedFunction e -> Name
forall e. DocumentedFunction e -> Name
functionName DocumentedFunction e
f) DocumentedFunction e
f

-- | Declares a new object operation from a documented function.
operation :: Operation             -- ^ the kind of operation
          -> DocumentedFunction e  -- ^ function used to perform the operation
          -> (Operation, DocumentedFunction e)
operation :: Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
op DocumentedFunction e
f = (,) Operation
op (DocumentedFunction e -> (Operation, DocumentedFunction e))
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
forall a b. (a -> b) -> a -> b
$ Name -> DocumentedFunction e -> DocumentedFunction e
forall e. Name -> DocumentedFunction e -> DocumentedFunction e
setName (Operation -> Name
metamethodName Operation
op) DocumentedFunction e
f

-- | Defines a function parameter that takes the given type.
udparam :: LuaError e
        => DocumentedTypeWithList e a itemtype  -- ^ expected type
        -> Text            -- ^ parameter name
        -> Text            -- ^ parameter description
        -> Parameter e a
udparam :: DocumentedTypeWithList e a itemtype
-> Text -> Text -> Parameter e a
udparam DocumentedTypeWithList e a itemtype
ty = Peeker e a -> Text -> Text -> Text -> Parameter e a
forall e a. Peeker e a -> Text -> Text -> Text -> Parameter e a
parameter (DocumentedTypeWithList e a itemtype -> Peeker e a
forall e fn a itemtype.
LuaError e =>
UDTypeWithList e fn a itemtype -> Peeker e a
peekUD DocumentedTypeWithList e a itemtype
ty) (ByteString -> Text
Utf8.toText (ByteString -> Text) -> (Name -> ByteString) -> Name -> Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Name -> ByteString
fromName (Name -> Text) -> Name -> Text
forall a b. (a -> b) -> a -> b
$ DocumentedTypeWithList e a itemtype -> Name
forall e fn a itemtype. UDTypeWithList e fn a itemtype -> Name
udName DocumentedTypeWithList e a itemtype
ty)

-- | Defines a function result of the given type.
udresult :: LuaError e
         => DocumentedTypeWithList e a itemtype -- ^ result type
         -> Text           -- ^ result description
         -> FunctionResults e a
udresult :: DocumentedTypeWithList e a itemtype -> Text -> FunctionResults e a
udresult DocumentedTypeWithList e a itemtype
ty = Pusher e a -> Text -> Text -> FunctionResults e a
forall e a. Pusher e a -> Text -> Text -> FunctionResults e a
functionResult (DocumentedTypeWithList e a itemtype -> Pusher e a
forall e fn a itemtype.
LuaError e =>
UDTypeWithList e fn a itemtype -> a -> LuaE e ()
pushUD DocumentedTypeWithList e a itemtype
ty) (ByteString -> Text
Utf8.toText (ByteString -> Text) -> (Name -> ByteString) -> Name -> Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Name -> ByteString
fromName (Name -> Text) -> Name -> Text
forall a b. (a -> b) -> a -> b
$ DocumentedTypeWithList e a itemtype -> Name
forall e fn a itemtype. UDTypeWithList e fn a itemtype -> Name
udName DocumentedTypeWithList e a itemtype
ty)