Merge pull request #232 from Pat-Lafon/main

Richer Source Positions

Author: sampsyo

docs/lang/syntax.md

@@ -124,11 +124,14 @@ It also has the optional `args`, `funcs`, and `labels` fields.
 Source Positions
 ----------------
 
-Any syntax object may optionally have a `pos` field to reflect a source position:
+Any syntax object may optionally have position fields to reflect a source position:
 
-    { ..., "pos": {"row": <int>, "col": <int>} }
+    { ..., "pos": {"row": <int>, "col": <int>},
+           "pos_end": {"row": <int>, "col": <int>}?,
+           "src": "<string>"? }
 
-The `pos` object has two keys: `row` (the line number) and `col` (the column number within the line).
+The `pos` and `pos_end` objects have two keys: `row` (the line number) and `col` (the column number within the line). The `src` object can optionally provide the absolute path to a file which is referenced to by the source position.
+If `pos_end` is provided, it must be equal to or greater than `pos`.
 Front-end compilers that generate Bril code may add this information to help with debugging.
 The [text format parser](../tools/text.md), for example, can optionally add source positions.
 However, tools can't require positions to exist, to consistently exist or not on all syntax objects in a program, or to follow any particular rules.