gdharness 1.1.45 → 1.1.47

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

@@ -233,13 +233,17 @@ func call_method(params: Dictionary) -> Dictionary:
 			var read_from: int = Time.get_ticks_usec()
 			var answered: Variant = Paths.read_under(reached["holder"], spelled)
 			var read_for: int = Time.get_ticks_usec() - read_from
-			return {
+			var listed: Dictionary = {
 				"type": "method_result",
 				"path": node_path,
 				"method": method,
 				"result": _values.serialize(answered),
 				"elapsed_usec": read_for,
 			}
+			var asked_of_it: Variant = params.get("properties")
+			if _reads_the_result(asked_of_it):
+				listed.merge(_read_off_result(answered, asked_of_it))
+			return listed
 		var why: String = (
 			"%s:%s takes no arguments" % [reached["called"], spelled]
 			if Paths.can_read(reached["holder"], spelled)
@@ -258,10 +262,11 @@ func call_method(params: Dictionary) -> Dictionary:
 	# The method a call ends on is the one being called whether or not it carries the brackets a
 	# step along the way would: "get_viewport():gui_get_focus_owner()" is the same call as without
 	# the last pair.
+	var not_called: String = _not_a_method_to_call(holder, named, str(reached["called"]))
+	if not not_called.is_empty():
+		return {"type": "error", "message": not_called}
 	if not Paths.method_of(named).is_empty():
 		named = Paths.method_of(named)
-	if not holder.has_method(named):
-		return {"type": "error", "message": "%s has no method %s" % [reached["called"], named]}
 
 	# Checked before the call rather than left to it. `callv` raises inside the game when an
 	# argument cannot be converted, and an error raised in a game somebody is playing holds it at a
@@ -360,9 +365,98 @@ func call_method(params: Dictionary) -> Dictionary:
 		answer["errors"] = caught.raised.slice(0, ERRORS_KEPT)
 		if caught.raised.size() > ERRORS_KEPT:
 			answer["errors_not_shown"] = caught.raised.size() - ERRORS_KEPT
+	var asked: Variant = params.get("properties")
+	if _reads_the_result(asked):
+		answer.merge(_read_off_result(result, asked))
 	return answer
 
 
+## Why [param named], the last step of a call's method, names no method of [param holder] to call, or
+## "" when it does. Brackets on it holding arguments are refused rather than read: the arguments are
+## taken from args alone, so a call is never made with half of them in one place and half in the
+## other, or with the bracketed ones quietly dropped.
+static func _not_a_method_to_call(holder: Object, named: String, called: String) -> String:
+	var method: String = named
+	if not Paths.method_of(named).is_empty():
+		var bracketed: Dictionary = Paths.arguments_of(named)
+		var in_brackets: Array = bracketed.get("args", [])
+		if bracketed.has("message") or not in_brackets.is_empty():
+			return (
+				"%s:%s: the method a call ends on takes its arguments under args, not in its brackets"
+				% [called, named]
+			)
+		method = Paths.method_of(named)
+	return "" if holder.has_method(method) else "%s has no method %s" % [called, method]
+
+
+## Whether a call's `properties` asks for its result to be read: true, or a list of names.
+static func _reads_the_result(asked: Variant) -> bool:
+	return asked is Array or (asked is bool and asked)
+
+
+## What [param asked] reads off the object a call answered with: every variable its script declares
+## when [param asked] is true, or the properties a list names, each a path walked from the object.
+##
+## In the same answer because an object handed back is otherwise only its class and an id, and
+## reading one field of it meant finding the same object again by a path into the game's private
+## state, which works only where the caller already knows a key. A name that is not there is listed
+## rather than refusing the answer, since the call has run by then and its result is what was asked.
+func _read_off_result(result: Variant, asked: Variant) -> Dictionary:
+	if result is Object and not is_instance_valid(result):
+		return {
+			"properties_note": "the call answered an object that has since been freed, so nothing was read"
+		}
+	if not result is Object:
+		return {
+			"properties_note":
+			"the call answered %s, which has no properties to read" % type_string(typeof(result))
+		}
+	var object: Object = result
+	var wanted: Array[String] = []
+	if asked is Array:
+		for name: Variant in asked:
+			wanted.append(str(name))
+	else:
+		wanted = _script_variables(object)
+	var read: Dictionary = {}
+	var missing: Array[String] = []
+	for path: String in wanted:
+		var walked: Dictionary = _walk_from(object, path)
+		if walked.has("message"):
+			missing.append(str(walked["message"]))
+		else:
+			read[path] = _values.serialize(walked["value"])
+	var answered: Dictionary = {"result_properties": read}
+	if not missing.is_empty():
+		answered["result_properties_missing"] = missing
+	return answered
+
+
+## The variables the script attached to [param object] declares, in the order it declares them.
+static func _script_variables(object: Object) -> Array[String]:
+	var names: Array[String] = []
+	for entry: Dictionary in object.get_property_list():
+		var usage: int = entry.get("usage", 0)
+		if usage & PROPERTY_USAGE_SCRIPT_VARIABLE != 0:
+			names.append(str(entry.get("name", "")))
+	return names
+
+
+## What [param path] reads walked from [param object], as {"value"}, or {"message"} naming the step
+## that is not there, by the same rules a path read from a node follows.
+static func _walk_from(object: Object, path: String) -> Dictionary:
+	var holder: Variant = object
+	var called: String = "the result"
+	for named: String in Paths.steps_of(path):
+		if not (holder is Object or holder is Array or holder is Dictionary or Paths.packed(holder)):
+			return {"message": "%s holds no object to read %s off" % [called, named]}
+		if not Paths.can_read(holder, named):
+			return {"message": Paths.nothing_there(holder, named, called)}
+		holder = Paths.read_under(holder, named)
+		called = "%s:%s" % [called, named]
+	return {"value": holder}
+
+
 ## Why [param given] arguments are the wrong number for [param method], or "" when they are not.
 ##
 ## Asked before the call, because `callv` given the wrong number refuses inside the game and returns

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

@@ -25,6 +25,9 @@ const HEADLESS_VIEWPORT: Vector2 = Vector2(64, 64)
 ## everything that process starts. Kept in step with `DESKTOP_VARIABLE` in src/desktop.ts.
 const DESKTOP_VARIABLE: String = "GDHARNESS_DESKTOP"
 
+## Whether this run has had the pointer note in full; the game process is the run.
+static var _pointer_explained: bool = false
+
 var _host: Node
 var _values: Values
 
@@ -60,13 +63,21 @@ func _init(host: Node, values: Values) -> void:
 ## that would take the screen. What reads the injected event is right, tooltips included, since the
 ## engine places a tooltip from the motion that reached the control.
 static func _pointer_noted(answer: Dictionary) -> Dictionary:
-	if OS.get_environment(DESKTOP_VARIABLE) != "":
+	if OS.get_environment(DESKTOP_VARIABLE) == "":
+		return answer
+	# The fact on every answer and the explanation on the first of the run: a session sends dozens of
+	# pointer calls to one game, and the same four hundred characters on each was most of what came
+	# back.
+	answer["pointer_on_hidden_desktop"] = true
+	if not _pointer_explained:
+		_pointer_explained = true
 		answer["pointer_note"] = (
 			"This game is on gdharness's own desktop, where Windows refuses to say where the"
 			+ " pointer is, so get_mouse_position() on the root window, and get_global_mouse_position()"
 			+ " and get_local_mouse_position() on what is drawn there, read a meaningless position"
 			+ " rather than where this put it. What reads the event itself gets this position: the"
-			+ " control under the pointer, its hover and tooltip, and the game's input handlers."
+			+ " control under the pointer, its hover and tooltip, and the game's input handlers. Said"
+			+ " once a run; pointer_on_hidden_desktop marks every answer it applies to."
 		)
 	return answer
 

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

@@ -61,7 +61,7 @@ static func wanted_items(menu: PopupMenu, params: Dictionary) -> Array[int]:
 			if words[at] == wanted:
 				return _items([order[at]])
 		for at: int in words.size():
-			if words[at].nocasecmp_to(wanted) == 0:
+			if Says.spaced(words[at]).nocasecmp_to(Says.spaced(wanted)) == 0:
 				return _items([order[at]])
 	# Separators are left out here: a heading is refused when named in full, and a pattern that
 	# matched one beside the item it heads would tie the two.

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

@@ -83,19 +83,21 @@ const READS_ONLY: String = ", and a path, which a wait reads every frame, only c
 ## 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.
 ##
-## A step written as a call, "get_viewport()", calls a method of that name that takes no arguments
-## and walks into what it returned. Some of what hangs off a node is only reachable by asking:
-## which control holds the focus is a question for the viewport a control is in, and the viewport
-## is a method's answer rather than a property. Spelled with the brackets so a reader sees a call
-## where one happens, and so a method can never shadow a property of the same name. A list or a map
-## answers the calls that read it, "board:size()" or "inbox:keys()", listed in [constant LIST_CALLS]
-## and [constant MAP_CALLS].
+## A step written as a call, "get_viewport()", calls a method of that name and walks into what it
+## returned. Some of what hangs off a node is only reachable by asking: which control holds the
+## focus is a question for the viewport a control is in, and the viewport is a method's answer
+## rather than a property. Spelled with the brackets so a reader sees a call where one happens, and
+## so a method can never shadow a property of the same name. A list or a map answers the calls that
+## read it, "board:size()" or "inbox:keys()", listed in [constant LIST_CALLS] and
+## [constant MAP_CALLS]. An engine method that reads takes literal arguments in the brackets,
+## "get_theme_stylebox(\"panel\"):content_margin_top", since what a control's theme gives it is only
+## reachable by naming what is asked for; see [method arguments_of].
 ##
 ## 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.
 static func walk_to(node: Node, node_path: String, reaching: String) -> Dictionary:
-	var parts: PackedStringArray = reaching.split(":")
+	var parts: PackedStringArray = steps_of(reaching)
 	var holder: Variant = node
 	var called: String = node_path
 	for step: int in parts.size() - 1:
@@ -187,26 +189,33 @@ static func nothing_under(holder: Variant, named: String, called: String) -> Str
 ## first one. An index reads the way a property does, and a negative one counts from the end the
 ## way GDScript's own does, so reading the last of something does not mean asking how many first.
 static func can_read(holder: Variant, named: String) -> bool:
+	var method: String = method_of(named)
+	var given: Dictionary = arguments_of(named) if not method.is_empty() else {"args": []}
+	if given.has("message"):
+		return false
+	var args: Array = given["args"]
 	if holder is Array:
 		var items: Array = holder
-		var list_call: String = method_of(named)
-		if not list_call.is_empty():
-			return list_call in LIST_CALLS and not (items.is_empty() and list_call in NEEDS_AN_ELEMENT)
+		if not method.is_empty():
+			return (
+				args.is_empty()
+				and method in LIST_CALLS
+				and not (items.is_empty() and method in NEEDS_AN_ELEMENT)
+			)
 		return _index_in(named, items.size()) != -1
 	if packed(holder):
-		if not method_of(named).is_empty():
-			return method_of(named) in PACKED_CALLS
+		if not method.is_empty():
+			return args.is_empty() and method in PACKED_CALLS
 		return _index_in(named, len(holder)) != -1
 	if holder is Dictionary:
 		var map: Dictionary = holder
-		if not method_of(named).is_empty():
-			return method_of(named) in MAP_CALLS
+		if not method.is_empty():
+			return args.is_empty() and method in MAP_CALLS
 		return not _key_in(map, named).is_empty()
 	if holder is Object:
 		var object: Object = holder
-		var method: String = method_of(named)
 		if not method.is_empty():
-			return call_refused(object, method, "").is_empty()
+			return call_refused(object, method, "", args.size()).is_empty()
 		return _has_property(object, named)
 	return false
 
@@ -236,24 +245,103 @@ static func _key_in(map: Dictionary, named: String) -> Array:
 	return []
 
 
-## The method a step written as a call names, "get_viewport()" being get_viewport, or "" for a
-## step that is a name.
+## [param reaching] split into its steps at each colon, except one inside a call's brackets or a
+## quoted argument: `get_node("/root/Main"):name` is two steps, and split at every colon a quoted
+## argument holding one became a step that names nothing.
+static func steps_of(reaching: String) -> PackedStringArray:
+	var steps: PackedStringArray = []
+	var step: String = ""
+	var depth: int = 0
+	var quoted: bool = false
+	var escaped: bool = false
+	for character: String in reaching:
+		if quoted:
+			if escaped:
+				escaped = false
+			elif character == "\\":
+				escaped = true
+			elif character == '"':
+				quoted = false
+		elif character == '"':
+			quoted = true
+		elif character == "(":
+			depth += 1
+		elif character == ")":
+			depth = maxi(depth - 1, 0)
+		elif character == ":" and depth == 0:
+			var _kept: bool = steps.push_back(step)
+			step = ""
+			continue
+		step += character
+	var _last: bool = steps.push_back(step)
+	return steps
+
+
+## The method a step written as a call names, "get_viewport()" being get_viewport and
+## `get_theme_constant("separation")` get_theme_constant, or "" for a step that is a name.
 static func method_of(named: String) -> String:
-	return named.trim_suffix("()") if named.ends_with("()") else ""
+	if not named.ends_with(")"):
+		return ""
+	var opened: int = named.find("(")
+	if opened < 1:
+		return ""
+	var method: String = named.substr(0, opened)
+	return method if method.is_valid_ascii_identifier() else ""
 
 
-## How many arguments [param method] on [param object] has to be given, or -1 when there is no such
-## method. Read off the method list rather than [method Object.has_method], because a path can only
-## call a method with nothing, and a method with a required argument called with nothing raises
-## inside the game rather than answering.
-static func _arguments_required(object: Object, method: String) -> int:
+## The arguments a call step gives in its brackets, as {"args"}, or {"message"} saying why they are
+## not ones a path can give.
+##
+## Literals only: words in double quotes, numbers, true, false and null, read as JSON reads them, a
+## whole number as an int. A path names what is read, and an argument that was itself a path or an
+## object would make a read depend on other state in a way the step does not show.
+static func arguments_of(named: String) -> Dictionary:
+	var inside: String = named.substr(named.find("(") + 1, named.length() - named.find("(") - 2).strip_edges()
+	if inside.is_empty():
+		return {"args": []}
+	var reader: JSON = JSON.new()
+	var parsed: Variant = reader.data if reader.parse("[%s]" % inside) == OK else null
+	if not parsed is Array:
+		return {"message": _not_literals(named)}
+	var args: Array = []
+	for given: Variant in parsed:
+		if given is float:
+			var number: float = given
+			if number == floorf(number) and absf(number) < 9.0e15:
+				args.append(int(number))
+			else:
+				args.append(number)
+		elif given == null or given is String or given is bool:
+			args.append(given)
+		else:
+			return {"message": _not_literals(named)}
+	return {"args": args}
+
+
+static func _not_literals(named: String) -> String:
+	return (
+		"%s: a path gives a call literal arguments only, words in double quotes, numbers, true, false or null"
+		% named
+	)
+
+
+## How many arguments [param method] on [param object] takes, as {"least", "most", "any_more"}, or
+## an empty map when there is no such method. Read off the method list rather than
+## [method Object.has_method], because a method given too few or too many raises inside the game
+## rather than answering.
+static func _arity(object: Object, method: String) -> Dictionary:
 	for entry: Dictionary in object.get_method_list():
 		if str(entry.get("name", "")) != method:
 			continue
 		var params: Array = entry.get("args", [])
 		var defaults: Array = entry.get("default_args", [])
-		return params.size() - defaults.size()
-	return -1
+		var flags: int = entry.get("flags", 0)
+		return {
+			"least": params.size() - defaults.size(),
+			"most": params.size(),
+			"any_more": flags & METHOD_FLAG_VARARG != 0,
+		}
+	return {}
 
 
 ## Why a path may not call [param method] on [param object], said about [param called_as], or ""
@@ -265,16 +353,36 @@ static func _arguments_required(object: Object, method: String) -> int:
 ## doing something and answering nothing, and one left untyped is trusted. Without this a find
 ## with property "queue_free()" freed every node it matched, and a wait on "advance_day()" called
 ## it once a frame and then reported the state it had driven the game to.
-static func call_refused(object: Object, method: String, called_as: String) -> String:
-	var required: int = _arguments_required(object, method)
-	if required == -1:
+##
+## Given [param given] arguments, a call is the engine's and marked as reading, or it is refused. A
+## game's method taking arguments is trusted on nothing at all: one answering a value can as well
+## change what it was asked about, and runtime_invoke call is how one is called on purpose.
+static func call_refused(object: Object, method: String, called_as: String, given: int = 0) -> String:
+	var arity: Dictionary = _arity(object, method)
+	if arity.is_empty():
 		return "%s has no method %s" % [called_as, method]
-	if required > 0:
+	var least: int = arity["least"]
+	var most: int = arity["most"]
+	var any_more: bool = arity["any_more"]
+	var scripted: Dictionary = _script_method(object, method)
+	if not scripted.is_empty() and (given > 0 or least > 0):
+		var why: String = (
+			"since nothing marks one as only reading%s; runtime_invoke call takes them" % READS_ONLY
+		)
 		return (
-			"%s.%s takes %d argument%s, and a path can only call a method that takes none"
-			% [called_as, method, required, "" if required == 1 else "s"]
+			"%s.%s is the game's own and a path gives a game's method no arguments, %s"
+			% [called_as, method, why]
+		)
+	if given < least or (given > most and not any_more):
+		var takes: String = "%d" % least
+		if any_more:
+			takes = "at least %d" % least
+		elif most != least:
+			takes = "%d to %d" % [least, most]
+		return (
+			'%s.%s takes %s argument%s and the path gives it %d, in the brackets as in %s("name")'
+			% [called_as, method, takes, "" if takes == "1" else "s", given, method]
 		)
-	var scripted: Dictionary = _script_method(object, method)
 	if not scripted.is_empty():
 		var returned: Dictionary = scripted.get("return", {})
 		var usage: int = returned.get("usage", 0)
@@ -350,7 +458,8 @@ static func read_under(holder: Variant, named: String) -> Variant:
 	var object: Object = holder
 	var method: String = method_of(named)
 	if not method.is_empty():
-		return object.call(method)
+		var args: Array = arguments_of(named)["args"]
+		return object.callv(method, args)
 	return object.get(named)
 
 
@@ -374,20 +483,25 @@ static func _index_in(named: String, size: int) -> int:
 ## the whole path, because the step is the typo.
 static func nothing_there(holder: Variant, named: String, called_as: String) -> String:
 	var container_call: String = method_of(named)
+	var given: Dictionary = arguments_of(named) if not container_call.is_empty() else {"args": []}
+	if given.has("message"):
+		return "%s:%s" % [called_as, given["message"]]
+	var given_args: Array = given["args"]
+	var given_count: int = given_args.size()
 	if holder is Array:
 		var items: Array = holder
 		if container_call in NEEDS_AN_ELEMENT and items.is_empty():
 			return "%s is an empty list, so it has no %s" % [called_as, named]
 		if not container_call.is_empty():
-			return container_calls_refused(called_as, "a list", container_call)
+			return container_calls_refused(called_as, "a list", container_call, given_count)
 		return "%s is a list of %d, so there is no %s in it" % [called_as, items.size(), named]
 	if packed(holder):
 		if not container_call.is_empty():
-			return container_calls_refused(called_as, "a packed list", container_call)
+			return container_calls_refused(called_as, "a packed list", container_call, given_count)
 		return "%s is a packed list of %d, so there is no %s in it" % [called_as, len(holder), named]
 	if holder is Dictionary:
 		if not container_call.is_empty():
-			return container_calls_refused(called_as, "a map", container_call)
+			return container_calls_refused(called_as, "a map", container_call, given_count)
 		var map: Dictionary = holder
 		var keys: Array = map.keys()
 		# A key reading as the step and still not reached is one of a type a step cannot spell, and
@@ -410,7 +524,7 @@ static func nothing_there(holder: Variant, named: String, called_as: String) ->
 	var object: Object = holder
 	var method: String = method_of(named)
 	if not method.is_empty():
-		return call_refused(object, method, called_as)
+		return call_refused(object, method, called_as, given_count)
 	# A method spelled as a property is the likeliest thing behind a name the object has no property
 	# for, and the caller is one pair of brackets away from what they meant.
 	if object.has_method(named):
@@ -422,13 +536,18 @@ static func nothing_there(holder: Variant, named: String, called_as: String) ->
 
 
 ## Why [param method] is not a call a path makes on [param sort] ("a list", "a packed list" or "a
-## map"), naming the calls it does make.
-static func container_calls_refused(called_as: String, sort: String, method: String) -> String:
+## map"), naming the calls it does make, or that it makes this one with no arguments when
+## [param given] were.
+static func container_calls_refused(
+	called_as: String, sort: String, method: String, given: int = 0
+) -> String:
 	var calls: Array[String] = MAP_CALLS
 	if sort == "a list":
 		calls = LIST_CALLS
 	elif sort == "a packed list":
 		calls = PACKED_CALLS
+	if given > 0 and method in calls:
+		return "%s is %s, and a path calls %s() on one with no arguments" % [called_as, sort, method]
 	var spelled: Array[String] = []
 	for each: String in calls:
 		spelled.append(each + "()")

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

@@ -16,6 +16,9 @@ const SPLITS_KEPT: int = 8
 ## Each `says` split into alternatives, by what was written; see [method alternatives].
 static var _splits: Dictionary[String, Array] = {}
 
+## Every space separator Unicode has besides the plain space, built once; see [method spaced].
+static var _spaces: RegEx = null
+
 
 ## Whether [param node]'s own words are what [param wanted] asks for.
 static func says(node: Node, wanted: String) -> bool:
@@ -35,12 +38,33 @@ static func says(node: Node, wanted: String) -> bool:
 ## 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:
+	var shown: String = spaced(said)
 	for words: String in alternatives(wanted):
-		if said.containsn(words) if is_plain(words) else said.matchn(words):
+		if shown.containsn(words) if is_plain(words) else shown.matchn(words):
 			return true
 	return false
 
 
+## [param text] with every Unicode space separator written as a plain space, which is what a caller
+## types for any of them. A game keeping a name on one line writes it with a non-breaking space, and
+## "Deskanem Bonituk" typed with a plain one found nothing while the screen showed exactly those
+## words. One character for one, so a place found in the result is the same place in [param text].
+static func spaced(text: String) -> String:
+	if _spaces == null:
+		var separators: String = (
+			String.chr(0x00A0)
+			+ String.chr(0x1680)
+			+ String.chr(0x2000)
+			+ "-"
+			+ String.chr(0x200A)
+			+ String.chr(0x202F)
+			+ String.chr(0x205F)
+			+ String.chr(0x3000)
+		)
+		_spaces = RegEx.create_from_string("[%s]" % separators)
+	return _spaces.sub(text, " ", true)
+
+
 ## 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
@@ -110,4 +134,4 @@ static func widened(wanted: String) -> String:
 ## 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")
+	return spaced(wanted.replace("\\n", "\n"))