gdharness 0.9.0 → 0.9.2

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

@@ -34,9 +34,10 @@ func get_tree(params: Dictionary) -> Dictionary:
 	var max_depth: int = int(params.get("depth", 3))
 	var include_properties: bool = bool(params.get("include_properties", false))
 
-	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
-	if root == null:
-		return {"type": "error", "message": "Node not found: " + root_path}
+	var reached: Dictionary = Values.node_at(_host.get_tree().root, root_path)
+	if reached.has("message"):
+		return reached
+	var root: Node = reached["node"]
 
 	return {"type": "tree", "root": _serialize_node_tree(root, 0, max_depth, include_properties)}
 
@@ -64,20 +65,28 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	if not wanted["script"].is_empty() and not wanted["script"].begins_with("res://"):
 		wanted["script"] = "res://" + wanted["script"]
 
-	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
-	if root == null:
-		return {"type": "error", "message": "Node not found: " + root_path}
+	var reached: Dictionary = Values.node_at(_host.get_tree().root, root_path)
+	if reached.has("message"):
+		return reached
+	var root: Node = reached["node"]
 
 	var found: Array[Dictionary] = []
 	var pending: Array[Node] = [root]
 	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 nearly: int = 0
 	while not pending.is_empty():
 		var node: Node = pending.pop_front()
-		if _matches(node, wanted):
+		var rest: bool = _matches_apart_from_name(node, wanted)
+		if rest and _named(node, wanted["name"]):
 			if found.size() >= limit:
 				truncated = true
 				break
 			found.append(_found(node, wanted_property))
+		elif rest and literal and str(node.name).containsn(wanted["name"]):
+			nearly += 1
 		# Internal children included, which they were not. A ConfirmationDialog builds its Yes and
 		# its No as internal nodes, and a ScrollContainer its bars, so a find over a screen for
 		# every Button came back without the two buttons the player is being asked to press:
@@ -88,7 +97,17 @@ func find_nodes(params: Dictionary) -> Dictionary:
 		for index: int in range(children.size() - 1, -1, -1):
 			pending.push_front(children[index])
 
-	return {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
+	var answer: Dictionary = {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
+	# Nothing found is the one answer that cannot be told apart from having asked the wrong
+	# question, and a name written without a wildcard is the way an agent writes "contains".
+	# Said only when it changes the answer, so a genuine nothing stays a plain nothing.
+	if found.is_empty() and nearly > 0:
+		var holding: String = "names contain" if nearly > 1 else "name contains"
+		answer["note"] = (
+			'name is matched as a glob against the whole name; %d node %s "%s", which "*%s*" would find'
+			% [nearly, holding, wanted["name"], wanted["name"]]
+		)
+	return answer
 
 
 ## One match, with the named property on it when one was named.
@@ -102,15 +121,20 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	var entry: Dictionary = _serialize_node(node, false)
 	if wanted_property.is_empty():
 		return entry
-	var has: bool = false
-	for prop: Dictionary in node.get_property_list():
-		if str(prop["name"]) == wanted_property:
-			has = true
-			break
 	entry["property"] = wanted_property
+	# Through a path as well, for the reason [method _reached] gives. A step that is not there on
+	# this node reads as not having the property rather than as a refusal, which is the rule this
+	# whole function is written to: a find matches nodes of several classes on purpose.
+	var reached: Dictionary = _reached(node, str(entry["path"]), wanted_property)
+	if reached.has("message"):
+		entry["has_property"] = false
+		return entry
+	var holder: Object = reached["holder"]
+	var named: String = reached["name"]
+	var has: bool = _has_property(holder, named)
 	entry["has_property"] = has
 	if has:
-		entry["value"] = _values.serialize(node.get(wanted_property))
+		entry["value"] = _values.serialize(holder.get(named))
 	return entry
 
 
@@ -123,11 +147,24 @@ static func _anything_asked(wanted: Dictionary[String, String]) -> bool:
 	return false
 
 
-func _matches(node: Node, wanted: Dictionary[String, String]) -> bool:
+## Whether [param node] carries the name a find asked for. Empty matches everything, which is what
+## makes leaving a filter out the same as not having one.
+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("?")
+
+
+## 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:
 	if not wanted["group"].is_empty() and not node.is_in_group(wanted["group"]):
 		return false
-	if not wanted["name"].is_empty() and not str(node.name).matchn(wanted["name"]):
-		return false
 	# 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.
@@ -173,9 +210,10 @@ func read_text(params: Dictionary) -> Dictionary:
 	var include_hidden: bool = bool(params.get("include_hidden", false))
 	var limit: int = clampi(int(params.get("limit", READ_LIMIT)), 1, READ_LIMIT)
 
-	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
-	if root == null:
-		return {"type": "error", "message": "Node not found: " + root_path}
+	var reached: Dictionary = Values.node_at(_host.get_tree().root, root_path)
+	if reached.has("message"):
+		return reached
+	var root: Node = reached["node"]
 
 	# One line further than asked for, so that whether anything was left behind is read off the
 	# walk rather than guessed at from the count: a panel of exactly as many lines as the caller
@@ -240,9 +278,10 @@ func get_rect(params: Dictionary) -> Dictionary:
 	if node_path.is_empty():
 		return {"type": "error", "message": "Node path required"}
 
-	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
-	if node == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
 
 	if node is Control:
 		var control: Control = node
@@ -391,28 +430,71 @@ func get_property(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or property.is_empty():
 		return {"type": "error", "message": "Node path and property required"}
 
-	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
-	if node == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
 
+	var reached: Dictionary = _reached(node, node_path, property)
+	if reached.has("message"):
+		return reached
+
+	var holder: Object = reached["holder"]
+	var named: String = reached["name"]
 	# Asked of the property list rather than read and compared to null, because a property the
-	# node does not have and a property that is null both read as null.
-	var known: bool = false
-	for entry: Dictionary in node.get_property_list():
-		if str(entry["name"]) == property:
-			known = true
-			break
-	if not known:
-		return {"type": "error", "message": "%s has no property %s" % [node_path, property]}
+	# holder does not have and a property that is null both read as null.
+	if not _has_property(holder, named):
+		return {"type": "error", "message": "%s has no property %s" % [reached["called"], named]}
 
 	return {
 		"type": "property",
 		"path": node_path,
 		"property": property,
-		"value": _values.serialize(node.get(property)),
+		"value": _values.serialize(holder.get(named)),
 	}
 
 
+## What [param reaching] names something on, which is the node itself until the name has a colon
+## in it, and the last name along that path.
+##
+## A game's state does not sit on nodes, it hangs off them: the speed of the clock is a property of
+## a [RefCounted] held by a [RefCounted] held by the root, and that is what an agent asks about.
+## What a game does hangs off them the same way, so the last name is a property to read, a property
+## to write or a method to call, and the walk to it is one walk.
+##
+## Colons, because that is the separator [method Object.get_indexed] already takes. Walked a step
+## at a time rather than handed to that method, which answers null for a path that goes wrong
+## halfway along and for one that ends on null.
+##
+## Answers with a `message` instead when a step along the way is not there or holds something that
+## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
+## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
+func _reached(node: Node, node_path: String, reaching: String) -> Dictionary:
+	var parts: PackedStringArray = reaching.split(":")
+	var holder: Object = node
+	var called: String = node_path
+	for step: int in parts.size() - 1:
+		var named: String = parts[step]
+		if not _has_property(holder, named):
+			return {"type": "error", "message": "%s has no property %s" % [called, named]}
+		var next: Variant = holder.get(named)
+		called = "%s:%s" % [called, named]
+		if not next is Object:
+			var wanted: String = parts[step + 1]
+			return {"type": "error", "message": "%s holds no object to read %s off" % [called, wanted]}
+		holder = next
+	return {"holder": holder, "name": parts[parts.size() - 1], "called": called}
+
+
+## Whether [param holder] declares [param named]. Its own function because three ops ask it and a
+## property read back as null answers it wrongly.
+static func _has_property(holder: Object, named: String) -> bool:
+	for entry: Dictionary in holder.get_property_list():
+		if str(entry["name"]) == named:
+			return true
+	return false
+
+
 func set_property(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
@@ -421,19 +503,29 @@ func set_property(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or property.is_empty():
 		return {"type": "error", "message": "Node path and property required"}
 
-	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
-	if node == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
 
-	var old_value: Variant = node.get(property)
-	node.set(property, _values.fitted(value, typeof(old_value)))
+	# Through a path as well, for the reason [method _reached] gives, and read back off the same
+	# holder afterwards: a set that does not take says so by answering with the old value, which is
+	# how a typed container refusing a write is told from one accepting it.
+	var reached: Dictionary = _reached(node, node_path, property)
+	if reached.has("message"):
+		return reached
+
+	var holder: Object = reached["holder"]
+	var named: String = reached["name"]
+	var old_value: Variant = holder.get(named)
+	holder.set(named, _values.fitted(value, typeof(old_value)))
 
 	return {
 		"type": "property_set",
 		"path": node_path,
 		"property": property,
 		"old_value": _values.serialize(old_value),
-		"new_value": _values.serialize(node.get(property))
+		"new_value": _values.serialize(holder.get(named))
 	}
 
 
@@ -445,18 +537,28 @@ func call_method(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or method.is_empty():
 		return {"type": "error", "message": "Node path and method required"}
 
-	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
-	if node == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
+
+	# Through a path as well, for the reason [method _reached] gives. What a game does hangs off its
+	# nodes as much as its state does, so reading `_game:run:day` while being unable to call
+	# `_game:run:advance` answers half of what a node holds and refuses the other half.
+	var reached: Dictionary = _reached(node, node_path, method)
+	if reached.has("message"):
+		return reached
 
-	if not node.has_method(method):
-		return {"type": "error", "message": "Method not found: " + method}
+	var holder: Object = reached["holder"]
+	var named: String = reached["name"]
+	if not holder.has_method(named):
+		return {"type": "error", "message": "%s has no method %s" % [reached["called"], named]}
 
 	var deserialized_args: Array = []
 	for index: int in args.size():
-		deserialized_args.append(_values.fitted(args[index], _values.parameter_type(node, method, index)))
+		deserialized_args.append(_values.fitted(args[index], _values.parameter_type(holder, named, index)))
 
-	var result: Variant = node.callv(method, deserialized_args)
+	var result: Variant = holder.callv(named, deserialized_args)
 
 	return {"type": "method_result", "path": node_path, "method": method, "result": _values.serialize(result)}
 

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

@@ -42,6 +42,37 @@ func serialize(value: Variant) -> Variant:
 	return call(serialiser, value) if not serialiser.is_empty() else value
 
 
+## The node [param path] names under [param root], or a refusal saying why there is not one.
+##
+## The other direction of what a node serialises as, and here for that reason: a node crosses the
+## wire as its path, so a path crossing back is a node or it is nothing. One answer for every op,
+## because each of them read a path for itself and they could disagree about what one means.
+##
+## A colon is the disagreement worth its own sentence. Godot reads everything after the first one
+## as subnames and [method Node.get_node_or_null] drops them, so "/root/Main:_game:run" was quietly
+## answered about "/root/Main", and an op that then said the path had no method `advance` was right
+## about an object nobody had asked for. Colons reach through what a node holds, and the arguments
+## that take them are the property and the method.
+static func node_at(root: Node, path: String) -> Dictionary:
+	if path.is_empty():
+		return {"type": "error", "message": "Node path required"}
+
+	if path.contains(":"):
+		var shape: String = (
+			'"%s" names a node and colons reach past one: "%s" is the node,'
+			+ ' and "%s" goes in the property or the method'
+		)
+		return {
+			"type": "error",
+			"message": shape % [path, path.get_slice(":", 0), path.substr(path.find(":") + 1)],
+		}
+
+	var node: Node = root.get_node_or_null(path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + path}
+	return {"node": node}
+
+
 func _serialize_nil(_value: Variant) -> Variant:
 	return null
 

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

@@ -53,9 +53,10 @@ func wait_signal(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or signal_name.is_empty():
 		return {"type": "error", "message": "Node path and signal name required"}
 
-	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
-	if node == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
 	if not node.has_signal(signal_name):
 		return {"type": "error", "message": "%s has no signal %s" % [node_path, signal_name]}
 
@@ -90,8 +91,9 @@ func wait_until(params: Dictionary) -> Dictionary:
 		return _out_of_range("timeout_ms", timeout_ms, 1, CEILING_MSEC)
 	if node_path.is_empty():
 		return {"type": "error", "message": "Node path required"}
-	if _host.get_tree().root.get_node_or_null(node_path) == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
 	if not says.is_empty():
 		return await _wait_until_said(node_path, says, timeout_ms)
 	if property.is_empty():
@@ -99,7 +101,7 @@ func wait_until(params: Dictionary) -> Dictionary:
 	if not params.has("value"):
 		return {"type": "error", "message": "A value to wait for is required"}
 
-	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	var node: Node = standing["node"]
 
 	var current: Variant = node.get(property)
 	var wanted: Variant = _values.fitted(params["value"], typeof(current))