document.bash

## document.bash: parsing a testmark document, and reading its hunks.
## Sourced by testmark.bash; the functions here assume they run inside `_testmark_call`.
# shellcheck disable=SC2034,SC2178 # shellcheck does not follow namerefs: writes through them look unused, and reusing a name as one looks like an array turned string

# Storage: a document's state lives only in globals named after its handle, `_testmark_KIND_HANDLE`, one per kind in _testmark_kinds:
#   lines        indexed: the lines, each keeping its "\n" (a file's last line may lack one), CRLF made LF
#   start, end   assoc by hunk name: the body's line range [start, end) in lines
#   info         assoc by hunk name: the info string
#   names        the hunk names in document order, each ending in "\n"
#   pid          $BASHPID at parse, for refusing state changes from a subshell
#   file         the file's absolute path, so a `cd` after parse can't send testmark_write elsewhere
#   patch        assoc by hunk name: what testmark_write puts in place of the opener and body lines, [start - 1, end)
#   checked      assoc by hunk name: the output testmark_check first saw, so a second, different one is an error
# So forgetting a handle is one `unset` per kind, and nothing else needs cleaning up.
# Variable names are built only from handles that pass _testmark_handle, and kinds have no "_", so two handles' variables never meet.
# Hunk names come from documents and may contain shell syntax, so name-keyed elements are touched only as "Using assoc arrays safely" in docs/hacking/bash-pitfalls.md allows.
_testmark_kinds=(lines start end info names pid file patch checked)

_testmark_err() {
	>&2 printf 'testmark: %s\n' "$1"
}

## Prints an error about hunk $2 of document $1, which must both exist: "testmark: FILE:LINE: hunk "NAME": $3".
## LINE is the hunk's annotation line, so a reader can go straight to it.
_testmark_hunk_err() {
	local -n file=_testmark_file_$1 start=_testmark_start_$1
	_testmark_err "$file:$((start[$2] - 1)): hunk \"$2\": $3"
}

## Fails with a message unless $1 is a valid handle.
_testmark_handle() {
	[[ -n $1 && $1 != *[!A-Za-z0-9_]* ]] || {
		_testmark_err "invalid handle \"$1\": must match [A-Za-z0-9_]+"
		return 1
	}
}

_testmark_parse() {
	(($# == 2)) || {
		_testmark_err "usage: testmark_parse HANDLE FILE"
		return 1
	}
	local h=$1 file=$2 kind
	_testmark_handle "$h" || return 1
	for kind in "${_testmark_kinds[@]}"; do unset -v "_testmark_${kind}_$h"; done
	local -a lines
	# See "use blocks to open an fd and check properties on it without TOCTOU" in docs/hacking/bash-pitfalls.md.
	# The 2>/dev/null comes before the <, so it also hides bash's message when the open fails; ours is printed instead.
	{ [[ ! -d /dev/stdin ]] && mapfile lines; } 2>/dev/null <"$file" || {
		_testmark_err "$file: not a readable file"
		return 1
	}

	# State: `open` while inside a code block; `k` from an annotation until its hunk closes; `at` is the line number of the annotation or opener.
	local -A start=() end=() info=()
	local i line name names='' open='' k='' at=''
	for ((i = 0; i < ${#lines[@]}; i++)); do
		line=${lines[i]}
		# A line without its "\n" is the last line, or was cut at a NUL; read -d '' tells which.  See "NUL bytes vanish unless you check for them" in docs/hacking/bash-pitfalls.md.
		if [[ $line != *$'\n' ]] && IFS= read -r -d '' _ <"$file"; then
			_testmark_err "$file:$((i + 1)): contains a NUL byte"
			return 1
		fi
		if [[ $line == *$'\r\n' ]]; then
			line=${line%$'\r\n'}
			lines[i]=$line$'\n'
		else
			line=${line%$'\n'}
		fi

		if [[ -n $open ]]; then
			if [[ $line == '```'* ]]; then
				[[ -z $k ]] || end[$k]=$i
				open='' k=''
			fi
		elif [[ -n $k ]]; then
			[[ $line == '```'* ]] || {
				_testmark_err "$file:$at: annotation not followed by a code block"
				return 1
			}
			line=${line#'```'}
			# Trim: strip the leading run of whitespace, then the trailing one.
			line=${line#"${line%%[![:space:]]*}"}
			info[$k]=${line%"${line##*[![:space:]]}"}
			start[$k]=$((i + 1))
			open=1 at=$((i + 1))
		elif [[ $line == '```'* ]]; then
			open=1 at=$((i + 1))
		elif [[ $line == '[testmark]:#'* ]]; then
			name=${line#'[testmark]:# ('}
			name=${name%')'}
			# The name is the first word: skip leading whitespace, then stop at the next.
			name=${name#"${name%%[![:space:]]*}"}
			name=${name%%[[:space:]]*}
			if [[ $line != '[testmark]:# ('*')' || -z $name ]]; then
				_testmark_err "$file:$((i + 1)): malformed annotation; want \"[testmark]:# (name)\""
				return 1
			fi
			k=$name
			[[ -z ${start[$k]+set} ]] || {
				_testmark_err "$file:$((i + 1)): duplicate hunk name \"$k\""
				return 1
			}
			names+=$k$'\n'
			at=$((i + 1))
		fi
	done
	if [[ -n $open ]]; then
		_testmark_err "$file:$at: code block not closed"
		return 1
	fi
	[[ -z $k ]] || {
		_testmark_err "$file:$at: annotation not followed by a code block"
		return 1
	}

	# Parsed without error; only now are globals written.
	# Assoc kinds are declared first; see "assoc arrays must be declared as such" in docs/hacking/bash-pitfalls.md.
	declare -gA "_testmark_start_$h" "_testmark_end_$h" "_testmark_info_$h" "_testmark_patch_$h" "_testmark_checked_$h"
	local -n g_lines=_testmark_lines_$h g_start=_testmark_start_$h g_end=_testmark_end_$h g_info=_testmark_info_$h
	local -n g_names=_testmark_names_$h g_pid=_testmark_pid_$h g_file=_testmark_file_$h g_patch=_testmark_patch_$h g_checked=_testmark_checked_$h
	g_lines=("${lines[@]}")
	for name in "${!start[@]}"; do g_start[$name]=${start[$name]} g_end[$name]=${end[$name]} g_info[$name]=${info[$name]}; done
	g_names=$names g_pid=$BASHPID
	g_file=$file
	[[ $file == /* ]] || g_file=$PWD/$file
	# Assigned, not just declared: set -u counts a declared but never assigned array as unset.
	g_patch=() g_checked=()
}

## Fails with a message unless $1 is the handle of a parsed document.
_testmark_doc() {
	_testmark_handle "$1" || return 1
	[[ -v _testmark_pid_$1 ]] || {
		_testmark_err "unknown handle \"$1\""
		return 1
	}
}

## Fails with a message unless $1 is the handle of a parsed document with a hunk named $2.
_testmark_hunk() {
	_testmark_doc "$1" || return 1
	local -n start=_testmark_start_$1
	[[ -n ${start[$2]+set} ]] || {
		local -n file=_testmark_file_$1
		_testmark_err "$file: no hunk named \"$2\""
		return 1
	}
}

_testmark_names() {
	(($# == 1)) || {
		_testmark_err "usage: testmark_names HANDLE"
		return 1
	}
	_testmark_doc "$1" || return 1
	local -n names=_testmark_names_$1
	printf '%s' "$names"
}

_testmark_body() {
	(($# == 2)) || {
		_testmark_err "usage: testmark_body HANDLE NAME"
		return 1
	}
	_testmark_hunk "$1" "$2" || return 1
	local body
	_testmark_get_body "$1" "$2"
	printf '%s' "$body"
}

## Sets the caller's local `body` to the body of hunk $2 in document $1, which must both exist.
_testmark_get_body() {
	local -n lines=_testmark_lines_$1 start=_testmark_start_$1 end=_testmark_end_$1
	local i=${start[$2]} last=${end[$2]}
	body=
	for (( ; i < last; i++)); do body+=${lines[i]}; done # not a slice; see "Quadratic operations" in docs/hacking/bash-pitfalls.md
}

_testmark_info() {
	(($# == 2)) || {
		_testmark_err "usage: testmark_info HANDLE NAME"
		return 1
	}
	_testmark_hunk "$1" "$2" || return 1
	local -n info=_testmark_info_$1
	printf '%s\n' "${info[$2]}"
}