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

-- | Utilities to build Lua modules.
--   
--   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 Lua.
@package hslua-packaging
@version 2.4.1

-- | 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] -> [TypeDoc] -> 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)]

-- | Lua initializers for the types that come with this module. Useful to
--   force full initialization of all metatables.
[moduleTypeInitializers] :: Module e -> [LuaE e Name]

-- | Documentation for the types that are associated with this module.
[moduleTypeDocs] :: Module e -> [TypeDoc]

-- | Self-documenting module field
data Field e
Field :: Name -> FieldDoc -> LuaE e () -> Field e
[fieldName] :: Field e -> Name
[fieldDoc] :: Field e -> FieldDoc
[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

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

-- | Documentation for any of the supported Lua objects.
data DocumentationObject
DocObjectFunction :: FunctionDoc -> DocumentationObject
DocObjectModule :: ModuleDoc -> DocumentationObject
DocObjectType :: TypeDoc -> DocumentationObject

-- | Module documentation
data ModuleDoc
ModuleDoc :: Text -> Text -> [FieldDoc] -> [FunctionDoc] -> [TypeDoc] -> ModuleDoc

-- | module name
[moduleDocName] :: ModuleDoc -> Text

-- | textual module description
[moduleDocDescription] :: ModuleDoc -> Text

-- | module fields
[moduleDocFields] :: ModuleDoc -> [FieldDoc]

-- | module functions
[moduleDocFunctions] :: ModuleDoc -> [FunctionDoc]

-- | module-associated types
[moduleDocTypes] :: ModuleDoc -> [TypeDoc]

-- | Documentation for a Haskell function
data FunctionDoc
FunDoc :: Text -> Text -> [ParameterDoc] -> ResultsDoc -> Maybe Version -> FunctionDoc
[funDocName] :: FunctionDoc -> Text
[funDocDescription] :: FunctionDoc -> Text
[funDocParameters] :: FunctionDoc -> [ParameterDoc]
[funDocResults] :: FunctionDoc -> ResultsDoc

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

-- | Documentation of a data type.
data TypeDoc
TypeDoc :: Text -> Text -> [(Operation, FunctionDoc)] -> [FunctionDoc] -> TypeDoc
[typeDocName] :: TypeDoc -> Text
[typeDocDescription] :: TypeDoc -> Text
[typeDocOperations] :: TypeDoc -> [(Operation, FunctionDoc)]
[typeDocMethods] :: TypeDoc -> [FunctionDoc]

-- | 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

-- | Documentation for a module field.
data FieldDoc
FieldDoc :: Text -> TypeSpec -> Text -> FieldDoc
[fieldDocName] :: FieldDoc -> Text
[fieldDocType] :: FieldDoc -> TypeSpec
[fieldDocDescription] :: FieldDoc -> Text

-- | Named objects
class HasName a
getName :: HasName a => a -> Name
setName :: HasName a => a -> Name -> a

-- | Objects that have descriptions.
class HasDescription a
getDescription :: HasDescription a => a -> Text
setDescription :: HasDescription a => a -> Text -> a
instance GHC.Classes.Eq HsLua.Packaging.Types.DocumentationObject
instance GHC.Classes.Eq HsLua.Packaging.Types.FieldDoc
instance GHC.Classes.Eq HsLua.Packaging.Types.FunctionDoc
instance GHC.Classes.Eq HsLua.Packaging.Types.ModuleDoc
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.Eq HsLua.Packaging.Types.TypeDoc
instance HsLua.Packaging.Types.HasDescription (HsLua.Packaging.Types.Field e)
instance HsLua.Packaging.Types.HasDescription HsLua.Packaging.Types.FieldDoc
instance HsLua.Packaging.Types.HasDescription (HsLua.Packaging.Types.Module e)
instance HsLua.Packaging.Types.HasDescription HsLua.Packaging.Types.ModuleDoc
instance HsLua.Packaging.Types.HasName (HsLua.Packaging.Types.DocumentedFunction e)
instance HsLua.Packaging.Types.HasName (HsLua.Packaging.Types.Field e)
instance HsLua.Packaging.Types.HasName (HsLua.Packaging.Types.Module e)
instance GHC.Classes.Ord HsLua.Packaging.Types.DocumentationObject
instance GHC.Classes.Ord HsLua.Packaging.Types.FieldDoc
instance GHC.Classes.Ord HsLua.Packaging.Types.FunctionDoc
instance GHC.Classes.Ord HsLua.Packaging.Types.ModuleDoc
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.Classes.Ord HsLua.Packaging.Types.TypeDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.DocumentationObject
instance GHC.Internal.Show.Show HsLua.Packaging.Types.FieldDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.FunctionDoc
instance GHC.Internal.Show.Show HsLua.Packaging.Types.ModuleDoc
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
instance GHC.Internal.Show.Show HsLua.Packaging.Types.TypeDoc

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

-- | 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 idx. Pops the documentation of the stack.
registerDocumentation :: LuaError e => StackIndex -> LuaE 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 objects as values.
--   
--   The table is an ephemeron table, i.e., an entry gets garbage collected
--   if the key is no longer reachable.
docsField :: Name

-- | Module documentation
data ModuleDoc
ModuleDoc :: Text -> Text -> [FieldDoc] -> [FunctionDoc] -> [TypeDoc] -> ModuleDoc

-- | module name
[moduleDocName] :: ModuleDoc -> Text

-- | textual module description
[moduleDocDescription] :: ModuleDoc -> Text

-- | module fields
[moduleDocFields] :: ModuleDoc -> [FieldDoc]

-- | module functions
[moduleDocFunctions] :: ModuleDoc -> [FunctionDoc]

-- | module-associated types
[moduleDocTypes] :: ModuleDoc -> [TypeDoc]

-- | Documentation for a Haskell function
data FunctionDoc
FunDoc :: Text -> Text -> [ParameterDoc] -> ResultsDoc -> Maybe Version -> FunctionDoc
[funDocName] :: FunctionDoc -> Text
[funDocDescription] :: FunctionDoc -> Text
[funDocParameters] :: FunctionDoc -> [ParameterDoc]
[funDocResults] :: FunctionDoc -> ResultsDoc

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

-- | Documentation for any of the supported Lua objects.
data DocumentationObject
DocObjectFunction :: FunctionDoc -> DocumentationObject
DocObjectModule :: ModuleDoc -> DocumentationObject
DocObjectType :: TypeDoc -> DocumentationObject

-- | Pushes a DocumentationObject to the Lua stack.
pushDocumentationObject :: LuaError e => Pusher e DocumentationObject

-- | Pushes the metatable for documentation objects.
peekDocumentationObject :: Peeker e DocumentationObject

-- | Pushes the documentation of a module as userdata.
pushModuleDoc :: LuaError e => Pusher e ModuleDoc

-- | Retrieves a module documentation object from the Lua stack.
peekModuleDoc :: Peeker e ModuleDoc

-- | Pushes function documentation as userdata.
pushFunctionDoc :: LuaError e => Pusher e FunctionDoc

-- | Retrieve function documentation from the Lua stack.
peekFunctionDoc :: Peeker e FunctionDoc

-- | Pushes documentation type documentation as userdata.
pushTypeDoc :: LuaError e => Pusher e FunctionDoc

-- | Retrieve function documentation from the Lua stack.
peekTypeDoc :: Peeker e TypeDoc

-- | Generate FunctionDoc documentation for module functions.
generateFunctionDocumentation :: Maybe Name -> DocumentedFunction e -> FunctionDoc

-- | Generate documentation for a module.
generateModuleDocumentation :: Module e -> ModuleDoc

-- | Generate documentation for a UDType.
generateTypeDocumentation :: DocumentedType e a -> TypeDoc

-- | 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 defun, 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 returnResult, but returns only a single result.
returnResult :: HsFnPrecursor e (LuaE e a) -> FunctionResult e a -> DocumentedFunction e

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

-- | Take a HaskellFunction precursor and convert it into a full
--   HaskellFunction, using the given FunctionResults 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 ($), but left associative.
(###) :: (a -> HsFnPrecursor e a) -> a -> HsFnPrecursor e a
infixl 8 ###

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

-- | Inline version of returnResults.
(=#>) :: 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 updateFunctionDescription.
(#?) :: DocumentedFunction e -> Text -> DocumentedFunction e
infixl 8 #?

-- | 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 opt (parameter ...) instead.

-- | Deprecated: Use `opt (parameter ...)` instead.
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 HaskellFunctions.
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)

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

-- | Defines a function parameter of type Bool.
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 String.
stringParam :: Text -> Text -> Parameter e String

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

-- | Defines a function result of type Bool.
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 Text.
stringResult :: Text -> FunctionResults e String

-- | Defines a function result of type Text.
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, and to their type as 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

-- | Declares a new read- and writable property.
property :: LuaError e => Name -> Text -> (Pusher e b, a -> b) -> (Peeker e b, a -> b -> a) -> Member e fn a

-- | Declares a new read- and writable typed property.
property' :: LuaError e => Name -> TypeSpec -> Text -> (Pusher e b, a -> b) -> (Peeker e b, a -> b -> a) -> Member e fn a

-- | Declares a new read- and writable property which is not always
--   available.
possibleProperty :: LuaError e => Name -> Text -> (Pusher e b, a -> Possible b) -> (Peeker e b, a -> b -> Possible a) -> Member e fn a

-- | Declares a new read- and writable property which is not always
--   available.
possibleProperty' :: LuaError e => Name -> TypeSpec -> Text -> (Pusher e b, a -> Possible b) -> (Peeker e b, a -> b -> Possible a) -> Member e fn a

-- | Creates a read-only object property. Attempts to set the value will
--   cause an error.
readonly :: Name -> Text -> (Pusher e b, a -> b) -> Member e fn a

-- | Creates a read-only object property. Attempts to set the value will
--   cause an error.
readonly' :: Name -> TypeSpec -> Text -> (Pusher e b, a -> b) -> Member e fn a

-- | Define an alias for another, possibly nested, property.
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 ()

-- | Ensures that the type has been fully initialized, i.e., that all
--   metatables have been created and stored in the registry. Returns the
--   name of the initialized type.
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

-- | Type specifier for a UDType
udTypeSpec :: UDTypeGeneric e fn a -> TypeSpec

-- | A type member, either a method or a variable.
data Member e fn a

-- | Lua metadata operation types.
data Operation

-- | the addition (+) operation. If any operand for an addition is
--   not a number (nor a string coercible to a number), Lua will try to
--   call a metamethod. First, Lua will check the first operand (even if it
--   is valid). If that operand does not define a metamethod for
--   __add, then Lua will check the second operand. If Lua can
--   find a metamethod, it calls the metamethod with the two operands as
--   arguments, and the result of the call (adjusted to one value) is the
--   result of the operation. Otherwise, it raises an error.
Add :: Operation

-- | the subtraction (-) operation. Behavior similar to the
--   addition operation.
Sub :: Operation

-- | the multiplication (*) operation. Behavior similar to the
--   addition operation.
Mul :: Operation

-- | the division (/) operation. Behavior similar to the addition
--   operation.
Div :: Operation

-- | the modulo (%) operation. Behavior similar to the addition
--   operation.
Mod :: Operation

-- | the exponentiation (^) operation. Behavior similar to the
--   addition operation.
Pow :: Operation

-- | the negation (unary -) operation. Behavior similar to the
--   addition operation.
Unm :: Operation

-- | the floor division (//) operation. Behavior similar to the
--   addition operation.
Idiv :: Operation

-- | the bitwise AND (&) operation. Behavior similar to the
--   addition operation, except that Lua will try a metamethod if any
--   operand is neither an integer nor a value coercible to an integer (see
--   §3.4.3).
Band :: Operation

-- | the bitwise OR (|) operation. Behavior similar to the bitwise
--   AND operation.
Bor :: Operation

-- | the bitwise exclusive OR (binary ~) operation. Behavior
--   similar to the bitwise AND operation.
Bxor :: Operation

-- | the bitwise NOT (unary ~) operation. Behavior similar to the
--   bitwise AND operation.
Bnot :: Operation

-- | the bitwise left shift (<<) operation. Behavior similar
--   to the bitwise AND operation.
Shl :: Operation

-- | the bitwise right shift (>>) operation. Behavior
--   similar to the bitwise AND operation.
Shr :: Operation

-- | the concatenation (..) operation. Behavior similar to the
--   addition operation, except that Lua will try a metamethod if any
--   operand is neither a string nor a number (which is always coercible to
--   a string).
Concat :: Operation

-- | the length (#) operation. If the object is not a string, Lua
--   will try its metamethod. If there is a metamethod, Lua calls it with
--   the object as argument, and the result of the call (always adjusted to
--   one value) is the result of the operation. If there is no metamethod
--   but the object is a table, then Lua uses the table length operation
--   (see §3.4.7). Otherwise, Lua raises an error.
Len :: Operation

-- | the equal (==) operation. Behavior similar to the addition
--   operation, except that Lua will try a metamethod only when the values
--   being compared are either both tables or both full userdata and they
--   are not primitively equal. The result of the call is always converted
--   to a boolean.
Eq :: Operation

-- | the less than (<) operation. Behavior similar to the
--   addition operation, except that Lua will try a metamethod only when
--   the values being compared are neither both numbers nor both strings.
--   The result of the call is always converted to a boolean.
Lt :: Operation

-- | the less equal (<=) operation. Unlike other operations,
--   the less-equal operation can use two different events. First, Lua
--   looks for the __le metamethod in both operands, like in the
--   less than operation. If it cannot find such a metamethod, then it will
--   try the __lt metamethod, assuming that a <= b is
--   equivalent to not (b < a). As with the other comparison operators,
--   the result is always a boolean. (This use of the __lt event
--   can be removed in future versions; it is also slower than a real __le
--   metamethod.)
Le :: Operation

-- | The indexing access operation table[key]. This event happens
--   when table is not a table or when key is not present in table. The
--   metamethod is looked up in table.
Index :: Operation

-- | The indexing assignment table[key] = value. Like the index
--   event, this event happens when table is not a table or when key is not
--   present in table. The metamethod is looked up in table.
Newindex :: Operation

-- | The call operation func(args). This event happens when Lua
--   tries to call a non-function value (that is, func is not a function).
--   The metamethod is looked up in func. If present, the metamethod is
--   called with func as its first argument, followed by the arguments of
--   the original call (args). All results of the call are the result of
--   the operation. (This is the only metamethod that allows multiple
--   results.)
Call :: Operation

-- | The operation used to create a string representation of the object.
Tostring :: Operation

-- | the operation of iterating over the object's key-value pairs.
Pairs :: Operation

-- | a custom operation, with the metamethod name as parameter.
CustomOperation :: Name -> Operation

-- | A read- and writable property on a UD object.
data Property e a

-- | A property or method which may be available in some instances but not
--   in others.
data Possible a
Actual :: a -> Possible a
Absent :: Possible a

-- | 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] -> [TypeDoc] -> 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)]

-- | Lua initializers for the types that come with this module. Useful to
--   force full initialization of all metatables.
[moduleTypeInitializers] :: Module e -> [LuaE e Name]

-- | Documentation for the types that are associated with this module.
[moduleTypeDocs] :: Module e -> [TypeDoc]

-- | Module documentation
data ModuleDoc
ModuleDoc :: Text -> Text -> [FieldDoc] -> [FunctionDoc] -> [TypeDoc] -> ModuleDoc

-- | module name
[moduleDocName] :: ModuleDoc -> Text

-- | textual module description
[moduleDocDescription] :: ModuleDoc -> Text

-- | module fields
[moduleDocFields] :: ModuleDoc -> [FieldDoc]

-- | module functions
[moduleDocFunctions] :: ModuleDoc -> [FunctionDoc]

-- | module-associated types
[moduleDocTypes] :: ModuleDoc -> [TypeDoc]

-- | Self-documenting module field
data Field e
Field :: Name -> FieldDoc -> LuaE e () -> Field e
[fieldName] :: Field e -> Name
[fieldDoc] :: Field e -> FieldDoc
[fieldPushValue] :: Field e -> LuaE e ()

-- | Define a Lua module.
defmodule :: Name -> Module e

-- | Set the list of module fields.
withFields :: Module e -> [Field e] -> Module e
infixl 0 `withFields`

-- | Set the list of functions in the module.
withFunctions :: Module e -> [DocumentedFunction e] -> Module e
infixl 0 `withFunctions`

-- | Set operations that can be performed on the module object.
withOperations :: Module e -> [(Operation, DocumentedFunction e)] -> Module e
infixl 0 `withOperations`

-- | Associate a type with this module. An associated type is listed in the
--   module documentation.
associateType :: LuaError e => Module e -> DocumentedType e a -> Module e
infixl 0 `associateType`

-- | Gives a different name
renameTo :: HasName a => a -> Name -> a

-- | Create a new module field.
deffield :: Name -> Field e

-- | Set a specific type for a field.
withType :: Field e -> TypeSpec -> Field e
infixl 0 `withType`

-- | Sets a textual description
withDescription :: HasDescription a => a -> Text -> a
infixl 0 `withDescription`

-- | Add a value pusher to a field.
withValue :: Field e -> LuaE e () -> Field e
infixl 0 `withValue`

-- | Named objects
class HasName a
getName :: HasName a => a -> Name
setName :: HasName a => a -> Name -> a

-- | Objects that have descriptions.
class HasDescription a
getDescription :: HasDescription a => a -> Text
setDescription :: HasDescription a => a -> Text -> a

-- | Registers a Module; 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 ()

-- | Lua metadata operation types.
data Operation

-- | the addition (+) operation. If any operand for an addition is
--   not a number (nor a string coercible to a number), Lua will try to
--   call a metamethod. First, Lua will check the first operand (even if it
--   is valid). If that operand does not define a metamethod for
--   __add, then Lua will check the second operand. If Lua can
--   find a metamethod, it calls the metamethod with the two operands as
--   arguments, and the result of the call (adjusted to one value) is the
--   result of the operation. Otherwise, it raises an error.
Add :: Operation

-- | the subtraction (-) operation. Behavior similar to the
--   addition operation.
Sub :: Operation

-- | the multiplication (*) operation. Behavior similar to the
--   addition operation.
Mul :: Operation

-- | the division (/) operation. Behavior similar to the addition
--   operation.
Div :: Operation

-- | the modulo (%) operation. Behavior similar to the addition
--   operation.
Mod :: Operation

-- | the exponentiation (^) operation. Behavior similar to the
--   addition operation.
Pow :: Operation

-- | the negation (unary -) operation. Behavior similar to the
--   addition operation.
Unm :: Operation

-- | the floor division (//) operation. Behavior similar to the
--   addition operation.
Idiv :: Operation

-- | the bitwise AND (&) operation. Behavior similar to the
--   addition operation, except that Lua will try a metamethod if any
--   operand is neither an integer nor a value coercible to an integer (see
--   §3.4.3).
Band :: Operation

-- | the bitwise OR (|) operation. Behavior similar to the bitwise
--   AND operation.
Bor :: Operation

-- | the bitwise exclusive OR (binary ~) operation. Behavior
--   similar to the bitwise AND operation.
Bxor :: Operation

-- | the bitwise NOT (unary ~) operation. Behavior similar to the
--   bitwise AND operation.
Bnot :: Operation

-- | the bitwise left shift (<<) operation. Behavior similar
--   to the bitwise AND operation.
Shl :: Operation

-- | the bitwise right shift (>>) operation. Behavior
--   similar to the bitwise AND operation.
Shr :: Operation

-- | the concatenation (..) operation. Behavior similar to the
--   addition operation, except that Lua will try a metamethod if any
--   operand is neither a string nor a number (which is always coercible to
--   a string).
Concat :: Operation

-- | the length (#) operation. If the object is not a string, Lua
--   will try its metamethod. If there is a metamethod, Lua calls it with
--   the object as argument, and the result of the call (always adjusted to
--   one value) is the result of the operation. If there is no metamethod
--   but the object is a table, then Lua uses the table length operation
--   (see §3.4.7). Otherwise, Lua raises an error.
Len :: Operation

-- | the equal (==) operation. Behavior similar to the addition
--   operation, except that Lua will try a metamethod only when the values
--   being compared are either both tables or both full userdata and they
--   are not primitively equal. The result of the call is always converted
--   to a boolean.
Eq :: Operation

-- | the less than (<) operation. Behavior similar to the
--   addition operation, except that Lua will try a metamethod only when
--   the values being compared are neither both numbers nor both strings.
--   The result of the call is always converted to a boolean.
Lt :: Operation

-- | the less equal (<=) operation. Unlike other operations,
--   the less-equal operation can use two different events. First, Lua
--   looks for the __le metamethod in both operands, like in the
--   less than operation. If it cannot find such a metamethod, then it will
--   try the __lt metamethod, assuming that a <= b is
--   equivalent to not (b < a). As with the other comparison operators,
--   the result is always a boolean. (This use of the __lt event
--   can be removed in future versions; it is also slower than a real __le
--   metamethod.)
Le :: Operation

-- | The indexing access operation table[key]. This event happens
--   when table is not a table or when key is not present in table. The
--   metamethod is looked up in table.
Index :: Operation

-- | The indexing assignment table[key] = value. Like the index
--   event, this event happens when table is not a table or when key is not
--   present in table. The metamethod is looked up in table.
Newindex :: Operation

-- | The call operation func(args). This event happens when Lua
--   tries to call a non-function value (that is, func is not a function).
--   The metamethod is looked up in func. If present, the metamethod is
--   called with func as its first argument, followed by the arguments of
--   the original call (args). All results of the call are the result of
--   the operation. (This is the only metamethod that allows multiple
--   results.)
Call :: Operation

-- | The operation used to create a string representation of the object.
Tostring :: Operation

-- | the operation of iterating over the object's key-value pairs.
Pairs :: Operation

-- | a custom operation, with the metamethod name as parameter.
CustomOperation :: Name -> Operation

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