mq-dap 0.8.3

Debug Adapter Protocol implementation for mq
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

<h1 align="center">mq-dap</h1>

Debug Adapter Protocol implementation for mq.

## Usage

### Command Line

Start the DAP server (typically done automatically by your editor):

```bash
# Start the DAP server
mq-dbg

# Debug a specific query file
mq-dbg query.mq input.md
```

### Debugging Features

Once connected to a DAP client:

1. **Set Breakpoints**: Click in the gutter or use your editor's breakpoint command
2. **Conditional Breakpoints**: Only stop when an mq expression evaluates truthy, e.g. `x > 3`
3. **Hit Count Breakpoints**: Only stop once the hit count condition is met. A bare number, e.g. `3`, is shorthand for `hit_count >= 3`; otherwise it's evaluated as an mq expression with `hit_count` bound to the current hit count, e.g. `hit_count >= 3 && x == 1`
4. **Logpoints**: Log a message instead of stopping; uses mq's own `${expr}` string interpolation syntax, e.g. `x is ${x}`. `${self}` yields the current pipeline value and `${$VAR}` reads the environment variable `VAR`
5. **Exception Breakpoints**: Enable "Uncaught Exceptions" in your editor's breakpoints pane to automatically pause when a query raises an error that isn't caught by `try`/`catch`
6. **Start Debugging**: Launch the debugger with your query file
7. **Step Through Code**: Use step over, step in, and step out commands
8. **Inspect Variables**: Hover over variables or view them in the variables pane
9. **Watch Expressions**: Add mq expressions to your editor's watch pane to re-evaluate them against the current scope every time execution stops
10. **View Call Stack**: See the current execution stack in the call stack pane

### Example Debug Session

```sh
# Create a query file
echo '.h | let y = to_text() | breakpoint() | y' > query.mq

# Start debugging
mq-dbg query.mq input.md
```

## Development

### Building from Source

```sh
git clone https://github.com/harehare/mq
cd mq
cargo build --release -p mq-dap
```

### Running Tests

```sh
cargo test -p mq-dap
```

## Support

- 🐛 [Report bugs](https://github.com/harehare/mq/issues)
- 💡 [Request features](https://github.com/harehare/mq/issues)
- 📖 [Read the documentation](https://mqlang.org/book/)

## License

Licensed under the MIT License.