Option sets: a .o target for shared parameters
A named group of optional parameters, declared once and used by several
klammers, so a writer learns one vocabulary instead of a spelling per
klammer. The "o" target is a pseudo-target beside "k": "k" declares a
klammer's interface and documents it, "o" declares an option interface and
documents it, and neither produces output for any target.
@@caption_args.o :caption :number.bool true :caption_side.side
: Arguments that define a caption for a block element @@
@@code.k :filename @hpos_args :hpos left @ @caption_args :caption_side top @
| text.literal : A source file displayed verbatim @@
A set is used only in the parameter list of a ".k" declaration -- the one
place a klammer's interface is declared once for all of its targets -- and
is resolved as that list is read. Names and types come from the set; a
default may be overridden where it is used. A klammer application in a
parameter list is now a definition-time error.
The SKS gains the sets caption_args and hpos_args (:hpos and :offset), and
@table, @image, @image_grid, @reference and @show gain .k declarations. A
distance is no longer written as a position: :hpos 4em is rejected, and the
same layout is :hpos left :offset 4em. Code listings are numbered by
default, like tables and figures.
New engine sources mac/option_set{,_registry}.{h,cpp}; tst/ ships two more
suites, option_set_test.sh and signature_test.sh (twelve in all).
(from dev 34e536cb0329)
This commit is contained in:
143
tst/signature_test.sh
Executable file
143
tst/signature_test.sh
Executable file
@@ -0,0 +1,143 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# signature_test.sh — one klammer, one interface (engine suite, tst/).
|
||||
#
|
||||
# A klammer may be defined separately for each target. When it is, every
|
||||
# target's definition carries its own parameter list, and those lists must
|
||||
# agree: a klammer's interface is a property of the KLAMMER, not of the
|
||||
# target it is being rendered to. If they disagree, the same document would
|
||||
# bind arguments differently — or fail — depending only on the target, which
|
||||
# is exactly the thing an author must be able to rely on not happening.
|
||||
#
|
||||
# The engine enforces this rather than warning about it, and the remedy it
|
||||
# names is the .k declaration: declare the parameters once, and give each
|
||||
# target a "::" instance with no parameter list of its own. That is the
|
||||
# migration from repeating an argument list per target to declaring it once.
|
||||
#
|
||||
# These are engine tests, so they use -k none and define their own targets
|
||||
# inline: a target is a Machine construct (@@@target), not owned by any
|
||||
# klammer set.
|
||||
#
|
||||
# Usage: ./signature_test.sh (needs KLAMMERTEXT_HOME set; ktext on PATH)
|
||||
# Exit code: 0 if all tests pass, 1 otherwise.
|
||||
|
||||
PASS=0
|
||||
FAIL=0
|
||||
KTEXT=ktext
|
||||
K=${KLAMMERTEXT_HOME:?KLAMMERTEXT_HOME must be set}
|
||||
|
||||
red=$'\033[31m'
|
||||
green=$'\033[32m'
|
||||
bold=$'\033[1m'
|
||||
reset=$'\033[0m'
|
||||
|
||||
pass() { echo "${green}PASS${reset} $1"; PASS=$((PASS+1)); }
|
||||
fail() {
|
||||
echo "${red}FAIL${reset} $1"
|
||||
echo " expected: $2"
|
||||
echo " got: $3"
|
||||
FAIL=$((FAIL+1))
|
||||
}
|
||||
|
||||
TARGETS='@@@target ta | Target A @@@
|
||||
@@@target tb | Target B @@@
|
||||
'
|
||||
|
||||
# accepted NAME SRC — the definitions are consistent and the klammer applies.
|
||||
accepted() {
|
||||
local name="$1" src="$2" out
|
||||
out=$("$KTEXT" -k none -s "$TARGETS$src" -t ta -d 2>&1)
|
||||
if echo "$out" | grep -qi "error"; then
|
||||
fail "$name" "no error" "$(echo "$out" | grep -i -A1 error | tail -1)"
|
||||
else
|
||||
pass "$name"
|
||||
fi
|
||||
}
|
||||
|
||||
# rejected NAME SRC PATTERN — the drift is caught, and the message says how.
|
||||
rejected() {
|
||||
local name="$1" src="$2" want="$3" out
|
||||
out=$("$KTEXT" -k none -s "$TARGETS$src" -t ta -d 2>&1)
|
||||
if ! echo "$out" | grep -qi "error"; then
|
||||
fail "$name" "a definition error" "accepted"
|
||||
elif ! echo "$out" | grep -qF "$want"; then
|
||||
fail "$name" "message containing: $want" "$(echo "$out" | head -6 | tail -3)"
|
||||
else
|
||||
pass "$name"
|
||||
fi
|
||||
}
|
||||
|
||||
echo "${bold}Klammer signature consistency${reset}"
|
||||
echo "============================="
|
||||
echo
|
||||
|
||||
accepted " 1. identical parameter lists" \
|
||||
'@@k1.ta s :n : [*s*] @@
|
||||
@@k1.tb s :n : [*s*] @@
|
||||
@k1 x @'
|
||||
|
||||
rejected " 2. positional names differ" \
|
||||
'@@k2.ta s : [*s*] @@
|
||||
@@k2.tb t : [*t*] @@
|
||||
@k2 x @' 'are not the same for every target'
|
||||
|
||||
rejected " 3. option names differ" \
|
||||
'@@k3.ta s :one : [*s*] @@
|
||||
@@k3.tb s :two : [*s*] @@
|
||||
@k3 x @' 'are not the same for every target'
|
||||
|
||||
rejected " 4. defaults differ" \
|
||||
'@@k4.ta s :n abc : [*s*] @@
|
||||
@@k4.tb s :n xyz : [*s*] @@
|
||||
@k4 x @' 'are not the same for every target'
|
||||
|
||||
rejected " 5. argument types differ" \
|
||||
'@@k5.ta s :n.int : [*s*] @@
|
||||
@@k5.tb s :n.word : [*s*] @@
|
||||
@k5 x @' 'are not the same for every target'
|
||||
|
||||
echo
|
||||
echo "-- the message must show HOW they differ, not just where"
|
||||
|
||||
# With more than two targets the designer would otherwise have to diff the
|
||||
# definitions by hand; each target's own signature is listed beside its name.
|
||||
name=" 6. each target's signature is shown"
|
||||
out=$("$KTEXT" -k none -s "$TARGETS"'@@k6.ta s :one : [*s*] @@
|
||||
@@k6.tb s :two : [*s*] @@
|
||||
@k6 x @' -t ta -d 2>&1)
|
||||
if echo "$out" | grep -q "ta .*s :one" && echo "$out" | grep -q "tb .*s :two"; then
|
||||
pass "$name"
|
||||
else
|
||||
fail "$name" "both signatures listed by target" "$(echo "$out" | head -8 | tail -4)"
|
||||
fi
|
||||
|
||||
# The error path once printed internal katom detail through msg(), which is
|
||||
# debugging scaffolding and must never reach a user-facing message.
|
||||
name=" 7. no internal debug output on the error path"
|
||||
out=$("$KTEXT" -k none -s "$TARGETS"'@@k7.k s : a declaration @@
|
||||
@@k7.ta s2 :other : [*s2*] @@
|
||||
@k7 x @' -t ta -d 2>&1)
|
||||
if echo "$out" | grep -q "klammer-definition"; then
|
||||
fail "$name" "no internal dump" "$(echo "$out" | head -2)"
|
||||
else
|
||||
pass "$name"
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "-- the remedy the message names"
|
||||
|
||||
accepted " 8. a .k declaration with :: instances" \
|
||||
'@@k8.k s :n : a declaration @@
|
||||
@@k8.ta :: [*s*] @@
|
||||
@@k8.tb :: [*s*] @@
|
||||
@k8 x @'
|
||||
|
||||
rejected " 9. a .k declaration plus a parameterized definition" \
|
||||
'@@k9.k s : a declaration @@
|
||||
@@k9.ta s2 :other : [*s2*] @@
|
||||
@k9 x @' 'both a declaration'
|
||||
|
||||
echo
|
||||
echo "============================="
|
||||
echo "Results: ${green}$PASS passed${reset}, ${red}$FAIL failed${reset}"
|
||||
[ $FAIL -eq 0 ]
|
||||
Reference in New Issue
Block a user