Lua API Usage¶
cais provides idiomatic Lua bindings with object-oriented wrappers, options tables, and automatic resource reclamation.
Requiring Modules¶
You can load the umbrella module or individual submodules:
-- Load complete library
local cais = require("cais")
-- Or load lightweight, standalone submodules
local fs = require("cais.fs") -- or cais.filesystem
local socket = require("cais.socket")
local serial = require("cais.serial")
Idiomatic Return Conventions¶
Functions in cais follow the standard Lua convention for fallible calls:
- On Success: Returns result object(s) or true.
- On Failure: Returns nil, followed by an error string (e.g. nil, "connection refused" or nil, "timeout").
local sock, err = cais.socket.connect("127.0.0.1", 9000)
if not sock then
print("Failed to connect: " .. tostring(err))
return
end
Object-Oriented Methods and Cleanup¶
All native handles (sock, port, file) expose object methods and automatic garbage collection (__gc):
local sock = cais.socket.connect("127.0.0.1", 8080)
-- Explicit close:
sock:close()
-- Or let Lua's garbage collector automatically reclaim the file descriptor
-- without memory leaks or descriptor exhaustion.
Flexible Parameterization¶
Constructors accept either concise options tables or classic positional arguments: