hslua: Bindings to Lua, an embeddable scripting language

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

HsLua provides wrappers and helpers to bridge Haskell and Lua.

It builds upon the lua package, which allows to bundle a Lua interpreter with a Haskell program.

Example programs are available in a separate repository.


[Skip to Readme]

Properties

Versions 0.1, 0.2, 0.3, 0.3.2, 0.3.3, 0.3.4, 0.3.5, 0.3.6, 0.3.6.1, 0.3.7, 0.3.8, 0.3.9, 0.3.10, 0.3.11, 0.3.12, 0.3.13, 0.4.0, 0.4.1, 0.5.0, 0.6.0, 0.7.0, 0.7.1, 0.8.0, 0.9.0, 0.9.1, 0.9.2, 0.9.3, 0.9.4, 0.9.5, 0.9.5.1, 0.9.5.2, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.3.1, 1.0.3.2, 1.1.0, 1.1.1, 1.1.2, 1.2.0, 1.3.0, 1.3.0.1, 1.3.0.2, 2.0.0, 2.0.0, 2.0.1, 2.1.0, 2.2.0, 2.2.1, 2.3.0, 2.3.1
Change log CHANGELOG.md
Dependencies base (>=4.8 && <5), bytestring (>=0.10.2 && <0.12), containers (>=0.5.9 && <0.7), exceptions (>=0.8 && <0.11), hslua-classes (>=2.0 && <2.1), hslua-core (>=2.0 && <2.1), hslua-marshalling (>=2.0 && <2.1), hslua-objectorientation (>=2.0 && <2.1), hslua-packaging (>=2.0 && <2.1), mtl (>=2.2 && <2.3), text (>=1.0 && <1.3) [details]
License MIT
Copyright © 2007–2012 Gracjan Polak; © 2012–2016 Ömer Sinan Ağacan; © 2017-2021 Albert Krewinkel
Author Albert Krewinkel, Gracjan Polak, Ömer Sinan Ağacan
Maintainer albert+hslua@zeitkraut.de
Category Foreign
Home page https://hslua.org/
Bug tracker https://github.com/hslua/hslua/issues
Source repo head: git clone https://github.com/hslua/hslua.git
Uploaded by tarleb at 2021-10-21T18:32:50Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for hslua-2.0.0

[back to package description]

HsLua – Bindings to Lua, an embeddable scripting language

Build status AppVeyor Status Hackage

HsLua provides bindings, wrappers, types, and helper functions to bridge Haskell and Lua.

This package is part of HsLua, a Haskell framework built around the embeddable scripting language Lua.

Overview

Lua is a small, well-designed, embeddable scripting language. It has become the de-facto default to make programs extensible and is widely used everywhere from servers over games and desktop applications up to security software and embedded devices. This package provides Haskell bindings to Lua, enable coders to embed the language into their programs, making them scriptable.

HsLua ships with batteries included and includes Lua 5.3.6. Cabal flags make it easy to compile against a system-wide Lua installation.

Interacting with Lua

HsLua provides the Lua type to define Lua operations. The operations are executed by calling run. A simple "Hello, World" program, using the Lua print function, is given below:

import Foreign.Lua as Lua

main :: IO ()
main = Lua.run prog
  where
    prog :: Lua ()
    prog = do
      Lua.openlibs  -- load Lua libraries so we can use 'print'
      Lua.callFunc "print" "Hello, World!"

The Lua stack

Lua's API is stack-centered: most operations involve pushing values to the stack or receiving items from the stack. E.g., calling a function is performed by pushing the function onto the stack, followed by the function arguments in the order they should be passed to the function. The API function call then invokes the function with given numbers of arguments, pops the function and parameters off the stack, and pushes the results.

,----------.
|  arg 3   |
+----------+
|  arg 2   |
+----------+
|  arg 1   |
+----------+                  ,----------.
| function |    call 3 1      | result 1 |
+----------+   ===========>   +----------+
|          |                  |          |
|  stack   |                  |  stack   |
|          |                  |          |

Manually pushing and pulling arguments can become tiresome, so HsLua makes function calling simple by providing callFunc. It uses type-magic to allow different numbers of arguments. Think about it as having the signature

callFunc :: String -> a1 -> a2 -> … -> res

where the arguments a1, a2, … must be of a type which can be pushed to the Lua stack, and the result-type res must be constructable from a value on the Lua stack.

Getting values from and to the Lua stack

Conversion between Haskell and Lua values is governed by two type classes:

-- | A value that can be read from the Lua stack.
class Peekable a where
  -- | Check if at index @n@ there is a convertible Lua value and
  --   if so return it.  Throws a @'LuaException'@ otherwise.
  peek :: StackIndex -> Lua a

and

-- | A value that can be pushed to the Lua stack.
class Pushable a where
  -- | Pushes a value onto Lua stack, casting it into meaningfully
  --   nearest Lua type.
  push :: a -> Lua ()

Many basic data types (except for numeric types, see the FAQ) have instances for these type classes. New instances can be defined for custom types using the functions in Foreign.Lua.Core (also exported in Foreign.Lua).

Q&A