Initial Commit main

1 files changed, 276 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..62dcb22
--- /dev/null
+++ b/README.md
@@ -0,0 +1,276 @@
+# 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]
+  ```