From c5c95477c9297310ce641f1f7f41ecc4facd4351 Mon Sep 17 00:00:00 2001
From: Robin Stocker <robin@nibor.org>
Date: Mon, 21 Oct 2024 22:37:38 +1100
Subject: [PATCH] README: Add source positions section

---
 README.md                                     | 25 +++++++++++++++++++
 .../org/commonmark/test/UsageExampleTest.java | 16 ++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 717db7c9..d803f32d 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,31 @@ class WordCountVisitor extends AbstractVisitor {
 }
 ```
 
+#### Source positions
+
+If you want to know where a parsed `Node` appeared in the input source text,
+you can request the parser to return source positions like this:
+
+```java
+var parser = Parser.builder().includeSourceSpans(IncludeSourceSpans.BLOCKS_AND_INLINES).build();
+```
+
+Then parse nodes and inspect source positions:
+
+```java
+var source = "foo\n\nbar *baz*";
+var doc = parser.parse(source);
+var emphasis = doc.getLastChild().getLastChild();
+var s = emphasis.getSourceSpans().get(0);
+s.getLineIndex();    // 2 (third line)
+s.getColumnIndex();  // 4 (fifth column)
+s.getInputIndex();   // 9 (string index 9)
+s.getLength();       // 5
+source.substring(s.getInputIndex(), s.getInputIndex() + s.getLength());  // "*baz*"
+```
+
+If you're only interested in blocks and not inlines, use `IncludeSourceSpans.BLOCKS`.
+
 #### Add or change attributes of HTML elements
 
 Sometimes you might want to customize how HTML is rendered. If all you
diff --git a/commonmark/src/test/java/org/commonmark/test/UsageExampleTest.java b/commonmark/src/test/java/org/commonmark/test/UsageExampleTest.java
index 1ffb7b64..1bff79a2 100644
--- a/commonmark/src/test/java/org/commonmark/test/UsageExampleTest.java
+++ b/commonmark/src/test/java/org/commonmark/test/UsageExampleTest.java
@@ -1,6 +1,7 @@
 package org.commonmark.test;
 
 import org.commonmark.node.*;
+import org.commonmark.parser.IncludeSourceSpans;
 import org.commonmark.parser.Parser;
 import org.commonmark.renderer.NodeRenderer;
 import org.commonmark.renderer.html.*;
@@ -58,6 +59,21 @@ public void visitor() {
         assertEquals(4, visitor.wordCount);
     }
 
+    @Test
+    public void sourcePositions() {
+        var parser = Parser.builder().includeSourceSpans(IncludeSourceSpans.BLOCKS_AND_INLINES).build();
+
+        var source = "foo\n\nbar *baz*";
+        var doc = parser.parse(source);
+        var emphasis = doc.getLastChild().getLastChild();
+        var s = emphasis.getSourceSpans().get(0);
+        assertEquals(2, s.getLineIndex());
+        assertEquals(4, s.getColumnIndex());
+        assertEquals(9, s.getInputIndex());
+        assertEquals(5, s.getLength());
+        assertEquals("*baz*", source.substring(s.getInputIndex(), s.getInputIndex() + s.getLength()));
+    }
+
     @Test
     public void addAttributes() {
         Parser parser = Parser.builder().build();