HsLua.Packaging.Function

Marshaling and documenting Haskell functions.

Documentation

data DocumentedFunction e

Haskell equivallent to CFunction, i.e., function callable from Lua.

Constructors

DocumentedFunction

Fields

• callFunction :: LuaE e NumResults
• functionName :: Name
• functionDoc :: FunctionDoc

Creating documented functions

defun :: Name -> a -> HsFnPrecursor e a

Begin wrapping a monadic Lua function such that it can be turned into a documented function exposable to Lua.

lambda :: a -> HsFnPrecursor e a

Just like defun, but uses an empty name for the documented function. Should be used when defining methods or operators.

applyParameter :: HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b

Partially apply a parameter.

returnResult :: HsFnPrecursor e (LuaE e a) -> FunctionResult e a -> DocumentedFunction e

Like returnResult, but returns only a single result.

returnResultsOnStack :: HsFnPrecursor e (LuaE e NumResults) -> Text -> DocumentedFunction e

Take a HaskellFunction precursor and convert it into a full HaskellFunction, using the given FunctionResults to return the result to Lua.

liftPure :: (a -> b) -> a -> LuaE e b

Turns a pure function into a monadic Lua function.

The resulting function is strict.

liftPure2 :: (a -> b -> c) -> a -> b -> LuaE e c

Turns a binary function into a Lua function.

The resulting function is strict in both its arguments.

liftPure3 :: (a -> b -> c -> d) -> a -> b -> c -> LuaE e d

Turns a ternary 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 quarternary 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

Turns a quinary function into a Lua function.

The resulting function is strict in all of its arguments.

Types

data Parameter e a

Function parameter.

Constructors

Parameter

Fields

• parameterPeeker :: Peeker e a
• parameterDoc :: ParameterDoc

data FunctionResult e a

Result of a call to a Haskell function.

Constructors

FunctionResult

Fields

• fnResultPusher :: Pusher e a
• fnResultDoc :: ResultValueDoc

type FunctionResults e a = [FunctionResult e a]

List of function results in the order in which they are returned in Lua.

Operators

(###) :: (a -> HsFnPrecursor e a) -> a -> HsFnPrecursor e a infixl 8

Like ($), but left associative.

(<#>) :: HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b infixl 8

Inline version of applyParameter.

(=#>) :: HsFnPrecursor e (LuaE e a) -> FunctionResults e a -> DocumentedFunction e infixl 8

Inline version of returnResults.

(=?>) :: HsFnPrecursor e (LuaE e NumResults) -> Text -> DocumentedFunction e infixl 8

Return a flexible number of results that have been pushed by the function action.

(#?) :: DocumentedFunction e -> Text -> DocumentedFunction e infixl 8

Inline version of updateFunctionDescription.

Modifying functions

setName :: Name -> DocumentedFunction e -> DocumentedFunction e

Renames a documented function.

since :: DocumentedFunction e -> Version -> DocumentedFunction e infixl 8

Sets the library version at which the function was introduced in its current form.

Pushing to Lua

pushDocumentedFunction :: LuaError e => DocumentedFunction e -> LuaE e ()

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.

Accessing documentation in Lua

docsField :: Name

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.

pushDocumentation :: LuaError e => StackIndex -> LuaE e NumResults

Pushes the documentation of the object at the given index to the stack, or just *nil* if no documentation is available.

Convenience functions

parameter

Arguments

:: Peeker e a

method to retrieve value from Lua

-> Text

expected Lua type

-> Text

parameter name

-> Text

parameter description

-> Parameter e a

Creates a parameter.

optionalParameter

Arguments

:: Peeker e a

method to retrieve the value from Lua

-> Text

expected Lua type

-> Text

parameter name

-> Text

parameter description

-> Parameter e (Maybe a)

Creates an optional parameter.

functionResult

Arguments

:: Pusher e a

method to push the Haskell result to Lua

-> Text

Lua type of result

-> Text

result description

-> FunctionResults e a

Creates a function result.

Internal

toHsFnPrecursor :: StackIndex -> Name -> a -> HsFnPrecursor e a

Create a HaskellFunction precursor from a monadic function, selecting the stack index after which the first function parameter will be placed.