Skip to content

Commit a02e3f3

Browse files
natecraddocknatecraddock
committed
docs: restructure documentation and remove examples
Examples are now separate files
1 parent eeacf60 commit a02e3f3

1 file changed

Lines changed: 58 additions & 165 deletions

File tree

‎docs.md‎

Lines changed: 58 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,65 @@
44

55
This documentation provides
66

7+
* `build.zig` documentation
78
* An overview of Ziglua's structure and changes from the C API
89
* Safety considerations
9-
* `build.zig` documentation
1010

1111
Documentation on each individual function is found in the source code.
1212

13+
## Build Documentation
14+
15+
Example `build.zig.zon` file. The hash in the url is the hash of the commit you are using.
16+
17+
```
18+
.{
19+
.name = "myproject",
20+
.version = "0.0.1",
21+
.dependencies = .{
22+
.ziglua = .{
23+
.url = "https://github.com/natecraddock/ziglua/archive/ab111adb06d2d4dc187ee9e1e352617ca8659155.tar.gz",
24+
.hash = "12206cf9e90462ee6e14f593ea6e0802b9fe434429ba10992a1451e32900f741005c",
25+
},
26+
}
27+
}
28+
```
29+
30+
Example usage in `build.zig`.
31+
32+
```zig
33+
pub fn build(b: *std.Build) void {
34+
// ... snip ...
35+
36+
const ziglua = b.dependency("ziglua", .{
37+
.target = target,
38+
.optimize = optimize,
39+
});
40+
41+
// ... snip ...
42+
43+
// add the ziglua module and lua artifact
44+
exe.addModule("ziglua", ziglua.module("ziglua"));
45+
exe.linkLibrary(ziglua.artifact("lua"));
46+
47+
}
48+
```
49+
50+
There are currently two additional options that can be passed to `b.dependency()`:
51+
52+
* `.version`: Set the Lua version to build and embed. Defaults to `.lua_54`. Possible values are `.lua_51`, `.lua_52`, `.lua_53`, and `.lua_54`.
53+
* `.shared`: Defaults to `false` for embedding in a Zig program. Set to `true` to dynamically link the Lua source code (useful for creating shared modules).
54+
55+
For example, here is a `b.dependency()` call that and links against a shared Lua 5.2 library:
56+
57+
```zig
58+
const ziglua = b.dependency("ziglua", .{
59+
.target = target,
60+
.optimize = optimize,
61+
.version = .lua52,
62+
.shared = true,
63+
});
64+
```
65+
1366
## Moving from the C API to Zig
1467

1568
While efforts have been made to keep the Ziglua API similar to the C API, many changes have been made including:
@@ -24,17 +77,17 @@ With this in mind, here are some general guidelines to help when moving from the
2477

2578
In general, most functions are named similarly to the original C functions. The `lua_` and `luaL_` prefixes have been removed, because all functions are in the `Lua` struct namespace. Additionally, all functions are in `camelCase` to match Zig naming style.
2679

27-
In the few cases when the [auxiliary library](https://www.lua.org/manual/5.4/manual.html#5) functions have the same name as a normal C API function, the suffix `Aux` is added to the function name to distinguish from the normal function.
80+
In the few cases when the [auxiliary library](https://www.lua.org/manual/5.4/manual.html#5) functions have the same name as a normal C API function, the auxlib function is given a more descriptive name.
2881

29-
For example, the functions `lua_newstate` and `luaL_newstate` are translated to `Lua.newState` and `Lua.newStateAux` respectively.
82+
For example, the functions `lua_newstate` and `luaL_newstate` are translated to `Lua.newState` and `Lua.newStateLibc` respectively.
3083

3184
Because Zig best practice is to communicate intent precisely, some abbreviations are expanded to make names more clear, like renaming `pcall` to `protectedCall`.
3285

3386
### Lua Initialization
3487

3588
In the C API, there are two functions provided to initialize the main Lua state: `lua_newstate` and `luaL_newstate`. The former requires passing an allocator function to be used by Lua for all memory allocations, while the latter uses the default libc allocator.
3689

37-
Ziglua provides a third option with the `Lua.init(Allocator)` function, which accepts a Zig allocator. All three functions are available depending on your needs, but most likely you will want to use the `Lua.init(Allocator)` function. If you have special requirements for allocation, then `Lua.newState` would be useful. `Lua.newStateAux` is available if you wish to use the default libc allocator.
90+
Ziglua provides a third option with the `Lua.init(Allocator)` function, which accepts a Zig allocator. All three functions are available depending on your needs, but most likely you will want to use the `Lua.init(Allocator)` function. If you have special requirements for allocation, then `Lua.newState` would be useful. `Lua.newStateLibc` is available if you wish to use the default libc allocator.
3891

3992
## Safety
4093

@@ -44,7 +97,7 @@ Here is a list of the features Ziglua uses for greater safety:
4497

4598
### Errors
4699

47-
Many functions now return Zig errors rather than an integer code. The compiler will then ensure that the error is handled, or ignored. There are specific error types like `ziglua.Error.Runtime` for errors that have a specific meaning.
100+
Many functions now return Zig errors rather than an integer code. The Zig compiler will then ensure that the error is handled, or ignored. There are specific error types like `ziglua.Error.Runtime` for errors that have a specific meaning.
48101

49102
On the other hand, many functions either succeed or return an error. Rather than returning a boolean success code, these functions return the generic `ziglua.Error.Fail` to indicate failure. The type of failure can be determined in the context of the function called.
50103

@@ -103,163 +156,3 @@ This is a macro for `lua_pushstring`, so use `Lua.pushString()` instead.
103156
### `pcall`
104157

105158
Both `lua_pcall` and `lua_pcallk` are expanded to `protectedCall` and `protectedCallCont` for readability.
106-
107-
## Build Documentation
108-
109-
Example `build.zig.zon` file. The hash in the url is the hash of the commit you are using.
110-
111-
```
112-
.{
113-
.name = "myproject",
114-
.version = "0.0.1",
115-
.dependencies = .{
116-
.ziglua = .{
117-
.url = "https://github.com/natecraddock/ziglua/archive/ab111adb06d2d4dc187ee9e1e352617ca8659155.tar.gz",
118-
.hash = "12206cf9e90462ee6e14f593ea6e0802b9fe434429ba10992a1451e32900f741005c",
119-
},
120-
}
121-
}
122-
```
123-
124-
Example usage in `build.zig`.
125-
126-
```zig
127-
pub fn build(b: *std.Build) void {
128-
// ... snip ...
129-
130-
const ziglua = b.dependency("ziglua", .{
131-
.target = target,
132-
.optimize = optimize,
133-
});
134-
135-
// ... snip ...
136-
137-
// add the ziglua module and lua artifact
138-
exe.addModule("ziglua", ziglua.module("ziglua"));
139-
exe.linkLibrary(ziglua.artifact("lua"));
140-
141-
}
142-
```
143-
144-
There are currently two additional options that can be passed to `b.dependency()`:
145-
146-
* `.version`: Set the Lua version to build and embed. Defaults to `.lua_54`. Possible values are `.lua_51`, `.lua_52`, `.lua_53`, and `.lua_54`.
147-
148-
* `.shared`: Defaults to `false` for embedding in a Zig program. Set to `true` to dynamically link the Lua source code (useful for creating shared modules).
149-
150-
For example, here is a `b.dependency()` call that and links against a shared Lua 5.2 library:
151-
152-
```zig
153-
const ziglua = b.dependency("ziglua", .{
154-
.target = target,
155-
.optimize = optimize,
156-
.version = .lua52,
157-
.shared = true,
158-
});
159-
```
160-
161-
## Examples
162-
163-
Here are more thorough examples that show off the Ziglua bindings in context. All examples use the previously documented [`build.zig`](#build-documentation) setup.
164-
165-
### Simple Lua Interpreter
166-
167-
This is a modified program from _Programming In Lua 4th Edition_
168-
169-
```zig
170-
const std = @import("std");
171-
const ziglua = @import("ziglua");
172-
173-
const Lua = ziglua.Lua;
174-
175-
pub fn main() anyerror!void {
176-
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
177-
const allocator = gpa.allocator();
178-
defer _ = gpa.deinit();
179-
180-
// Initialize The Lua vm and get a reference to the main thread
181-
var lua = try Lua.init(allocator);
182-
defer lua.deinit();
183-
184-
// Open the standard libraries
185-
lua.openLibs();
186-
187-
var stdin = std.io.getStdIn().reader();
188-
var stdout = std.io.getStdOut().writer();
189-
190-
var buffer: [256]u8 = undefined;
191-
while (true) {
192-
_ = try stdout.write("> ");
193-
194-
// Read a line of input
195-
const len = try stdin.read(&buffer);
196-
if (len == 0) break; // EOF
197-
if (len >= buffer.len - 1) {
198-
try stdout.print("error: line too long!\n", .{});
199-
continue;
200-
}
201-
202-
// Ensure the buffer is null-terminated so the Lua API can read the length
203-
buffer[len] = 0;
204-
205-
// Compile a line of Lua code
206-
lua.loadString(buffer[0..len :0]) catch {
207-
try stdout.print("{s}\n", .{lua.toString(-1) catch unreachable});
208-
lua.pop(1);
209-
continue;
210-
};
211-
212-
// Execute a line of Lua code
213-
lua.protectedCall(0, 0, 0) catch {
214-
try stdout.print("{s}\n", .{lua.toString(-1) catch unreachable});
215-
lua.pop(1);
216-
};
217-
}
218-
}
219-
```
220-
221-
This shows a basic interpreter that reads a string from stdin. That string is parsed and compiled as Lua code and then executed.
222-
223-
Notice that the functions `lua.loadString()` and `lua.protectedCall()` return errors that must be handled, here printing the error message that was placed on the stack.
224-
225-
The `lua.toString()` calls are both followed with `catch unreachable` in this example. This function can fail if the value at the given index is not a string. The stack should contain a Lua error string, so in this example we assert that it will not fail. We also could have passed a generic error string with `catch "Error"`
226-
227-
### Calling a Zig function
228-
229-
Registering a Zig function to be called from Lua is simple
230-
231-
```zig
232-
const std = @import("std");
233-
const ziglua = @import("ziglua");
234-
235-
const Lua = ziglua.Lua;
236-
237-
fn adder(lua: *Lua) i32 {
238-
const a = lua.toInteger(1) catch 0;
239-
const b = lua.toInteger(2) catch 0;
240-
lua.pushInteger(a + b);
241-
return 1;
242-
}
243-
244-
pub fn main() anyerror!void {
245-
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
246-
const allocator = gpa.allocator();
247-
defer _ = gpa.deinit();
248-
249-
var lua = try Lua.init(allocator);
250-
defer lua.deinit();
251-
252-
lua.pushFunction(ziglua.wrap(adder));
253-
lua.pushInteger(10);
254-
lua.pushInteger(32);
255-
256-
// assert that this function call will not error
257-
lua.protectedCall(2, 1, 0) catch unreachable;
258-
259-
std.debug.print("the result: {}\n", .{lua.toInteger(1) catch unreachable});
260-
}
261-
```
262-
263-
Notice the use of `ziglua.wrap`. This is because the function `fn adder(*Lua) i32` is a `ziglua.ZigFn`, when the `lua.pushFunction` call expects a `ziglua.CFn` type.
264-
265-
The `ziglua.wrap` function generates a new function at compile time that wraps the Zig function in a function compatible with the Lua C API. This could be done automatically by `lua.pushFunction`, but that would require the parameter to be comptime-known. The call to `ziglua.wrap` is slightly more verbose, but has the benefit of being more flexible.

0 commit comments

Comments
 (0)