hslua-core-2.3.2: Bindings to Lua, an embeddable scripting language

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

HsLua.Core.Error

Contents

- Helpers for hslua C wrapper functions.
- Orphan instances

Description

Lua exceptions and exception handling.

Synopsis

- newtype Exception = Exception {
  - exceptionMessage :: String
  }
- class Exception e => LuaError e where
  - popException :: LuaE e e
  - pushException :: e -> LuaE e ()
  - luaException :: String -> e
- type Lua a = LuaE Exception a
- try :: Exception e => LuaE e a -> LuaE e (Either e a)
- failLua :: LuaError e => String -> LuaE e a
- throwErrorAsException :: LuaError e => LuaE e a
- throwTypeMismatchError :: LuaError e => ByteString -> StackIndex -> LuaE e a
- changeErrorType :: forall old new a. LuaE old a -> LuaE new a
- liftLuaThrow :: LuaError e => (State -> Ptr StatusCode -> IO a) -> LuaE e a
- popErrorMessage :: State -> IO ByteString
- pushTypeMismatchError :: ByteString -> StackIndex -> LuaE e ()

# Documentation

newtype Exception #

Default Lua error type. Exceptions raised by Lua-related operations.

Constructors

Exception |
Fields exceptionMessage :: String

#### Instances

Instances details

Exception Exception # |
Instance details Defined in HsLua.Core.Error Methods toException :: Exception -> SomeException # fromException :: SomeException -> Maybe Exception # displayException :: Exception -> String # backtraceDesired :: Exception -> Bool #
Show Exception # |
Instance details Defined in HsLua.Core.Error Methods showsPrec :: Int -> Exception -> ShowS # show :: Exception -> String # showList :: [Exception] -> ShowS #
Eq Exception # |
Instance details Defined in HsLua.Core.Error Methods (==) :: Exception -> Exception -> Bool # (/=) :: Exception -> Exception -> Bool #
LuaError Exception # |
Instance details Defined in HsLua.Core.Error Methods popException :: LuaE Exception Exception # pushException :: Exception -> LuaE Exception () # luaException :: String -> Exception #

class Exception e => LuaError e where #

Any type that you wish to use for error handling in HsLua must be an instance of the `LuaError` class.

Methods

popException :: LuaE e e #

Converts the error at the top of the stack into an exception and pops the error off the stack.

This function is expected to produce a valid result for any Lua value; neither a Haskell exception nor a Lua error may result when this is called.

pushException :: e -> LuaE e () #

Pushes an exception to the top of the Lua stack. The pushed Lua object is used as an error object, and it is recommended that calling `tostring()` on the object produces an informative message.

luaException :: String -> e #

Creates a new exception with the given message.

#### Instances

Instances details

LuaError Exception # |
Instance details Defined in HsLua.Core.Error Methods popException :: LuaE Exception Exception # pushException :: Exception -> LuaE Exception () # luaException :: String -> Exception #

type Lua a = LuaE Exception a #

A Lua operation.

This type is suitable for most users. It uses a default exception for error handling. Users who need more control over error handling can use `LuaE` with a custom error type instead.

try :: Exception e => LuaE e a -> LuaE e (Either e a) #

Return either the result of a Lua computation or, if an exception was thrown, the error.

failLua :: LuaError e => String -> LuaE e a #

Raises an exception in the Lua monad.

throwErrorAsException :: LuaError e => LuaE e a #

Converts a Lua error at the top of the stack into a Haskell exception and throws it.

throwTypeMismatchError :: LuaError e => ByteString -> StackIndex -> LuaE e a #

Raises an exception that's appropriate when the type of a Lua object at the given index did not match the expected type. The name or description of the expected type is taken as an argument.

changeErrorType :: forall old new a. LuaE old a -> LuaE new a #

Change the error type of a computation.

# Helpers for hslua C wrapper functions.

liftLuaThrow :: LuaError e => (State -> Ptr StatusCode -> IO a) -> LuaE e a #

Takes a failable HsLua function and transforms it into a monadic `LuaE` operation. Throws an exception if an error occured.

popErrorMessage :: State -> IO ByteString #

Retrieve and pop the top object as an error message. This is very similar to tostring', but ensures that we don't recurse if getting the message failed.

This helpful as a "last resort" method when implementing `popException`.

pushTypeMismatchError #

Arguments

:: ByteString | name or description of expected type
-> StackIndex | stack index of mismatching object
-> LuaE e () |

Creates an error to notify about a Lua type mismatch and pushes it to the stack.

# Orphan instances

LuaError e => Alternative (LuaE e) # |
Instance details Methods empty :: LuaE e a # (<|>) :: LuaE e a -> LuaE e a -> LuaE e a # some :: LuaE e a -> LuaE e [a] # many :: LuaE e a -> LuaE e [a] #
LuaError e => MonadFail (LuaE e) # |
Instance details Methods fail :: String -> LuaE e a #