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

-- | Object orientation tools for HsLua
--   
--   Expose Haskell objects to Lua with an object oriented interface.
@package hslua-objectorientation
@version 2.5.0

-- | Binary and unary object operations.
module HsLua.ObjectOrientation.Operation

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

-- | Returns the metamethod name used to control this operation.
metamethodName :: Operation -> Name
instance GHC.Classes.Eq HsLua.ObjectOrientation.Operation.Operation
instance GHC.Classes.Ord HsLua.ObjectOrientation.Operation.Operation
instance GHC.Internal.Show.Show HsLua.ObjectOrientation.Operation.Operation

-- | 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.ObjectOrientation.Generic

-- | 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.
--   
--   This type includes methods to define how the object should behave as a
--   read-only list of type itemtype.
data UDTypeGeneric e fn a
UDType :: Name -> [(Operation, fn)] -> Map Name (Property e a) -> Map Name fn -> Map AliasIndex Alias -> UDTypeHooks e fn a -> (fn -> LuaE e ()) -> UDTypeGeneric e fn a
[udName] :: UDTypeGeneric e fn a -> Name
[udOperations] :: UDTypeGeneric e fn a -> [(Operation, fn)]
[udProperties] :: UDTypeGeneric e fn a -> Map Name (Property e a)
[udMethods] :: UDTypeGeneric e fn a -> Map Name fn
[udAliases] :: UDTypeGeneric e fn a -> Map AliasIndex Alias
[udHooks] :: UDTypeGeneric e fn a -> UDTypeHooks e fn a
[udFnPusher] :: UDTypeGeneric e fn a -> fn -> LuaE e ()

-- | Defines a new "Lua type" and sets the behavior of the Lua object
--   instances. It's possible to pass custom type extensions, which modify
--   the default object behavior. Furthermore, the function pusher
--   parameter controls how functions are marshaled to Lua.
--   
--   Note that the type name must be unique.
deftypeGeneric' :: Pusher e fn -> Name -> [(Operation, fn)] -> [Member e fn a] -> UDTypeHooks e fn a -> UDTypeGeneric e fn a

-- | Use a documented function as an object method.
methodGeneric :: Name -> fn -> Member e fn 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

-- | Extensions for userdata types.
data UDTypeHooks e fn a
UDTypeHooks :: Int -> LuaE e () -> (a -> StackIndex -> Peek e a) -> (a -> LuaE e ()) -> UDTypeHooks e fn a

-- | Number of uservalues required for this extension, *including* the
--   uservalue for the default caching table.
[hookUservalues] :: UDTypeHooks e fn a -> Int

-- | Run after the metatable has been set up; the new metatable is at the
--   top of the stack when this hook is run.
[hookMetatableSetup] :: UDTypeHooks e fn a -> LuaE e ()

-- | Peek extra data and modify the peeked object
[hookPeekUD] :: UDTypeHooks e fn a -> a -> StackIndex -> Peek e a

-- | Push extra data
[hookPushUD] :: UDTypeHooks e fn a -> a -> LuaE e ()

-- | No extension.
emptyHooks :: UDTypeHooks e fn a

-- | Retrieves a userdata value of the given type.
peekUDGeneric :: LuaError e => UDTypeGeneric e fn a -> Peeker e a

-- | Pushes a userdata value of the given type.
pushUDGeneric :: LuaError e => UDTypeGeneric e fn a -> 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

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

-- | A read- and writable property on a UD object.
data Property e a
Property :: (a -> LuaE e NumResults) -> Maybe (StackIndex -> a -> LuaE e a) -> Text -> TypeSpec -> Property e a
[propertyGet] :: Property e a -> a -> LuaE e NumResults
[propertySet] :: Property e a -> Maybe (StackIndex -> a -> LuaE e a)
[propertyDescription] :: Property e a -> Text
[propertyType] :: Property e a -> TypeSpec

-- | 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 property or method which may be available in some instances but not
--   in others.
data Possible a
Actual :: a -> Possible a
Absent :: Possible a

-- | Alias for a different property of this or of a nested object.
type Alias = [AliasIndex]

-- | Index types allowed in aliases (strings and integers)
data AliasIndex
StringIndex :: Name -> AliasIndex
IntegerIndex :: Integer -> AliasIndex
instance GHC.Classes.Eq HsLua.ObjectOrientation.Generic.AliasIndex
instance GHC.Internal.Data.String.IsString HsLua.ObjectOrientation.Generic.AliasIndex
instance GHC.Classes.Ord HsLua.ObjectOrientation.Generic.AliasIndex

module HsLua.ObjectOrientation.ListType

-- | Userdata type that (also) behaves like a list.

-- | Deprecated: Use UDTypeGeneric instead
type UDTypeWithList e fn a itemtype = UDTypeGeneric e fn a

-- | Pair of pairs, describing how a type can be used as a Lua list. The
--   first pair describes how to push the list items, and how the list is
--   extracted from the type; the second pair contains a method to retrieve
--   list items, and defines how the list is used to create an updated
--   value.
type ListSpec e a itemtype = ((Pusher e itemtype, a -> [itemtype]), (Peeker e itemtype, a -> [itemtype] -> a))
listExtension :: LuaError e => ListSpec e a itemtype -> UDTypeHooks e fn a

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

-- | 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 UDType e fn a = UDTypeGeneric e fn a

-- | Defines a new type, defining the behavior of objects in Lua. Note that
--   the type name must be unique.
deftypeGeneric :: Pusher e fn -> Name -> [(Operation, fn)] -> [Member e fn a] -> UDType e fn a
