Lumacs/LUA_API.md

Lumacs Lua API Documentation

Lumacs provides a powerful Lua scripting API for configuration and extensibility, inspired by Emacs but using Lua instead of Elisp.

Configuration File

Lumacs loads init.lua from one of these locations (in order):

1. ./init.lua (current directory)
2. ~/.config/lumacs/init.lua
3. ~/.lumacs/init.lua

Global Objects

editor (EditorCore)

The main editor instance.

Properties:

• editor:buffer() - Returns the current Buffer
• editor:cursor() - Returns current Position
• editor:set_cursor(pos) - Set cursor position

Methods:

• editor:move_up() - Move cursor up
• editor:move_down() - Move cursor down
• editor:move_left() - Move cursor left
• editor:move_right() - Move cursor right
• editor:move_to_line_start() - Move to start of line
• editor:move_to_line_end() - Move to end of line
• editor:load_file(path) - Load a file
• editor:quit() - Quit the editor

lumacs (module)

Module namespace.

Classes:

• lumacs.Position(line, column) - Create a cursor position

Buffer Object

Returned by editor:buffer().

Properties:

• buffer:name() - Get buffer name
• buffer:line_count() - Get number of lines
• buffer:is_modified() - Check if modified
• buffer:content() - Get entire content as string

Methods:

• buffer:line(index) - Get line by index (0-based)
• buffer:insert(pos, text) - Insert text at position
• buffer:insert_char(pos, char) - Insert single character
• buffer:insert_newline(pos) - Insert newline
• buffer:erase_char(pos) - Delete character (backspace)
• buffer:save() - Save buffer to file

Position Object

Represents a cursor position.

Constructor:

local pos = lumacs.Position(line, column)

Fields:

• pos.line - Line number (0-based)
• pos.column - Column number (0-based)

Global Functions

bind_key(key, callback)

Bind a key to a Lua function.

Key names:

• Single characters: "a", "b", "1", etc.
• Special keys: "Escape", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End"
• Control keys: "C-a", "C-s", "C-c", etc.

Example:

bind_key("C-s", function()
    editor:buffer():save()
    message("Buffer saved!")
end)

message(text)

Display a message to the user (appears in stderr).

message("Hello from Lua!")

print(...)

Print to stderr (stdout is used by TUI).

print("Debug info:", value)

Example Configuration

-- Emacs-style navigation
bind_key("C-n", function() editor:move_down() end)
bind_key("C-p", function() editor:move_up() end)
bind_key("C-f", function() editor:move_right() end)
bind_key("C-b", function() editor:move_left() end)
bind_key("C-a", function() editor:move_to_line_start() end)
bind_key("C-e", function() editor:move_to_line_end() end)

-- Save buffer
bind_key("C-s", function()
    if editor:buffer():save() then
        message("Saved!")
    else
        message("Failed to save")
    end
end)

-- Insert timestamp
bind_key("C-t", function()
    local timestamp = os.date("%Y-%m-%d %H:%M:%S")
    editor:buffer():insert(editor:cursor(), timestamp)
end)

-- Custom functions
function goto_line(n)
    editor:set_cursor(lumacs.Position(n - 1, 0))
end

message("Lumacs configured!")

Future Features

Coming soon:

• Command buffer - Execute Lua code interactively (like M-x eval in Emacs)
• Multiple buffers - Switch between open files
• Window splits - Split panes with different buffers
• Hooks - Run code on events (file open, save, etc.)
• More buffer operations - Search, replace, undo/redo

Tips

• Use print() for debugging (output goes to stderr)
• Check the example init.lua for more ideas
• Lua has full access to the editor state
• Key bindings override default bindings