# 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:**
```lua
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:**
```lua
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:**
```lua
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).

```lua
message("Hello from Lua!")
```

### `print(...)`
Print to stderr (stdout is used by TUI).

```lua
print("Debug info:", value)
```

## Example Configuration

```lua
-- 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:

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