Copyright	© 2021-2024 Albert Krewinkel
License	MIT
Maintainer	Albert Krewinkel <tarleb@hslua.org>
Safe Haskell	None
Language	Haskell2010

HsLua.ObjectOrientation.Generic

Contents

Defining types
Marshaling
Type docs
Helper types for building

Description

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

Synopsis

data UDTypeGeneric e fn a = UDType {
- udName :: Name
- udOperations :: [(Operation, fn)]
- udProperties :: Map Name (Property e a)
- udMethods :: Map Name fn
- udAliases :: Map AliasIndex Alias
- udHooks :: UDTypeHooks e fn a
- udFnPusher :: fn -> LuaE e ()
}
deftypeGeneric' :: Pusher e fn -> Name -> [(Operation, fn)] -> [Member e fn a] -> UDTypeHooks e fn a -> UDTypeGeneric e fn a
methodGeneric :: Name -> fn -> Member e fn 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
data UDTypeHooks e fn a = UDTypeHooks {
- hookUservalues :: Int
- hookMetatableSetup :: LuaE e ()
- hookPeekUD :: a -> StackIndex -> Peek e a
- hookPushUD :: a -> LuaE e ()
}
emptyHooks :: UDTypeHooks e fn a
peekUDGeneric :: LuaError e => UDTypeGeneric e fn a -> Peeker e a
pushUDGeneric :: LuaError e => UDTypeGeneric e fn a -> a -> LuaE e ()
initType :: LuaError e => UDTypeGeneric e fn a -> LuaE e Name
udDocs :: UDTypeGeneric e fn a -> TypeDocs
udTypeSpec :: UDTypeGeneric e fn a -> TypeSpec
data Member e fn a
data Property e a = Property {
- propertyGet :: a -> LuaE e NumResults
- propertySet :: Maybe (StackIndex -> a -> LuaE e a)
- propertyDescription :: Text
- propertyType :: TypeSpec
}
data Operation
- = Add
- | Sub
- | Mul
- | Div
- | Mod
- | Pow
- | Unm
- | Idiv
- | Band
- | Bor
- | Bxor
- | Bnot
- | Shl
- | Shr
- | Concat
- | Len
- | Eq
- | Lt
- | Le
- | Index
- | Newindex
- | Call
- | Tostring
- | Pairs
- | CustomOperation Name
data Possible a
- = Actual a
- | Absent
type Alias = [AliasIndex]
data AliasIndex
- = StringIndex Name
- | IntegerIndex Integer

Documentation

data UDTypeGeneric e fn a Source #

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.

Constructors

UDType
Fields udName :: Name udOperations :: [(Operation, fn)] udProperties :: Map Name (Property e a) udMethods :: Map Name fn udAliases :: Map AliasIndex Alias udHooks :: UDTypeHooks e fn a udFnPusher :: fn -> LuaE e ()

Defining types

deftypeGeneric' Source #

Arguments

:: Pusher e fn	function pusher
-> Name	type name
-> [(Operation, fn)]	operations
-> [Member e fn a]	methods
-> UDTypeHooks e fn a	behavior modifying hooks
-> UDTypeGeneric e fn a

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.

Methods

methodGeneric :: Name -> fn -> Member e fn a Source #

Use a documented function as an object method.

Properties

property Source #

Arguments

:: LuaError e
=> Name	property name
-> Text	property description
-> (Pusher e b, a -> b)	how to get the property value
-> (Peeker e b, a -> b -> a)	how to set a new property value
-> Member e fn a

Declares a new read- and writable property.

property' Source #

Arguments

:: LuaError e
=> Name	property name
-> TypeSpec	property type
-> Text	property description
-> (Pusher e b, a -> b)	how to get the property value
-> (Peeker e b, a -> b -> a)	how to set a new property value
-> Member e fn a

Declares a new read- and writable typed property.

possibleProperty Source #

Arguments

:: LuaError e
=> Name	property name
-> Text	property description
-> (Pusher e b, a -> Possible b)	how to get the property value
-> (Peeker e b, a -> b -> Possible a)	how to set a new property value
-> Member e fn a

Declares a new read- and writable property which is not always available.

possibleProperty' Source #

Arguments

:: LuaError e
=> Name	property name
-> TypeSpec	type of the property value
-> Text	property description
-> (Pusher e b, a -> Possible b)	how to get the property value
-> (Peeker e b, a -> b -> Possible a)	how to set a new property value
-> Member e fn a

Declares a new read- and writable property which is not always available.

readonly Source #

Arguments

:: Name	property name
-> Text	property description
-> (Pusher e b, a -> b)	how to get the property value
-> Member e fn a

Creates a read-only object property. Attempts to set the value will cause an error.

readonly' Source #

Arguments

:: Name	property name
-> TypeSpec	property type
-> Text	property description
-> (Pusher e b, a -> b)	how to get the property value
-> Member e fn a

Creates a read-only object property. Attempts to set the value will cause an error.

Aliases

alias Source #

Arguments

:: AliasIndex	property alias
-> Text	description
-> [AliasIndex]	sequence of nested properties
-> Member e fn a

Define an alias for another, possibly nested, property.

Type extension

data UDTypeHooks e fn a Source #

Extensions for userdata types.

Constructors

UDTypeHooks

Fields

hookUservalues :: Int
Number of uservalues required for this extension, *including* the uservalue for the default caching table.
hookMetatableSetup :: LuaE e ()
Run after the metatable has been set up; the new metatable is at the top of the stack when this hook is run.
hookPeekUD :: a -> StackIndex -> Peek e a
Peek extra data and modify the peeked object
hookPushUD :: a -> LuaE e ()
Push extra data

emptyHooks :: UDTypeHooks e fn a Source #

No extension.

Marshaling

peekUDGeneric :: LuaError e => UDTypeGeneric e fn a -> Peeker e a Source #

Retrieves a userdata value of the given type.

pushUDGeneric Source #

Arguments

:: LuaError e
=> UDTypeGeneric e fn a	userdata type
-> a	value to push
-> LuaE e ()

Pushes a userdata value of the given type.

initType :: LuaError e => UDTypeGeneric e fn a -> LuaE e Name Source #

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.

Type docs

udDocs :: UDTypeGeneric e fn a -> TypeDocs Source #

Returns documentation for this type.

udTypeSpec :: UDTypeGeneric e fn a -> TypeSpec Source #

Type specifier for a UDType

Helper types for building

data Member e fn a Source #

A type member, either a method or a variable.

data Property e a Source #

A read- and writable property on a UD object.

Constructors

Property
Fields propertyGet :: a -> LuaE e NumResults propertySet :: Maybe (StackIndex -> a -> LuaE e a) propertyDescription :: Text propertyType :: TypeSpec

data Operation Source #

Lua metadata operation types.

Constructors

Add	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.
Sub	the subtraction (`-`) operation. Behavior similar to the addition operation.
Mul	the multiplication (`*`) operation. Behavior similar to the addition operation.
Div	the division (`/`) operation. Behavior similar to the addition operation.
Mod	the modulo (`%`) operation. Behavior similar to the addition operation.
Pow	the exponentiation (`^`) operation. Behavior similar to the addition operation.
Unm	the negation (unary `-`) operation. Behavior similar to the addition operation.
Idiv	the floor division (`//`) operation. Behavior similar to the addition operation.
Band	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).
Bor	the bitwise OR (`\|`) operation. Behavior similar to the bitwise AND operation.
Bxor	the bitwise exclusive OR (binary `~`) operation. Behavior similar to the bitwise AND operation.
Bnot	the bitwise NOT (unary `~`) operation. Behavior similar to the bitwise AND operation.
Shl	the bitwise left shift (`<<`) operation. Behavior similar to the bitwise AND operation.
Shr	the bitwise right shift (`>>`) operation. Behavior similar to the bitwise AND operation.
Concat	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).
Len	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.
Eq	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.
Lt	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.
Le	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.)
Index	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.
Newindex	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.
Call	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.)
Tostring	The operation used to create a string representation of the object.
Pairs	the operation of iterating over the object's key-value pairs.
CustomOperation Name	a custom operation, with the metamethod name as parameter.

Instances

Instances details

Show Operation Source #
Instance details Defined in HsLua.ObjectOrientation.Operation Methods showsPrec :: Int -> Operation -> ShowS show :: Operation -> String showList :: [Operation] -> ShowS
Eq Operation Source #
Instance details Defined in HsLua.ObjectOrientation.Operation Methods (==) :: Operation -> Operation -> Bool (/=) :: Operation -> Operation -> Bool
Ord Operation Source #
Instance details Defined in HsLua.ObjectOrientation.Operation Methods compare :: Operation -> Operation -> Ordering (<) :: Operation -> Operation -> Bool (<=) :: Operation -> Operation -> Bool (>) :: Operation -> Operation -> Bool (>=) :: Operation -> Operation -> Bool max :: Operation -> Operation -> Operation min :: Operation -> Operation -> Operation

data Possible a Source #

A property or method which may be available in some instances but not in others.

Constructors

Actual a
Absent

type Alias = [AliasIndex] Source #

Alias for a different property of this or of a nested object.

data AliasIndex Source #

Index types allowed in aliases (strings and integers)

Constructors

StringIndex Name
IntegerIndex Integer

Instances

Instances details

IsString AliasIndex Source #
Instance details Defined in HsLua.ObjectOrientation.Generic Methods fromString :: String -> AliasIndex
Eq AliasIndex Source #
Instance details Defined in HsLua.ObjectOrientation.Generic Methods (==) :: AliasIndex -> AliasIndex -> Bool (/=) :: AliasIndex -> AliasIndex -> Bool
Ord AliasIndex Source #
Instance details Defined in HsLua.ObjectOrientation.Generic Methods compare :: AliasIndex -> AliasIndex -> Ordering (<) :: AliasIndex -> AliasIndex -> Bool (<=) :: AliasIndex -> AliasIndex -> Bool (>) :: AliasIndex -> AliasIndex -> Bool (>=) :: AliasIndex -> AliasIndex -> Bool max :: AliasIndex -> AliasIndex -> AliasIndex min :: AliasIndex -> AliasIndex -> AliasIndex