From 63774b36dc7bce1f56b75553a705dce0c97fb2f4 Mon Sep 17 00:00:00 2001
From: Thomas Voss <mail@thomasvoss.com>
Date: Fri, 20 Oct 2023 21:40:50 +0200
Subject: Document reader.go

---
 parser/reader.go | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/parser/reader.go b/parser/reader.go
index 6b077fc..28cbe3d 100644
--- a/parser/reader.go
+++ b/parser/reader.go
@@ -9,16 +9,23 @@ import (
 	"unicode/utf8"
 )
 
+// position represents the current position of the reader in the buffer.  It has
+// both a row and column, as well as a previous column.  We need that previous
+// column to figure out our position when backtracking with reader.unreadRune().
 type position struct {
 	col     uint
 	row     uint
 	prevCol uint
 }
 
+// String returns the position of the last-processed rune in the buffer in the
+// standard ‘row:col’ format, while starting at 1:1 to be vim-compatible.
 func (p position) String() string {
 	return fmt.Sprintf("%d:%d", p.row+1, p.col)
 }
 
+// reader represents the actual parser.  It has both an underlying buffered
+// reader, and a position.
 type reader struct {
 	r   *bufio.Reader
 	pos position
@@ -39,6 +46,10 @@ func (reader *reader) peekRune() (rune, error) {
 	return r, nil
 }
 
+// unreadRune moves the parser one rune back, allowing for basic backtracking.
+// You can only safely call reader.unreadRune() once before reading again.  If
+// not you will risk messing up the parsers position tracking if you unread
+// multiple newlines.
 func (reader *reader) unreadRune() error {
 	if reader.pos.col == 0 {
 		reader.pos.col = reader.pos.prevCol
@@ -50,6 +61,8 @@ func (reader *reader) unreadRune() error {
 	return reader.r.UnreadRune()
 }
 
+// readRune reads and returns the next rune in the readers buffer.  It is just a
+// wrapper around ‘reader.r.ReadRune()’ that updates the readers position.
 func (reader *reader) readRune() (rune, error) {
 	r, _, err := reader.r.ReadRune()
 	if r == '\n' {
@@ -62,6 +75,8 @@ func (reader *reader) readRune() (rune, error) {
 	return r, err
 }
 
+// readNonSpaceRune is identical to reader.readRune(), except it skips any runes
+// representing spaces (as defined by unicode).
 func (reader *reader) readNonSpaceRune() (rune, error) {
 	if err := reader.skipSpaces(); err != nil {
 		return 0, err
@@ -70,6 +85,9 @@ func (reader *reader) readNonSpaceRune() (rune, error) {
 	return reader.readRune()
 }
 
+// skipSpaces moves the parser forwards so that the next call to
+// ‘reader.readRune()’ is guaranteed to read a non-space rune as defined by
+// Unicode.
 func (reader *reader) skipSpaces() error {
 	for {
 		if r, err := reader.readRune(); err != nil {
-- 
cgit v1.2.3