gdharness 1.1.13 → 1.1.14

package/build/godot/addons/gdharness_runtime/runtime_queries.gd

@@ -5,6 +5,7 @@ extends RefCounted
 
 const Paths = preload("runtime_paths.gd")
 const Read = preload("reading.gd")
+const Says = preload("runtime_says.gd")
 const Screen = preload("runtime_screen.gd")
 const Values = preload("runtime_values.gd")
 const Words = preload("runtime_words.gd")
@@ -103,13 +104,13 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	var truncated: bool = false
 	# Counted while the tree is already being walked, for the answer below: how many nodes this
 	# find would have matched if the name had been read the way it was probably meant.
-	var literal: bool = _is_literal(wanted["name"])
+	var literal: bool = Says.is_plain(wanted["name"])
 	var nearly: int = 0
 	# The same for the words: a glob is matched against the whole text, and one written as a prefix
 	# by habit, "Taken together*", missed the label whose sentence those words are in the middle of.
 	# Nothing found then read as the words not being on screen, which is the wrong conclusion when
 	# checking that a change to the text landed.
-	var widened_says: String = _widened(wanted["says"])
+	var widened_says: String = Says.widened(wanted["says"])
 	var widened: Dictionary[String, String] = {}
 	for filter: String in wanted:
 		widened[filter] = widened_says if filter == "says" else wanted[filter]
@@ -241,50 +242,6 @@ static func _named(node: Node, pattern: String) -> bool:
 	return pattern.is_empty() or str(node.name).matchn(pattern)
 
 
-## Whether [param pattern] is a name written as a whole word rather than as a glob, which is how a
-## caller writes one when they mean "contains". [method String.matchn] answers nothing to it, and
-## nothing is also what a name that is simply not there answers.
-static func _is_literal(pattern: String) -> bool:
-	return not pattern.is_empty() and not pattern.contains("*") and not pattern.contains("?")
-
-
-## Whether [param said] is what a find asked for in [param wanted].
-##
-## A plain word is a contains, which is what somebody looking for the row about a person means. A
-## pattern is a glob, because [code]namePattern[/code] beside it is one and nobody writes `*Still*`
-## in one field meaning a glob and in the other meaning those characters. Written as a contains
-## only, a glob matched nothing at all and an empty answer reads as a control that is not on the
-## screen: twice in one session here, over a button that was.
-static func _says(said: String, wanted: String) -> bool:
-	var words: String = as_said(wanted)
-	return said.containsn(words) if _is_literal(words) else said.matchn(words)
-
-
-## Whether [param node]'s own words are what [param wanted] asks for, by the rules a find uses, so a
-## click that names its control by its words finds the one a find would have answered with.
-static func says(node: Node, wanted: String) -> bool:
-	return _says(Words.said_by(node), wanted)
-
-
-## [param wanted], a glob, open at both ends so it matches its words anywhere in a text; "" when
-## it is not a glob, or already open at both ends, and so has nothing to suggest.
-static func _widened(wanted: String) -> String:
-	if wanted.is_empty() or _is_literal(wanted):
-		return ""
-	var open: String = "*" + wanted.lstrip("*").rstrip("*") + "*"
-	return "" if open == wanted else open
-
-
-## [param wanted] as words on a screen: a backslash followed by n is a line break.
-##
-## A button with two lines on it was asked for with the break written as the two characters, the
-## way it is typed into a JSON string one escape short, and was answered as not there: 0 found,
-## which reads as a control that is not on the screen. Nothing on a screen says a backslash and
-## an n, so the two characters mean the break to everybody who writes them.
-static func as_said(wanted: String) -> String:
-	return wanted.replace("\\n", "\n")
-
-
 ## Every filter but the name, so a find that came back empty can say how many nodes the name was
 ## the only thing standing between it and.
 func _matches_apart_from_name(node: Node, wanted: Dictionary[String, String]) -> bool:
@@ -293,7 +250,7 @@ func _matches_apart_from_name(node: Node, wanted: Dictionary[String, String]) ->
 	# What this node says, rather than everything said underneath it. A row is then found by the
 	# label in it, and the path answered is that label's, which is where the words a caller is
 	# looking at actually are: matching every container above it would answer with the screen.
-	if not wanted["says"].is_empty() and not _says(Words.said_by(node), wanted["says"]):
+	if not wanted["says"].is_empty() and not Says.says(node, wanted["says"]):
 		return false
 	var script: Variant = node.get_script()
 	if not wanted["script"].is_empty():
@@ -327,10 +284,6 @@ static func _script_is(attached: Script, wanted: String) -> bool:
 	return false
 
 
-## Where a node is on screen: a Control's rectangle, a Node2D's position, or the place a 3D node
-## is drawn in, in both the canvas coordinates the node reports and the window pixels input
-## arrives in. The two differ whenever the project stretches its viewport, which is what made a
-## rect unusable for a click.
 ## Every line of text under a node, in the order somebody reads the screen.
 ##
 ## The question a caller asks most often, and the one that cost the most to answer: reading a panel
@@ -414,6 +367,10 @@ static func _drawn(node: Node) -> bool:
 	return window == null or window.visible
 
 
+## Where a node is on screen: a Control's rectangle, a Node2D's position, or the place a 3D node
+## is drawn in, in both the canvas coordinates the node reports and the window pixels input
+## arrives in. The two differ whenever the project stretches its viewport, which is what made a
+## rect unusable for a click.
 func get_rect(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	if node_path.is_empty():

package/build/godot/addons/gdharness_runtime/runtime_says.gd

@@ -0,0 +1,97 @@
+extends RefCounted
+
+## Whether a node says what a caller asked for in `says`: the one set of rules a find, a click and a
+## wait all match words by, so the three never disagree about which control a word names.
+
+const Words = preload("runtime_words.gd")
+
+## Stands in for a bar written as `\|` while `says` is split into its alternatives: a character from
+## the private use area, which no game's text uses.
+const ESCAPED_BAR: String = ""
+
+## How many splits [method alternatives] keeps. A find asks about two at once, the words it was given
+## and the same words widened, and anything past a handful is a caller that has moved on.
+const SPLITS_KEPT: int = 8
+
+## Each `says` split into alternatives, by what was written; see [method alternatives].
+static var _splits: Dictionary[String, Array] = {}
+
+
+## Whether [param node]'s own words are what [param wanted] asks for.
+static func says(node: Node, wanted: String) -> bool:
+	return matches(Words.said_by(node), wanted)
+
+
+## Whether [param said] is what [param wanted] asks for.
+##
+## A plain word is a contains, which is what somebody looking for the row about a person means. A
+## pattern is a glob, because [code]namePattern[/code] beside it is one and nobody writes `*Still*`
+## in one field meaning a glob and in the other meaning those characters. Written as a contains
+## only, a glob matched nothing at all and an empty answer reads as a control that is not on the
+## screen: twice in one session here, over a button that was.
+##
+## Several alternatives separated by `|` match when any one of them does, each by those rules: a
+## wait for the end of a turn is a wait for whichever of "won", "lost" or the next turn's words comes
+## first, and read as one glob with the bars in it, it waited out its whole timeout for words no
+## screen says.
+static func matches(said: String, wanted: String) -> bool:
+	for words: String in alternatives(wanted):
+		if said.containsn(words) if is_plain(words) else said.matchn(words):
+			return true
+	return false
+
+
+## The alternatives [param wanted] names, each as words on a screen: split at every `|` not written
+## as `\|`, which stays a bar in the words. An empty alternative, a stray bar at either end, is
+## dropped: it names no words, and a find that came back empty widened it to `**` and suggested a
+## pattern that matches every node there is.
+##
+## Kept once split, since a find, a click or a wait asks about the same words for every node on the
+## screen: split afresh for each of them, one look over a hall of twenty thousand nodes took 210ms
+## rather than 155ms. The array handed back is shared and not to be changed.
+static func alternatives(wanted: String) -> Array[String]:
+	var kept: Variant = _splits.get(wanted)
+	if kept != null:
+		var split: Array[String] = kept
+		return split
+	var held: String = as_said(wanted).replace("\\|", ESCAPED_BAR)
+	var found: Array[String] = []
+	for part: String in held.split("|"):
+		var words: String = part.replace(ESCAPED_BAR, "|")
+		if not words.is_empty():
+			found.append(words)
+	if _splits.size() >= SPLITS_KEPT:
+		_splits.clear()
+	_splits[wanted] = found
+	return found
+
+
+## Whether [param pattern] is words written whole rather than as a glob, which is how a caller
+## writes them when they mean "contains". [method String.matchn] answers nothing to it, and nothing
+## is also what words that are simply not there answer.
+static func is_plain(pattern: String) -> bool:
+	return not pattern.is_empty() and not pattern.contains("*") and not pattern.contains("?")
+
+
+## [param wanted], a glob, open at both ends so it matches its words anywhere in a text; "" when
+## it is not a glob, or already open at both ends, and so has nothing to suggest.
+static func widened(wanted: String) -> String:
+	var open_ended: Array[String] = []
+	var changed: bool = false
+	for words: String in alternatives(wanted):
+		var open: String = words
+		if not is_plain(words):
+			open = "*" + words.lstrip("*").rstrip("*") + "*"
+			changed = changed or open != words
+		open_ended.append(open.replace("|", "\\|"))
+	return "|".join(open_ended) if changed else ""
+
+
+## [param wanted] as words on a screen: a backslash followed by n is a line break.
+##
+## A button with two lines on it was asked for with the break written as the two characters, the
+## way it is typed into a JSON string one escape short, and was answered as not there: 0 found,
+## which reads as a control that is not on the screen. Nothing on a screen says a backslash and
+## an n, so the two characters mean the break to everybody who writes them.
+static func as_said(wanted: String) -> String:
+	return wanted.replace("\\n", "\n")

package/build/godot/addons/gdharness_runtime/runtime_says.gd.uid

@@ -0,0 +1 @@
+uid://cx6i38yml0dy7

package/build/godot/addons/gdharness_runtime/runtime_targets.gd

@@ -4,6 +4,7 @@ extends RefCounted
 
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
+const Says = preload("runtime_says.gd")
 const Values = preload("runtime_values.gd")
 const Words = preload("runtime_words.gd")
 
@@ -43,7 +44,7 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 	var pending: Array[Node] = [reached["node"]]
 	while not pending.is_empty():
 		var node: Node = pending.pop_front()
-		if node is Control and Queries.says(node, wanted):
+		if node is Control and Says.says(node, wanted):
 			if not Queries.shown(node):
 				hidden += 1
 			else:
@@ -142,20 +143,35 @@ static func _rank(target: Control, whole: bool) -> int:
 	return (2 if target is BaseButton else 0) + (1 if whole else 0)
 
 
-## Whether [param said] is the whole of what [param wanted] asks for. A glob is matched against the
-## whole text already, so every match of one is whole.
+## Whether one of [param wanted]'s alternatives is the whole of [param said], or the whole of one of
+## its lines. A glob is matched against the whole text already, so every match of one is whole.
+##
+## A line counts because a card is a title over a description: "WARD" over "wards 3" is the card
+## named WARD, and read as its words run together it said WARD only as part of more, level with
+## "WARDSPITE" over its own description, and a click on WARD was refused as not clear.
 static func _says_exactly(said: String, wanted: String) -> bool:
-	var words: String = Queries.as_said(wanted)
-	if words.contains("*") or words.contains("?"):
-		return true
-	return said.strip_edges().nocasecmp_to(words.strip_edges()) == 0
+	for words: String in Says.alternatives(wanted):
+		if not Says.is_plain(words):
+			if said.matchn(words):
+				return true
+			continue
+		var looked_for: String = words.strip_edges()
+		if said.strip_edges().nocasecmp_to(looked_for) == 0:
+			return true
+		for line: String in said.split("\n"):
+			if line.strip_edges().nocasecmp_to(looked_for) == 0:
+				return true
+	return false
 
 
 ## [param count] matches of [param rank], as the start of a sentence.
 static func _described(count: int, rank: int, wanted: String, under: String) -> String:
 	var what: String = "button" if rank >= 2 else "control"
 	var how: String = '"%s"' % wanted
-	if not Queries.as_said(wanted).contains("*") and not Queries.as_said(wanted).contains("?"):
+	var plain: bool = true
+	for words: String in Says.alternatives(wanted):
+		plain = plain and Says.is_plain(words)
+	if plain:
 		how = ('exactly "%s"' if rank % 2 == 1 else '"%s" as part of more') % wanted
 	if count == 1:
 		return "the one %s on screen%s saying %s" % [what, under, how]
@@ -247,9 +263,12 @@ static func _areas_of(drawn: Array[Node]) -> Array[Rect2]:
 ##
 ## The engine's own order for which control takes the pointer: an embedded window over everything
 ## in the viewport that holds it, then the higher canvas layer, then the later in the tree. A
-## control holding the target or held by it is part of the same click. A target whose centre its
-## own container clips away is judged not covered, since the click scrolls it into view first and
-## what is drawn there now is not what it will land on.
+## control holding the target or held by it is part of the same click.
+##
+## A target whose centre its own container clips away is judged where the click will put it, since
+## the click scrolls it into view first: what is drawn over its place now is not what it will land
+## under. Judged not covered at all instead, a button below the fold of a roster that a full-screen
+## page covered was picked over the ones in view, scrolled up under the page and pressed there.
 ##
 ## [param areas] holds the box around each of [param drawn], so everything whose box misses the
 ## point is passed over before anything costlier is asked of it.
@@ -257,7 +276,7 @@ static func _cover_of(target: Control, drawn: Array[Node], areas: Array[Rect2])
 	var viewport: Viewport = target.get_viewport()
 	var point: Vector2 = target.get_global_transform_with_canvas() * (target.size * 0.5)
 	if _clipped_away(target, point):
-		return null
+		point = _where_it_lands(target, point)
 	var layer: int = _layer_of(target)
 	for at: int in drawn.size():
 		if not areas[at].has_point(point):
@@ -296,6 +315,29 @@ static func _holds(control: Control, point: Vector2) -> bool:
 	return Rect2(Vector2.ZERO, control.size).has_point(placed.affine_inverse() * point)
 
 
+## Where [param target]'s centre, now at [param point], will be once the click has scrolled it into
+## view: moved as little as puts the whole of it inside each container clipping it, innermost first,
+## which is how a scroll container brings a control into view. A target larger than a container is
+## centred in it.
+static func _where_it_lands(target: Control, point: Vector2) -> Vector2:
+	var drawn: Transform2D = target.get_global_transform_with_canvas()
+	var half: Vector2 = (drawn * Rect2(Vector2.ZERO, target.size)).size * 0.5
+	var landed: Vector2 = point
+	var walk: Node = target.get_parent()
+	while walk != null:
+		var holder: Control = walk as Control
+		if holder != null and holder.clip_contents:
+			var shown: Rect2 = holder.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, holder.size)
+			var low: Vector2 = shown.position + half
+			var high: Vector2 = shown.end - half
+			landed = Vector2(
+				shown.get_center().x if low.x > high.x else clampf(landed.x, low.x, high.x),
+				shown.get_center().y if low.y > high.y else clampf(landed.y, low.y, high.y)
+			)
+		walk = walk.get_parent()
+	return landed
+
+
 ## Whether a container clipping what it holds cuts [param point] off from [param control].
 static func _clipped_away(control: Control, point: Vector2) -> bool:
 	var walk: Node = control.get_parent()

package/build/godot/addons/gdharness_runtime/runtime_waits.gd

@@ -6,6 +6,7 @@ extends RefCounted
 const Paths = preload("runtime_paths.gd")
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
+const Says = preload("runtime_says.gd")
 const Values = preload("runtime_values.gd")
 
 ## The longest one wait may last, whatever the request says: past this the server has long
@@ -249,7 +250,6 @@ static func _watched(node: Node, node_path: String, property: String) -> Diction
 ## caller sees what it cost.
 func _wait_until_said(node_path: String, said: String, timeout_ms: int, include_hidden: bool) -> Dictionary:
 	var started: int = Time.get_ticks_msec()
-	var words: String = Queries.as_said(said)
 	var frames: int = 0
 	var looks: int = 0
 	var next_look: int = 0
@@ -257,7 +257,7 @@ func _wait_until_said(node_path: String, said: String, timeout_ms: int, include_
 	while true:
 		if Time.get_ticks_usec() >= next_look:
 			var looking: int = Time.get_ticks_usec()
-			found = _anything_says(node_path, words, include_hidden)
+			found = _anything_says(node_path, said, include_hidden)
 			looks += 1
 			next_look = Time.get_ticks_usec() + (Time.get_ticks_usec() - looking) * LOOKS_APART
 		if found or Time.get_ticks_msec() - started >= timeout_ms:
@@ -267,7 +267,7 @@ func _wait_until_said(node_path: String, said: String, timeout_ms: int, include_
 	# One more look at the end, so words that arrived between two paced looks are not answered as
 	# never having come.
 	if not found:
-		found = _anything_says(node_path, words, include_hidden)
+		found = _anything_says(node_path, said, include_hidden)
 		looks += 1
 
 	return {
@@ -293,7 +293,7 @@ func _anything_says(node_path: String, said: String, include_hidden: bool) -> bo
 	var pending: Array[Node] = [root]
 	while not pending.is_empty():
 		var node: Node = pending.pop_back()
-		if Queries.says(node, said) and (include_hidden or Queries.shown(node)):
+		if Says.says(node, said) and (include_hidden or Queries.shown(node)):
 			return true
 		pending.append_array(node.get_children(true))
 	return false