README.md
1# HsLua – Bindings to Lua, an embeddable scripting language
2
3[![Build status][GitHub Actions badge]][GitHub Actions]
4[![AppVeyor Status]](https://ci.appveyor.com/project/tarleb/hslua-r2y18)
5[![Hackage]](https://hackage.haskell.org/package/hslua)
6
7HsLua provides bindings, wrappers, types, and helper functions to bridge
8Haskell and Lua.
9
10[GitHub Actions badge]: https://img.shields.io/github/workflow/status/hslua/hslua/CI.svg?logo=github
11[GitHub Actions]: https://github.com/hslua/hslua/actions
12[AppVeyor Status]: https://ci.appveyor.com/api/projects/status/ldutrilgxhpcau94/branch/main?svg=true
13[Hackage]: https://img.shields.io/hackage/v/hslua.svg
14
15
16Overview
17--------
18
19[Lua](https://lua.org) is a small, well-designed, embeddable scripting language.
20It has become the de-facto default to make programs extensible and is widely
21used everywhere from servers over games and desktop applications up to security
22software and embedded devices. This package provides Haskell bindings to Lua,
23enable coders to embed the language into their programs, making them scriptable.
24
25HsLua ships with batteries included and includes Lua 5.3.6. Cabal
26flags make it easy to compile against a system-wide Lua
27installation.
28
29
30Interacting with Lua
31--------------------
32
33HsLua provides the `Lua` type to define Lua operations. The operations are
34executed by calling `run`. A simple "Hello, World" program, using the Lua
35`print` function, is given below:
36
37``` haskell
38import Foreign.Lua as Lua
39
40main :: IO ()
41main = Lua.run prog
42 where
43 prog :: Lua ()
44 prog = do
45 Lua.openlibs -- load Lua libraries so we can use 'print'
46 Lua.callFunc "print" "Hello, World!"
47```
48
49### The Lua stack
50
51Lua's API is stack-centered: most operations involve pushing values to the stack
52or receiving items from the stack. E.g., calling a function is performed by
53pushing the function onto the stack, followed by the function arguments in the
54order they should be passed to the function. The API function `call` then
55invokes the function with given numbers of arguments, pops the function and
56parameters of the stack, and pushes the results.
57
58 ,----------.
59 | arg 3 |
60 +----------+
61 | arg 2 |
62 +----------+
63 | arg 1 |
64 +----------+ ,----------.
65 | function | call 3 1 | result 1 |
66 +----------+ ===========> +----------+
67 | | | |
68 | stack | | stack |
69 | | | |
70
71Manually pushing and pulling arguments can become tiresome, so HsLua makes
72function calling simple by providing `callFunc`. It uses type-magic to allow
73different numbers of arguments. Think about it as having the signature
74
75 callFunc :: String -> a1 -> a2 -> … -> res
76
77where the arguments `a1, a2, …` must be of a type which can be pushed to the Lua
78stack, and the result-type `res` must be constructable from a value on the Lua
79stack.
80
81### Getting values from and to the Lua stack
82
83Conversion between Haskell and Lua values is governed by two type classes:
84
85``` haskell
86-- | A value that can be read from the Lua stack.
87class Peekable a where
88 -- | Check if at index @n@ there is a convertible Lua value and
89 -- if so return it. Throws a @'LuaException'@ otherwise.
90 peek :: StackIndex -> Lua a
91```
92
93and
94
95``` haskell
96-- | A value that can be pushed to the Lua stack.
97class Pushable a where
98 -- | Pushes a value onto Lua stack, casting it into meaningfully
99 -- nearest Lua type.
100 push :: a -> Lua ()
101```
102
103Many basic data types (except for numeric types, see the FAQ) have instances for
104these type classes. New instances can be defined for custom types using the
105functions in `Foreign.Lua.Core` (also exported in `Foreign.Lua`).
106
107
108Build flags
109-----------
110
111The following cabal build flags are supported:
112
113- `system-lua`: Use the locally installed Lua version instead of the version
114 shipped as part of HsLua.
115
116- `pkg-config`: Use *pkg-config* to discover library and include paths. Setting
117 this flag implies `system-lua`.
118
119- `allow-unsafe-gc`: Allow optimizations which make Lua's garbage collection
120 potentially unsafe; haskell finalizers must be handled with extreme care. This
121 is *enabled* per default, as this is rarely a problem in practice.
122
123- `apicheck`: Compile Lua with its API checks enabled.
124
125- `lua_32bits`: Compile Lua for a 32-bits system (e.g., i386, PowerPC G4).
126
127- `export-dynamic`: Add all symbols to dynamic symbol table; disabling this
128 will make it possible to create fully static binaries, but renders loading
129 of dynamic C libraries impossible.
130
131
132### Example: using a different lua version
133
134To use a system-wide installed Lua when linking hslua as a dependency,
135build/install your package using `--constraint="hslua +system-lua"`. For
136example, you can install Pandoc with hslua that uses system-wide Lua like
137this:
138
139``` sh
140cabal install pandoc --constraint="hslua +system-lua"
141```
142
143or with stack:
144
145``` sh
146stack install pandoc --flag=hslua:system-lua
147```
148
149
150Q&A
151---
152
153- **Can I see some examples?** Basic examples are available in the
154 [*hslua-examples*](https://github.com/hslua/hslua-examples) repository.
155
156 A big project build with hslua is [Pandoc](https://pandoc.org), the
157 universal document converter. It is written in Haskell and includes a Lua
158 interpreter, enabling programmatic modifications of documents via Lua.
159 Furthermore, custom output formats can be defined via Lua scripts.
160
161- **Where are the coroutine related functions?** Yielding from a coroutine works
162 via `longjmp`, which plays very badly with Haskell's RTS. Tests to get
163 coroutines working with HsLua were unsuccessful. No coroutine related
164 functions are exported from the default module for that reason. Pull
165 requests intended to fix this are very welcome.
166
