-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Utilities to package up Haskell functions and values into a Lua
--   module.
--   
--   This package is part of HsLua, a Haskell framework built around the
--   embeddable scripting language <a>Lua</a>.
@package hslua-packaging
@version 2.3.2


-- | Marshaling and documenting Haskell functions.
module HsLua.Packaging.Types

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

-- | Self-documenting module field
data Field e
Field :: Text -> TypeSpec -> Text -> LuaE e () -> Field e
[fieldName] :: Field e -> Text
[fieldType] :: Field e -> TypeSpec
[fieldDescription] :: Field e -> Text
[fieldPushValue] :: Field e -> LuaE e ()

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

-- | Documentation for a Haskell function
data FunctionDoc
FunctionDoc :: Text -> [ParameterDoc] -> ResultsDoc -> Maybe Version -> FunctionDoc
[functionDescription] :: FunctionDoc -> Text
[parameterDocs] :: FunctionDoc -> [ParameterDoc]
[functionResultsDocs] :: FunctionDoc -> ResultsDoc

-- | Version in which the function was introduced.
[functionSince] :: FunctionDoc -> Maybe Version

-- | Documentation for function parameters.
data ParameterDoc
ParameterDoc :: Text -> TypeSpec -> Text -> Bool -> ParameterDoc
[parameterName] :: ParameterDoc -> Text
[parameterType] :: ParameterDoc -> TypeSpec
[parameterDescription] :: ParameterDoc -> Text
[parameterIsOptional] :: ParameterDoc -> Bool

-- | Documentation for the return values of a function.
data ResultsDoc

-- | List of individual results
ResultsDocList :: [ResultValueDoc] -> ResultsDoc

-- | Flexible results
ResultsDocMult :: Text -> ResultsDoc

-- | Documentation for a single return value of a function.
data ResultValueDoc
ResultValueDoc :: TypeSpec -> Text -> ResultValueDoc
[resultValueType] :: ResultValueDoc -> TypeSpec
[resultValueDescription] :: ResultValueDoc -> Text
instance GHC.Classes.Eq HsLua.Packaging.Types.FunctionDoc
instance GHC.Classes.Eq HsLua.Packaging.Types.ParameterDoc
instance GHC.Classes.Eq HsLua.Packaging.Types.ResultValueDoc
instance GHC.Classes.Eq HsLua.Packaging.Types.ResultsDoc
instance GHC.Classes.Ord HsLua.Packaging.Types.FunctionDoc
instance GHC.Classes.Ord HsLua.Packaging.Types.ParameterDoc
instance GHC.Classes.Ord HsLua.Packaging.Types.ResultValueDoc
instance GHC.Classes.Ord HsLua.Packaging.Types.ResultsDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.FunctionDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.ParameterDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.ResultValueDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.ResultsDoc


-- | Render function and module documentation.

-- | <i>Deprecated: Use getdocumentation with a custom renderer.</i>
module HsLua.Packaging.Rendering

-- | Alias for <a>renderModule</a>.
render :: Module e -> Text

-- | Renders module documentation as Markdown.
renderModule :: Module e -> Text

-- | Renders documentation of a function.
renderFunction :: DocumentedFunction e -> Text


-- | Provides a function to print documentation if available.
module HsLua.Packaging.Documentation

-- | Function that retrieves documentation.
documentation :: LuaError e => DocumentedFunction e

-- | Pushes the documentation for the element at the given stack index.
--   Returns the type of the documentation object.
getdocumentation :: LuaError e => StackIndex -> LuaE e Type

-- | Registers the object at the top of the stack as documentation for the
--   object at index <tt>idx</tt>. Pops the documentation of the stack.
registerDocumentation :: LuaError e => StackIndex -> LuaE e ()

-- | Pushes the documentation of a module as a table with string fields
--   <tt>name</tt> and <tt>description</tt>.
pushModuleDoc :: LuaError e => Pusher e (Module e)

-- | Pushes the documentation of a function as a table with string fields,
--   <tt>name</tt>, <tt>description</tt>, and <tt>since</tt>, sequence
--   field <tt>parameters</tt>, and sequence or string field
--   <tt>results</tt>.
pushFunctionDoc :: LuaError e => Pusher e (DocumentedFunction e)

-- | Pushes the documentation of a field as a table with string fields
--   <tt>name</tt> and <tt>description</tt>.
pushFieldDoc :: LuaError e => Pusher e (Field e)

-- | Name of the registry field holding the documentation table. The
--   documentation table is indexed by the documented objects, like module
--   tables and functions, and contains documentation strings as values.
--   
--   The table is an ephemeron table, i.e., an entry gets garbage collected
--   if the key is no longer reachable.
docsField :: Name


-- | Marshaling and documenting Haskell functions.
module HsLua.Packaging.Function

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

-- | Begin wrapping a monadic Lua function such that it can be turned into
--   a documented function exposable to Lua.
defun :: Name -> a -> HsFnPrecursor e a

-- | Just like <tt>defun</tt>, but uses an empty name for the documented
--   function. Should be used when defining methods or operators.
lambda :: a -> HsFnPrecursor e a

-- | Partially apply a parameter.
applyParameter :: HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b

-- | Like <tt><a>returnResult</a></tt>, but returns only a single result.
returnResult :: HsFnPrecursor e (LuaE e a) -> FunctionResult e a -> DocumentedFunction e

-- | Take a <a>HaskellFunction</a> precursor and convert it into a full
--   <a>HaskellFunction</a>, using the given <a>FunctionResult</a>s to
--   return the result to Lua.
returnResults :: HsFnPrecursor e (LuaE e a) -> FunctionResults e a -> DocumentedFunction e

-- | Take a <a>HaskellFunction</a> precursor and convert it into a full
--   <a>HaskellFunction</a>, using the given <a>FunctionResult</a>s to
--   return the result to Lua.
returnResultsOnStack :: HsFnPrecursor e (LuaE e NumResults) -> Text -> DocumentedFunction e

-- | Updates the description of a Haskell function. Leaves the function
--   unchanged if it has no documentation.
updateFunctionDescription :: DocumentedFunction e -> Text -> DocumentedFunction e

-- | Turns a pure function into a monadic Lua function.
--   
--   The resulting function is strict.
liftPure :: (a -> b) -> a -> LuaE e b

-- | Turns a binary function into a Lua function.
--   
--   The resulting function is strict in both its arguments.
liftPure2 :: (a -> b -> c) -> a -> b -> LuaE e c

-- | Turns a ternary function into a Lua function.
--   
--   The resulting function is strict in all of its arguments.
liftPure3 :: (a -> b -> c -> d) -> a -> b -> c -> LuaE e d

-- | Turns a quarternary function into a Lua function.
--   
--   The resulting function is strict in all of its arguments.
liftPure4 :: (a -> b -> c -> d -> e) -> a -> b -> c -> d -> LuaE err e

-- | Turns a quinary function into a Lua function.
--   
--   The resulting function is strict in all of its arguments.
liftPure5 :: (a -> b -> c -> d -> e -> f) -> a -> b -> c -> d -> e -> LuaE err f

-- | Function parameter.
data Parameter e a
Parameter :: Peeker e a -> ParameterDoc -> Parameter e a
[parameterPeeker] :: Parameter e a -> Peeker e a
[parameterDoc] :: Parameter e a -> ParameterDoc

-- | Result of a call to a Haskell function.
data FunctionResult e a
FunctionResult :: Pusher e a -> ResultValueDoc -> FunctionResult e a
[fnResultPusher] :: FunctionResult e a -> Pusher e a
[fnResultDoc] :: FunctionResult e a -> ResultValueDoc

-- | List of function results in the order in which they are returned in
--   Lua.
type FunctionResults e a = [FunctionResult e a]

-- | Like <a>($)</a>, but left associative.
(###) :: (a -> HsFnPrecursor e a) -> a -> HsFnPrecursor e a
infixl 8 ###

-- | Inline version of <tt><a>applyParameter</a></tt>.
(<#>) :: HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
infixl 8 <#>

-- | Inline version of <tt><a>returnResults</a></tt>.
(=#>) :: HsFnPrecursor e (LuaE e a) -> FunctionResults e a -> DocumentedFunction e
infixl 8 =#>

-- | Return a flexible number of results that have been pushed by the
--   function action.
(=?>) :: HsFnPrecursor e (LuaE e NumResults) -> Text -> DocumentedFunction e
infixl 8 =?>

-- | Inline version of <tt><a>updateFunctionDescription</a></tt>.
(#?) :: DocumentedFunction e -> Text -> DocumentedFunction e
infixl 8 #?

-- | Renames a documented function.
setName :: Name -> DocumentedFunction e -> DocumentedFunction e

-- | Sets the library version at which the function was introduced in its
--   current form.
since :: DocumentedFunction e -> Version -> DocumentedFunction e
infixl 8 `since`

-- | Pushes a documented Haskell function to the Lua stack, making it
--   usable as a normal function in Lua. At the same time, the function
--   docs are registered in the documentation table.
pushDocumentedFunction :: LuaError e => DocumentedFunction e -> LuaE e ()

-- | Creates a parameter.
parameter :: Peeker e a -> TypeSpec -> Text -> Text -> Parameter e a

-- | Makes a parameter optional.
opt :: Parameter e a -> Parameter e (Maybe a)

-- | Creates an optional parameter.
--   
--   DEPRECATED: Use <tt>opt (parameter ...)</tt> instead.

-- | <i>Deprecated: Use `opt (parameter ...)` instead.</i>
optionalParameter :: Peeker e a -> TypeSpec -> Text -> Text -> Parameter e (Maybe a)

-- | Creates a function result.
functionResult :: Pusher e a -> TypeSpec -> Text -> FunctionResults e a

-- | Helper type used to create <a>HaskellFunction</a>s.
data HsFnPrecursor e a

-- | Create a HaskellFunction precursor from a monadic function, selecting
--   the stack index after which the first function parameter will be
--   placed.
toHsFnPrecursor :: StackIndex -> Name -> a -> HsFnPrecursor e a
instance GHC.Internal.Base.Functor (HsLua.Packaging.Function.HsFnPrecursor e)


-- | Utility functions for HsLua modules.
module HsLua.Packaging.Module

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

-- | Self-documenting module field
data Field e
Field :: Text -> TypeSpec -> Text -> LuaE e () -> Field e
[fieldName] :: Field e -> Text
[fieldType] :: Field e -> TypeSpec
[fieldDescription] :: Field e -> Text
[fieldPushValue] :: Field e -> LuaE e ()

-- | Registers a <a>Module</a>; leaves a copy of the module table on the
--   stack.
registerModule :: LuaError e => Module e -> LuaE e ()

-- | Preload self-documenting module using the module's default name.
preloadModule :: LuaError e => Module e -> LuaE e ()

-- | Add the module under a different name to the table of preloaded
--   packages.
preloadModuleWithName :: LuaError e => Module e -> Name -> LuaE e ()

-- | Pushes a documented module to the Lua stack.
pushModule :: LuaError e => Module e -> LuaE e ()
data Operation
Add :: Operation
Sub :: Operation
Mul :: Operation
Div :: Operation
Mod :: Operation
Pow :: Operation
Unm :: Operation
Idiv :: Operation
Band :: Operation
Bor :: Operation
Bxor :: Operation
Bnot :: Operation
Shl :: Operation
Shr :: Operation
Concat :: Operation
Len :: Operation
Eq :: Operation
Lt :: Operation
Le :: Operation
Index :: Operation
Newindex :: Operation
Call :: Operation
Tostring :: Operation
Pairs :: Operation
CustomOperation :: Name -> Operation


-- | Convenience functions for common parameter and result types.
module HsLua.Packaging.Convenience

-- | Defines a function parameter of type <a>Bool</a>.
boolParam :: Text -> Text -> Parameter e Bool

-- | Defines a function parameter for an integral type.
integralParam :: (Read a, Integral a) => Text -> Text -> Parameter e a

-- | Defines a function parameter of type <a>String</a>.
stringParam :: Text -> Text -> Parameter e String

-- | Defines a function parameter of type <a>Text</a>.
textParam :: Text -> Text -> Parameter e Text

-- | Defines a function result of type <a>Bool</a>.
boolResult :: Text -> FunctionResults e Bool

-- | Defines a function result for an integral type.
integralResult :: (Integral a, Show a) => Text -> FunctionResults e a

-- | Defines a function result of type <a>Text</a>.
stringResult :: Text -> FunctionResults e String

-- | Defines a function result of type <a>Text</a>.
textResult :: Text -> FunctionResults e Text


-- | 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<i>, and to their type as </i>UD type/.
module HsLua.Packaging.UDType

-- | 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 -> [(Operation, DocumentedFunction e)] -> [Member e (DocumentedFunction e) a] -> DocumentedType e a

-- | 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 -> [(Operation, DocumentedFunction e)] -> [Member e (DocumentedFunction e) a] -> Maybe (ListSpec e a itemtype) -> DocumentedTypeWithList e a itemtype

-- | Use a documented function as an object method.
method :: DocumentedFunction e -> Member e (DocumentedFunction e) a
property :: LuaError e => Name -> Text -> (Pusher e b, a -> b) -> (Peeker e b, a -> b -> a) -> Member e fn a
property' :: LuaError e => Name -> TypeSpec -> Text -> (Pusher e b, a -> b) -> (Peeker e b, a -> b -> a) -> Member e fn a
possibleProperty :: LuaError e => Name -> Text -> (Pusher e b, a -> Possible b) -> (Peeker e b, a -> b -> Possible a) -> Member e fn a
possibleProperty' :: LuaError e => Name -> TypeSpec -> Text -> (Pusher e b, a -> Possible b) -> (Peeker e b, a -> b -> Possible a) -> Member e fn a
readonly :: Name -> Text -> (Pusher e b, a -> b) -> Member e fn a
readonly' :: Name -> TypeSpec -> Text -> (Pusher e b, a -> b) -> Member e fn a
alias :: AliasIndex -> Text -> [AliasIndex] -> Member e fn a

-- | Declares a new object operation from a documented function.
operation :: Operation -> DocumentedFunction e -> (Operation, DocumentedFunction e)

-- | Retrieves a userdata value of the given type.
peekUD :: LuaError e => DocumentedTypeWithList e a itemtype -> Peeker e a

-- | Pushes a userdata value of the given type.
pushUD :: LuaError e => DocumentedTypeWithList e a itemtype -> a -> LuaE e ()
initType :: LuaError e => UDTypeGeneric e fn a -> LuaE e Name

-- | Defines a function parameter that takes the given type.
udparam :: LuaError e => DocumentedTypeWithList e a itemtype -> Text -> Text -> Parameter e a

-- | Defines a function result of the given type.
udresult :: LuaError e => DocumentedTypeWithList e a itemtype -> Text -> FunctionResults e a
udDocs :: UDTypeGeneric e fn a -> TypeDocs
udTypeSpec :: UDTypeGeneric e fn a -> TypeSpec
data Member e fn a
data Operation
Add :: Operation
Sub :: Operation
Mul :: Operation
Div :: Operation
Mod :: Operation
Pow :: Operation
Unm :: Operation
Idiv :: Operation
Band :: Operation
Bor :: Operation
Bxor :: Operation
Bnot :: Operation
Shl :: Operation
Shr :: Operation
Concat :: Operation
Len :: Operation
Eq :: Operation
Lt :: Operation
Le :: Operation
Index :: Operation
Newindex :: Operation
Call :: Operation
Tostring :: Operation
Pairs :: Operation
CustomOperation :: Name -> Operation
data Property e a
data Possible a
Actual :: a -> Possible a
Absent :: Possible a


-- | Tools to create documented Lua functions and modules.
module HsLua.Packaging
