# 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:**
```lua
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:**
```lua
bind_key("C-s", function()
    editor:buffer():save()
    message("Buffer saved!")
end)
```

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

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

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

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

## Example Configuration

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