Lumacs/documentation/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:undo() - Undo last change
• editor:redo() - Redo last change
• editor:quit() - Quit the editor

Window Management:

• editor:split_horizontally() - Split current window (Top/Bottom)
• editor:split_vertically() - Split current window (Left/Right)
• editor:close_window() - Close the active window
• editor:next_window() - Cycle focus to the next window

lumacs (module)

Module namespace.

Classes:

• lumacs.Position(line, column) - Create a cursor position
• lumacs.Range(start_pos, end_pos) - Create a range
• lumacs.TextAttribute(color, style) - Create a text attribute

Enums:

• lumacs.ColorType - Colors (Keyword, String, Comment, etc.)
• lumacs.Style - Styles (Normal, Bold, Italic, Underline)
• lumacs.BufferEvent - Events (Loaded, AfterChange, etc.)

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
• buffer.language - Get/Set language string (e.g., "lua", "cpp")

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(range) - Delete a range of text
• buffer:erase_char(pos) - Delete character (backspace)
• buffer:replace(range, text) - Replace text in a range
• buffer:find(query, start_pos) - Find text starting from position. Returns Range or nil.
• buffer:save() - Save buffer to file

Styling & Events:

• buffer:set_style(range, attr) - Apply syntax highlighting
• buffer:clear_styles() - Clear all styles
• buffer:on_buffer_event(callback) - Register an event listener

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)

Range Object

Represents a text range.

Constructor:

local range = lumacs.Range(start_pos, end_pos)

Fields:

• range.start - Start Position
• range.end - End Position

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.
• Meta/Alt keys: "M-a", "M-2", "M-ArrowUp", etc.

Example:

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

message(text)

Display a message to the user (appears in the minibuffer/status line).

message("Hello from Lua!")

print(...)

Print to stderr (stdout is used by TUI).

print("Debug info:", value)

Example Configuration

-- Window Management
bind_key("M-2", function() editor:split_horizontally() end)
bind_key("M-3", function() editor:split_vertically() end)
bind_key("M-0", function() editor:close_window() end)
bind_key("C-w", function() editor:next_window() end)

-- Search
bind_key("C-f", function()
    -- Implementation using buffer:find()
end)

Interactive Command Buffer

Press : to enter the command buffer. You can type Lua commands or editor shortcuts.

• :w - Save
• :q - Quit
• :wq - Save and Quit
• :print(1+1) - Execute Lua code

Events System

Plugins can react to editor events:

editor.buffer:on_buffer_event(function(event)
    if event.event == lumacs.BufferEvent.Loaded then
        print("File loaded: " .. event.language)
    end
end)