How hammerspoon/hammerspoon works
Overall Project Layers
• Core Native Layer: This includes the native C/Objective-C code (found throughout the “Hammerspoon” directory and associated Xcode projects) that interacts directly with macOS system APIs.
• Lua Bridge & Scripting Engine: Built using LuaSkin and embedded Lua (with the Lua interpreter source under “LuaSkin/lua-5.4.7”, etc.), this layer exposes native functionality to user-written Lua scripts.
• Extensions Framework: Hammerspoon’s power comes from its many extensions (organized under the “extensions” directory). Each extension—for example “alert”, “appfinder”, “audiodevice”, “screen”, etc.—wraps native functionality into Lua-accessible modules.
• User Configuration: The user’s initialization file (~/.hammerspoon/init.lua) is where custom scripting and configuration take place, using the provided APIs.
Major Components to Illustrate
• OS X / macOS System APIs: At the bottom, the operating system’s native interfaces and frameworks.
• Core Application:
– The “Hammerspoon” main application component (as built from sources and Xcode projects) which contains the native bridge code.
– Build configurations and entitlements (referenced in the “Build Configs” directory).
– External dependencies (Pods, third-party libraries like CocoaLumberjack, CocoaHTTPServer, and SocketRocket) that support various functionalities.
• Lua Engine & Bridge:
– The integrated Lua interpreter and LuaSkin (which forms the interface between native code and Lua).
– The bridging logic (for example, files like “MJLua.m”, “HSLogger.m”, etc., in the Hammerspoon directory) that expose system functionality to the scripting side.
• Extensions:
– Some extensions include extra native libraries (for example, “libalert.m”, “libwindow.m”, “libhttp.m”, etc.).
• External Integrations & Community Infrastructure:
– Mention tools like the Podfile, GitHub workflows, and additional directories (e.g., “scripts”, “SPOONS.md”) which illustrate the build and extension lifecycle, though these are more tooling than runtime infrastructure.
Relationships and Data Flow
• That the Lua layer in turn calls into the native bridge layer via LuaSkin.
• The native bridge layer communicates with macOS system APIs.
• Extensions form modules that encapsulate specific system functionalities and expose well-defined Lua APIs.
Architectural Patterns & Design Principles
• Modularization: The project is split into a core native layer, a scripting layer, and multiple discrete extension modules.
• Separation of Concerns: There is a clear separation between low-level system interactions (native code) and high-level automation and configuration (Lua scripts).
• Bridging Pattern: A key design principle is the bridging mechanism that connects system APIs to Lua through LuaSkin.
• Extensibility: The “extensions” directory shows a plugin-style architecture making it simple to add or update functionality.