scrib

A Lua module for macOS automation via ScriptingBridge, written in Zig.

Usage

local scrib = require("scrib")

-- Connect to an application by bundle ID
local chrome = scrib.app("com.google.Chrome")
print(chrome.name)

-- Access properties and collections
chrome.windows[1].activeTab.URL = "https://example.com"

-- Call methods
chrome:activate()

-- Error handling (returns nil + error string on failure)
local app, err = scrib.app("com.nonexistent.app")
if not app then
    print("Error: " .. err)
end

How It Works

scrib bridges Lua and macOS applications through Apple's ScriptingBridge framework:

1. ObjC Wrapping — ScriptingBridge objects are wrapped as Lua userdata with metatables that enable natural Lua syntax
2. Dynamic Dispatch — Property access (obj.name) and method calls (obj:activate()) are resolved at runtime via __index/__newindex metamethods
3. Type Conversion — Lua types are automatically converted to/from ObjC equivalents (strings↔NSString, tables↔NSArray/CGRect, numbers↔NSNumber)
4. Collection Indexing — Lua's 1-based indexing is translated to ObjC's 0-based arrays

Requirements

• macOS
• Zig 0.15.0+
• Lua 5.4

Building

zig build

The library installs to zig-out/lib/scrib.so. Add this directory to your Lua package.cpath.

Validate:

lua -e 'package.cpath="zig-out/lib/?.so"; print(require("scrib").version())'

Testing

# Unit tests
zig build test

# Integration tests (uses real macOS apps like Finder)
zig build integration

License

MIT