path: root/README.md

# sild - The Small Interactive Lua Debugger

`sild` is a standalone, TUI debugger for Lua scripts. It build statically and can run on most

```
sild [options] <script.lua> [script args...]
```

---

## Installation

Copy `sild` to a location on your `$PATH` and make it executable:

```sh
cp sild ~/.local/bin/sild
chmod +x ~/.local/bin/sild
```

---

## Quick start

```sh
sild myscript.lua
```

sild will pause on the first line of your script. From there:

| Key                   | Action                                   |
|-----------------------|------------------------------------------|
| `n / <enter>`         | step to next line                        |
| `c`                   | continue freely (honours breakpoints)    |
| `c <line>`            | continue until line (one-shot)           |
| `finish`              | run until current function returns       |
| `vars`                | list locals in scope with types          |
| `eval <expr>`         | evaluate a Lua expression                |
| `dump <tbl> [depth]`  | dump table recursively (default depth 3) |
| `bt`                  | stack traceback                          |
| `calls`               | show function call counts                |
| `set <name> <expr>`   | set a local variable by name             |
| `watch <expr>`        | watch expression, printed each step      |
| `unwatch <expr>`      | remove a watch                           |
| `watches`             | list active watches                      |
| `bp <line>`           | set breakpoint at line                   |
| `bp <line> if <expr>` | conditional breakpoint                   |
| `bpdel <line>`        | remove breakpoint at line                |
| `bplist`              | list all breakpoints                     |
| `q`                   | quit sild                                |
| `? / h / help`        | show this help                           |

---

## Command-line options

| Flag                  | Description                                            |
|-----------------------|--------------------------------------------------------|
| `-b, --break <line>`  | Set a breakpoint at `<line>` before execution starts.  |
| `-c, --config <file>` | Load config from `<file>` instead of the default path. |
| `-l, --lines <n>`     | Number of source lines shown in the code view.         |
| `-C, --columns <n>`   | Inner width of the code box in characters.             |
| `-W, --width <n>`     | Width of the history column in characters.             |
| `-h, --help`          | Print help and exit.                                   |
| `-v, --version`       | Print version and exit.                                |

Arguments after the script name are passed to the script via the usual `arg` table.

```sh
sild -b 42 -b 87 myscript.lua arg1 arg2
```

---

## Inline annotations

To write breakpoints and watches in your script, write them in the following annotation form.

```lua
--- BREAK
```
Break on the following line.

```lua
--- BREAK if n > 5
```
Break on the following line, only if the expression returns truthy. The expression is evaluated in the scope of your code at that point.

```lua
--- WATCH n
--- WATCH a[1]
```
Register a watch. The watch is added once, the first time the annotation is reached, and stays watched until removed with `unwatch`.

```lua
--- UNWATCH n
```
Remove a registered watch.

---

## Configuration

The default config file is loaded from first:

```
$XDG_CONFIG_HOME/sild/sild.cfg
```
else
```
~/.config/sild/sild.cfg
```

You can use a custom config with:
```
sild --config /path/to/file.cfg
```

If a config file does not exist, sild runs with it's built-in defaults.

### Format

```ini
# Lines starting with # are comments.
# key = value
code_lines = 20
col_keyword = 1;32
```

Keys and values are separated by `=`. Strings may be optionally quoted. Numbers must be plain integers. Unknown keys produce a warning on stderr.

### Available settings

#### Layout

| Key          | Default | Description                                       |
|--------------|---------|---------------------------------------------------|
| `auto_size`  | `true`  | Should the UI set it's own size for the terminal. | 
| `code_lines` | `15`    | Number of source lines shown in the code box.     |
| `code_inner` | `56`    | Inner width of the code box in characters.        |
| `hist_width` | `40`    | Width of the history column in characters.        |

#### Colours

All colours are specified as ANSI SGR codes as the digits between `\e[` and `m`.

| Code range | Meaning               |
|------------|-----------------------|
| `0`        | Reset                 |
| `1`        | Bold                  |
| `2`        | Dim                   |
| `31`–`37`  | Foreground colours    |
| `90`–`97`  | Bright foreground     |
| `1;33`     | Compound (bold yellow)|
| `""`       | No colour             |

| Key           | Default | Applied to                         |
|---------------|---------|------------------------------------|
| `col_keyword` | `1;34`  | Lua keywords                       |
| `col_string`  | `32`    | String literals                    |
| `col_number`  | `35`    | Numeric literals                   |
| `col_operator`| `33`    | Operators                          |
| `col_comment` | `2`     | Comments                           |
| `col_current` | `33`    | Current line marker                |
| `col_breakpt` | `31`    | Breakpoint line number             |
| `col_dim`     | `2`     | Dimmed elements                    |
| `col_header`  | `36`    | History column headers             |
| `col_lineno`  | `33`    | Line number inside history headers |
| `col_watch`   | `36`    | Watch label prefix                 |
| `col_value`   | `33`    | Evaluated values                   |
| `col_info`    | `36`    | Informational messages             |
| `col_error`   | `31`    | Error messages                     |
| `col_prompt`  | `33`    | Banner and breakpoint messages     |

### Priority order

Settings are prioritised in this order, from lowest to highest priority:

1. Built-in defaults (always present)
2. Config file (`~/.config/sild/sild.cfg` or `--config`)
3. Command-line flags (`--lines`, `--columns`, `--width`)

---

## Useful Notes

`rlwrap` can be used to enable command history:
```sh
alias sild='rlwrap sild'
```

## TODO:
### Do all `'-- TODO'` items
- `lua_src/main.lua`
```
27:-- TODO: Look for annotations in require'd files
28:local breakpoints_list, actions_list = parse.annotations(cli.script_path)
```

```
43:  -- TODO: use XDG_CONFIG_HOME here
42: print(ansi.color_dim("n=step  c=continue  ?=help  q=quit") .. "  " ..
43:   -- TODO: use XDG_CONFIG_HOME here
  ansi.color_dim("config: " .. (cli.config_file or (os.getenv("HOME") or "~") .. "/.config/sild/sild.cfg")) .. "\n")
```

- `lua_src/sild/commands.lua`
```
10: local function print_help()
11:  local function row(cmd, desc)
12:    print("  " .. ansi.color_value(ansi.fit(cmd, 28)) .. "  " .. desc)
13:  end
14:  -- TODO: Fit to screen width
15:  print()
16:  print(ansi.color_bold("-- Navigation ------------------"))
```

- `lua_src/sild/config.lua`
```
31:-- TODO: Replace all this if-elseing with tables of handlers
32:function M.parse_file(path)
```

- `lua_src/sild/ui.lua`
```
8:-- TODO: Make part of config
9:local SPLIT_POSITION = 0.35
```

### Add `.editorconfig` instead of using global format styles

### Add MacOS target
- `flake.nix`
```
let
  # TODO: Add x86_64-darwin and aarch64-darwin
  buildTargets = {
```

### callchart - print a bar chart out of call data

### PgUp PgDn to scroll code window

### Fix `auto_size` toggle
- `lua_src/sild/config.lua`
```
local config = {
  -- layout
  auto_size        = true,
```

### Luac detection (maybe decomp support?)

### `parse.lua` is only about file parsing, maybe rename?

### EmmyLua document all functions

### Hex code colour support

### Improve error messages for target scripts

### Have the program name and description set in rust (even possibly cargo)

### Allow debugging more than just scripts, be able to descend layers

### 'vars' is not comprehensive, modify how it chooses

### Fix partially broken watch annotations

### See if highlight works with multiline strings and longer floating point numbers like (123.456)
  Also doesn't handle multiline comments and string escape sequences
  
### These appear at start of debugging program, see if we can skip them
  ```sh
  [sild.debugger:174]
  [main.lua:47]
  ```