docs: update readme and docs for Zig 0.10.0

Author: natecraddock

docs.md

@@ -1,25 +1,25 @@
-# ziglua Documentation
+# Ziglua Documentation
 
-*To avoid a duplication of efforts, ziglua does not contain full documentation on the Lua C API. Please refer to [the Lua C API Documentation](https://www.lua.org/manual/5.4/manual.html#4) for full details.*
+*To avoid a duplication of efforts, Ziglua does not contain full documentation on the Lua C API. Please refer to the Lua C API Documentation for full details.*
 
 This documentation provides
 
-* An overview of ziglua's structure and changes from the C API
+* An overview of Ziglua's structure and changes from the C API
 * Safety considerations
 * `build.zig` documentation
 * Example code
 
-Documentation on each individual function is found in the [ziglua.zig](https://github.com/natecraddock/ziglua/blob/master/src/ziglua.zig) source code.
+Documentation on each individual function is found in the source code.
 
 ## Moving from the C API to Zig
 
-While efforts have been made to keep the ziglua API similar to the C API, many changes have been made including:
+While efforts have been made to keep the Ziglua API similar to the C API, many changes have been made including:
 
 * Renaming or omitting functions
 * Modifying parameters (names and types) and return values
 * Additional helper functions have been added
 
-With this in mind, here are some general guidelines to help guide when moving from the C to Zig APIs
+With this in mind, here are some general guidelines to help when moving from the C to Zig APIs
 
 ### Naming
 
@@ -35,13 +35,13 @@ Because Zig best practice is to communicate intent precisely, some abbreviations
 
 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.
 
-Ziglua provides a third option with the `Lua.init(Allocator)` function, which accepts a traditional 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.
+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.
 
 ## Safety
 
-The ziglua API aims to be safer than the traditional C API. That said, the way that Lua operates means that Zig cannot protect you from all errors due to the use of `longjmp` in C.
+The Ziglua API aims to be safer than the traditional C API. That said, the way that Lua operates means that Zig cannot protect you from all errors due to the use of `longjmp` in C.
 
-Here is a list of the types of features ziglua uses to ensure greater safety:
+Here is a list of the features Ziglua uses for greater safety:
 
 ### Errors
 
@@ -51,17 +51,17 @@ On the other hand, many functions either succeed or return an error. Rather than
 
 ### Booleans
 
-Functions that return or accept C boolean integers now use the Zig `bool` type to increase type safety.
+Functions that return or accept C boolean integers now use the Zig `bool` type.
 
 ### Slices
 
-In cases where C functions use separate pointers and ints to keep track of strings, ziglua uses a Zig slice to keep the data together.
+In cases where C functions use separate pointers and ints to keep track of strings, Ziglua uses a Zig slice to keep the data together.
 
-The slices are typed to indicate the contents (zero-terminated, raw bytes, etc)
+The slices are typed to indicate the contents (zero-terminated, raw bytes, etc.)
 
 ### Enums
 
-ziglua uses enums instead of integer codes or strings to prevent passing an invalid value to a function.
+Ziglua uses enums instead of integer codes or strings to prevent passing an invalid value to a function.
 
 ### Optionals
 
@@ -83,37 +83,36 @@ Because `error` is a reserved word in Zig, these functions have been renamed to
 
 ### `string` vs `lstring`
 
-The "string" variant functions vs the "lstring" functions only differ by returning the length of the string. In ziglua, the lstring functions are all named "bytes" instead. For example, `lua_tolstring` is `Lua.toBytes`. This is because these functions are typically used in cases when the string _might_ contain zeros before the null-terminating zero.
+The "string" variant functions vs the "lstring" functions only differ by returning the length of the string. In Ziglua, the lstring functions are all named "bytes" instead. For example, `lua_tolstring` is `Lua.toBytes`. This is because these functions are typically used in cases when the string _might_ contain zeros before the null-terminating zero.
 
 The "string" variant functions are safe to use when the string is known to be null terminated without inner zeros.
 
+The length of the returned string is almost always needed, so `Lua.toString() returns a zero-terminated Zig slice of the bytes with the correct length.
+
 ### `lua_pushvfstring`
 
-This function has been omitted because Zig does not have a va_list type, and `Lua.pushFString` works well
-enough for string formatting if variadic args are really needed.
-
-The length of the returned string is almost always needed, so `Lua.toString() returns a zero-terminated Zig slice of the bytes with the correct length.
+This function has been omitted because Zig does not have a va_list type, and `Lua.pushFString` works well enough for string formatting if variadic args are really needed.
 
 ### `lua_tointegerx` and `lua_tonumberx`
 
 Both of these functions accept an `isnum` return parameter to indicate if the conversion to number was successful. In the Zig version, both functions return either the number, or an error indicating the conversion was unsuccessful, and the `isnum` parameter is omitted.
 
 ### `lua_pushliteral`
 
-This is just a macro for `lua_pushstring`, so just use `Lua.pushString()` instead.
+This is a macro for `lua_pushstring`, so use `Lua.pushString()` instead.
 
 ### `pcall`
 
 Both `lua_pcall` and `lua_pcallk` are expanded to `protectedCall` and `protectedCallCont` for readability.
 
 ## Build Documentation
 
-When integrating ziglua into your projects, the following two statements are required:
+When integrating Ziglua into your projects, the following two statements are required:
 
 1. `@import()` the `build.zig` file
-2. `addPackage()` the ziglua api
+2. `addPackage()` the Ziglua api
 
-Note that this _must_ be done after setting the target and build mode, otherwise ziglua will not know that information.
+Note that this _must_ be done after setting the target and build mode, otherwise Ziglua will not know that information.
 
 ```zig
 const ziglua = @import("lib/ziglua/build.zig");
@@ -126,7 +125,7 @@ pub fn build(b: *Builder) void {
 
 This makes the `ziglua` package available in your project. Access with `@import("ziglua")`.
 
-There are currently three options that can be passed in the third argument to `ziglua.link()`:
+There are currently three options that can be passed in the third argument to `ziglua.linkAndPackage()`:
 
 * `.use_apicheck`: defaults to **false**. When **true** defines the macro `LUA_USE_APICHECK` in debug builds. See [The C API docs](https://www.lua.org/manual/5.4/manual.html#4) for more information on this macro.
 
@@ -142,7 +141,7 @@ exe.addPackage(ziglua.linkAndPackage(b, exe, .{ .use_apicheck = true, .version =
 
 ## Examples
 
-Here are more thorough examples that show off the ziglua bindings in context. All examples use previously documented [`build.zig`](#build-documentation) setup.
+Here are more thorough examples that show off the Ziglua bindings in context. All examples use the previously documented [`build.zig`](#build-documentation) setup.
 
 ### Simple Lua Interpreter
 
@@ -186,14 +185,14 @@ pub fn main() anyerror!void {
 
         // Compile a line of Lua code
         lua.loadString(buffer[0..len :0]) catch {
-            try stdout.print("{s}\n", .{lua.toString(-1)});
+            try stdout.print("{s}\n", .{lua.toString(-1) catch unreachable});
             lua.pop(1);
             continue;
         };
 
         // Execute a line of Lua code
         lua.protectedCall(0, 0, 0) catch {
-            try stdout.print("{s}\n", .{lua.toString(-1)});
+            try stdout.print("{s}\n", .{lua.toString(-1) catch unreachable});
             lua.pop(1);
         };
     }
@@ -204,6 +203,8 @@ This shows a basic interpreter that reads a string from stdin. That string is pa
 
 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.
 
+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"`
+
 ### Calling a Zig function
 
 Registering a Zig function to be called from Lua is simple
@@ -236,7 +237,7 @@ pub fn main() anyerror!void {
     // assert that this function call will not error
     lua.protectedCall(2, 1, 0) catch unreachable;
 
-    std.debug.print("the result: {}\n", .{lua.toInteger(1)});
+    std.debug.print("the result: {}\n", .{lua.toInteger(1) catch unreachable});
 }
 ```
 

readme.md

@@ -1,11 +1,13 @@
 # Ziglua
 
-A Zig library that provides a complete yet lightweight wrapper around the [Lua C API](https://www.lua.org/manual/5.4/manual.html#4). Ziglua currently supports the latest releases of Lua 5.1, 5.2, 5.3, and 5.4.
+A Zig library that provides a complete and lightweight wrapper around the [Lua C API](https://www.lua.org/manual/5.4/manual.html#4). Ziglua currently supports the latest releases of Lua 5.1, 5.2, 5.3, and 5.4.
 
-Ziglua offers two approaches as a library:
-* **embedded**: used to embed the Lua VM in a Zig program
+The Ziglua library offers two use cases:
+* **embedded**: used to statically embed the Lua VM in a Zig program
 * **module**: used to create shared Lua modules that can be loaded at runtime in other Lua-based software
 
+In both cases, Ziglua will compile Lua from source and link against your Zig code making it easy to create software that integrates with Lua without requiring Lua libraries installed on your system.
+
 Like the Lua C API, the Ziglua API "emphasizes flexibility and simplicity... common tasks may involve several API calls. This may be boring, but it gives us full control over all the details" (_Programming In Lua 4th Edition_). However, Ziglua takes advantage of Zig's features to make it easier and safer to interact with the Lua API.
 
 * [Docs](https://github.com/natecraddock/ziglua/blob/master/docs.md)
@@ -19,15 +21,15 @@ In a nutshell, Ziglua is a simple wrapper around the C API you would get by usin
 * Null-terminated slices instead of C strings
 * Type-checked enums for parameters and return values
 * Compiler-enforced checking of optional pointers
-* More precise types (e.g. `bool` instead of `int`)
+* Better types in many cases (e.g. `bool` instead of `int`)
 
 While there are some helper functions added to complement the C API, Ziglua aims to remain low-level. This allows full access to the Lua API through a layer of Zig's improvements over C.
 
 If you want something higher-level (but doesn't expose the full API), perhaps try [zoltan](https://github.com/ranciere/zoltan).
 
 ## Getting Started
 
-Adding Ziglua to your project is easy. First add this repo as a git submodule, or copy the source into your repo. Then add the following to your `build.zig` file (assuming cloned/copied into a `lib/` subdirectory):
+Adding Ziglua to your project takes only a couple of steps. First add this repo as a git submodule, or copy the source into your project (one day the Zig package manager will make this easier). Then add the following to your `build.zig` file (assuming cloned/copied into a `lib/` subdirectory):
 
 ```zig
 // use the path to the Ziglua build.zig file
@@ -39,7 +41,7 @@ pub fn build(b: *Builder) void {
 }
 ```
 
-This will compile the Lua C sources and statically link with your project. Then simply import the `ziglua` package into your code! Here is a simple example that pushes and inspects an integer on the Lua stack:
+This will compile the Lua C sources and statically link with your project. Then simply import the `ziglua` package into your code. Here is a simple example that pushes and inspects an integer on the Lua stack:
 
 ```zig
 const std = @import("std");
@@ -56,7 +58,7 @@ pub fn main() anyerror!void {
     defer lua.deinit();
 
     lua.pushInteger(42);
-    std.debug.print("{}\n", .{lua.toInteger(1)});
+    std.debug.print("{}\n", .{try lua.toInteger(1)});
 }
 ```
 
@@ -66,7 +68,7 @@ See [docs.md](https://github.com/natecraddock/ziglua/blob/master/docs.md) for do
 
 Nearly all functions, types, and constants in the C API have been wrapped in Ziglua. Only a few exceptions have been made when the function doesn't make sense in Zig (like functions using `va_list`).
 
-All functions have been type checked, but only the standard C API has been tested fully. Ziglua should be relatively stable and safe to use now, but is still new and changing frequently.
+Nearly all functions have associated Zig tests. Ziglua should be relatively stable and safe to use now, but I am still polishing things and function signatures may change from time to time.
 
 ## Acknowledgements