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


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

-- | Lua metadata operation types.
data Operation

-- | the addition (<tt>+</tt>) 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
--   <tt>__add</tt>, 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 (<tt>-</tt>) operation. Behavior similar to the
--   addition operation.
Sub :: Operation

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

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

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

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

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

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

-- | the bitwise AND (<tt>&amp;</tt>) 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 (<tt>|</tt>) operation. Behavior similar to the bitwise
--   AND operation.
Bor :: Operation

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

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

-- | the bitwise left shift (<tt>&lt;&lt;</tt>) operation. Behavior similar
--   to the bitwise AND operation.
Shl :: Operation

-- | the bitwise right shift (<tt>&gt;&gt;</tt>) operation. Behavior
--   similar to the bitwise AND operation.
Shr :: Operation

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

-- | The indexing access operation <tt>table[key]</tt>. 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 <tt>table[key] = value</tt>. 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 <tt>func(args)</tt>. 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.Show.Show HsLua.ObjectOrientation.Operation.Operation
instance GHC.Classes.Ord HsLua.ObjectOrientation.Operation.Operation
instance GHC.Classes.Eq 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<i>, and to their type as </i>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 = UDTypeWithList e fn a Void

-- | 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 <tt>itemtype</tt>.
data UDTypeWithList e fn a itemtype
UDTypeWithList :: Name -> [(Operation, fn)] -> Map Name (Property e a) -> Map Name fn -> Map AliasIndex Alias -> Maybe (ListSpec e a itemtype) -> (fn -> LuaE e ()) -> UDTypeWithList e fn a itemtype
[udName] :: UDTypeWithList e fn a itemtype -> Name
[udOperations] :: UDTypeWithList e fn a itemtype -> [(Operation, fn)]
[udProperties] :: UDTypeWithList e fn a itemtype -> Map Name (Property e a)
[udMethods] :: UDTypeWithList e fn a itemtype -> Map Name fn
[udAliases] :: UDTypeWithList e fn a itemtype -> Map AliasIndex Alias
[udListSpec] :: UDTypeWithList e fn a itemtype -> Maybe (ListSpec e a itemtype)
[udFnPusher] :: UDTypeWithList e fn a itemtype -> fn -> LuaE e ()

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

-- | 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.
deftypeGeneric' :: Pusher e fn -> Name -> [(Operation, fn)] -> [Member e fn a] -> Maybe (ListSpec e a itemtype) -> UDTypeWithList e fn a itemtype

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

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

-- | Define an alias for another, possibly nested, property.
alias :: AliasIndex -> Text -> [AliasIndex] -> Member e fn a

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

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

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

-- | Lua metadata operation types.
data Operation

-- | the addition (<tt>+</tt>) 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
--   <tt>__add</tt>, 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 (<tt>-</tt>) operation. Behavior similar to the
--   addition operation.
Sub :: Operation

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

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

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

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

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

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

-- | the bitwise AND (<tt>&amp;</tt>) 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 (<tt>|</tt>) operation. Behavior similar to the bitwise
--   AND operation.
Bor :: Operation

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

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

-- | the bitwise left shift (<tt>&lt;&lt;</tt>) operation. Behavior similar
--   to the bitwise AND operation.
Shl :: Operation

-- | the bitwise right shift (<tt>&gt;&gt;</tt>) operation. Behavior
--   similar to the bitwise AND operation.
Shr :: Operation

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

-- | The indexing access operation <tt>table[key]</tt>. 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 <tt>table[key] = value</tt>. 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 <tt>func(args)</tt>. 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

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

-- | 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.Ord HsLua.ObjectOrientation.AliasIndex
instance GHC.Classes.Eq HsLua.ObjectOrientation.AliasIndex
instance Data.String.IsString HsLua.ObjectOrientation.AliasIndex