lua-2.1.0: Lua, an embeddable scripting language

Copyright | © 2007–2012 Gracjan Polak; © 2012–2016 Ömer Sinan Ağacan; © 2017-2022 Albert Krewinkel
License | MIT
Maintainer | Albert Krewinkel <tarleb+hslua@zeitkraut.de>
Stability | beta
Portability | non-portable (depends on GHC)
Safe Haskell | None
Language | Haskell2010

Lua.Auxiliary

Contents

- The Auxiliary Library
  - Registry fields
  - References

Description

Raw bindings to functions and constants of the auxiliary library.

Synopsis

- luaL_getmetafield :: State -> StackIndex -> CString -> IO TypeCode
- luaL_getmetatable :: State -> CString -> IO TypeCode
- luaL_loadbuffer :: State -> Ptr CChar -> CSize -> CString -> IO StatusCode
- luaL_loadfile :: State -> Ptr CChar -> IO StatusCode
- luaL_loadfilex :: State -> Ptr CChar -> Ptr CChar -> IO StatusCode
- luaL_openlibs :: State -> IO ()
- luaL_newmetatable :: State -> CString -> IO LuaBool
- luaL_ref :: State -> StackIndex -> IO CInt
- luaL_testudata :: State -> StackIndex -> CString -> IO (Ptr ())
- luaL_traceback :: State -> State -> CString -> CInt -> IO ()
- luaL_unref :: State -> StackIndex -> CInt -> IO ()
- luaL_where :: State -> CInt -> IO ()
- loadedTableRegistryField :: String
- preloadTableRegistryField :: String
- data Reference
  - = Reference CInt
  - | RefNil
- fromReference :: Reference -> CInt
- toReference :: CInt -> Reference

# The Auxiliary Library

luaL_getmetafield #

Arguments

:: State |
-> StackIndex | obj
-> CString | e
-> IO TypeCode |

Pushes onto the stack the field `e` from the metatable of the object at index `obj` and returns the type of the pushed value. If the object does not have a metatable, or if the metatable does not have this field, pushes nothing and returns ``LUA_TNIL``.

luaL_getmetatable :: State -> CString -> IO TypeCode #

Pushes onto the stack the metatable associated with name tname in the registry (see ``luaL_newmetatable``) (nil if there is no metatable associated with that name). Returns the type of the pushed value.

luaL_loadbuffer #

Arguments

:: State |
-> Ptr CChar | buff
-> CSize | sz
-> CString | name
-> IO StatusCode |

Loads a buffer as a Lua chunk. This function uses `lua_load` to load the chunk in the buffer pointed to by `buff` with size `sz`.

This function returns the same results as `lua_load`. `name` is the chunk name, used for debug information and error messages.

luaL_loadfile #

Arguments

:: State |
-> Ptr CChar | filename
-> IO StatusCode |

Equivalent to luaL_loadfilex with mode equal to `NULL`.

luaL_loadfilex #

Arguments

:: State |
-> Ptr CChar | filename
-> Ptr CChar | mode
-> IO StatusCode |

Loads a file as a Lua chunk. This function uses `lua_load` to load the chunk in the file named filename. If filename is `NULL`, then it loads from the standard input. The first line in the file is ignored if it starts with a `#`.

The string mode works as in function `lua_load`.

This function returns the same results as `lua_load`, but it has an extra error code LUA_ERRFILE for file-related errors (e.g., it cannot open or read the file).

As `lua_load`, this function only loads the chunk; it does not run it.

luaL_openlibs :: State -> IO () #

Opens all standard Lua libraries into the given state.

https://www.lua.org/manual/5.3/manual.html#luaL_openlibs

luaL_newmetatable #

Arguments

:: State |
-> CString | tname
-> IO LuaBool |

If the registry already has the key `tname`, returns `0`. Otherwise, creates a new table to be used as a metatable for userdata, adds to this new table the pair `__name = tname`, adds to the registry the pair `[tname] = new table`, and returns `1`. (The entry `__name` is used by some error-reporting functions.)

In both cases pushes onto the stack the final value associated with `tname` in the registry.

luaL_ref #

Arguments

:: State |
-> StackIndex | t
-> IO CInt |

Creates and returns a reference, in the table at index `t`, for the object at the top of the stack (and pops the object).

A reference is a unique integer key. As long as you do not manually add integer keys into table `t`, `luaL_ref` ensures the uniqueness of the key it returns. You can retrieve an object referred by reference `r` by calling `lua_rawgeti l t r`. Function ``luaL_unref`` frees a reference and its associated object.

If the object at the top of the stack is nil, `luaL_ref` returns the constant ``LUA_REFNIL``. The constant ``LUA_NOREF`` is guaranteed to be different from any reference returned by `luaL_ref`.

luaL_testudata #

Arguments

:: State | l
-> StackIndex | arg
-> CString | tname
-> IO (Ptr ()) |

Checks whether the function argument `arg` is a userdata of the type `tname` (see ``luaL_newmetatable``) and returns the userdata address (see ``lua_touserdata``). Returns `NULL` if the test fails.

https://www.lua.org/manual/5.3/manual.html#luaL_testudata

luaL_traceback #

Arguments

:: State | l
-> State | l1
-> CString | msg
-> CInt | level
-> IO () |

Creates and pushes a traceback of the stack `l1`. If `msg` is not `NULL` it is appended at the beginning of the traceback. The level parameter tells at which level to start the traceback.

luaL_unref #

Arguments

:: State |
-> StackIndex | t
-> CInt | ref
-> IO () |

Releases reference `ref` from the table at index `t` (see ``luaL_ref``). The entry is removed from the table, so that the referred object can be collected. The reference `ref` is also freed to be used again.

luaL_where #

Arguments

:: State | l
-> CInt | lvl
-> IO () |

Pushes onto the stack a string identifying the current position of the control at level `lvl` in the call stack. Typically this string has the following format:

    chunkname:currentline:

Level 0 is the running function, level 1 is the function that called the running function, etc.

This function is used to build a prefix for error messages.

## Registry fields

loadedTableRegistryField :: String #

Key, in the registry, for table of loaded modules.

preloadTableRegistryField :: String #

Key, in the registry, for table of preloaded loaders.

## References

data Reference #

Reference to a stored value.

Constructors

Reference CInt | Reference to a stored value
RefNil | Reference to a nil value

#### Instances

Instances details

Eq Reference # |
Instance details Defined in Lua.Auxiliary Methods (==) :: Reference -> Reference -> Bool # (/=) :: Reference -> Reference -> Bool #
Show Reference # |
Instance details Defined in Lua.Auxiliary Methods showsPrec :: Int -> Reference -> ShowS # show :: Reference -> String # showList :: [Reference] -> ShowS #

fromReference :: Reference -> CInt #

Convert a reference to its C representation.

toReference :: CInt -> Reference #

Create a reference from its C representation.