From 66aef5a362d9b006748b020966c8cf7fbcf0d558 Mon Sep 17 00:00:00 2001
From: pompolic <pompolic@special-circumstanc.es>
Date: Thu, 23 Jun 2022 20:20:56 +0200
Subject: [PATCH] Documentation for hammer-parse-step-to-result

---
 gdb-port/README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/gdb-port/README.md b/gdb-port/README.md
index c7ba895..cc3c651 100644
--- a/gdb-port/README.md
+++ b/gdb-port/README.md
@@ -88,6 +88,19 @@ Steps execution until the "current" parser (the one `h_do_parse()` has been call
 
 In terms of call stack navigation, this is roughly analogous to executing `finish` to step out of the current stack frame, followed by stepping into the next function call. (With the difference, that this commands steps between "frames" of the parser stack)
 
+```
+hammer-parse-step-to-result <number>
+```
+
+Select a parser on the stack, step to when it returns its result, and print it.
+
+`<number>` select a parser on the parser stack according to the following rules:
+- If zero, the the "current" parser (which `h_do_parse` is about to apply) is selected
+- If positive, the selected parser will be `<number>`th item from the top of the stack (with the "current" parser being 0)
+- If negative, parsers are counted from the bottom of the stack, with the bottom of the stack being -1. Note: positive is 0-indexed, negative is 1-indexed
+
+This command will step until the selected `h_do_parse` frame returns its value. If applicable, it extracts the AST returned, and prints it. Afterwards, it will step to the next `h_do_parse` invocation. (This corresponds to stepping until the next time the parser stack grows in size, for example from a parser combinator applying its constituent parsers. For example: after selecting an element of a `h_sequence()` combinator for printing AST results, execution will stop when the next element of said sequence is about to be applied.)
+
 ## Querying
 
 ```
-- 
GitLab