gdharness 1.1.21 → 1.1.23

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

@@ -67,6 +67,9 @@ const PACKED: Array[int] = [
 ## The calls an empty list has nothing to answer, which the engine reports as an error when asked.
 const NEEDS_AN_ELEMENT: Array[String] = ["front", "back", "pick_random"]
 
+## Said after every call a path refuses for doing something rather than reading.
+const READS_ONLY: String = ", and a path, which a wait reads every frame, only calls methods that read"
+
 
 ## 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.
@@ -198,16 +201,33 @@ static func can_read(holder: Variant, named: String) -> bool:
 		var map: Dictionary = holder
 		if not method_of(named).is_empty():
 			return method_of(named) in MAP_CALLS
-		return map.has(named) or map.has(StringName(named))
+		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 _arguments_required(object, method) == 0
+			return call_refused(object, method, "").is_empty()
 		return _has_property(object, named)
 	return false
 
 
+## The key of [param map] a step names, in a list of one, or an empty list when it names none.
+##
+## A step is text, and a map is keyed by whatever the game put in it: text, a StringName, or a
+## number, which a map of units by id is. Keyed by 3, "3" is not a key of it, measured on 4.7.2, so a
+## step that reads as a number is tried as one after the two spellings of text.
+static func _key_in(map: Dictionary, named: String) -> Array:
+	var spellings: Array = [named, StringName(named)]
+	if named.is_valid_int():
+		spellings.append(int(named))
+	if named.is_valid_float():
+		spellings.append(float(named))
+	for key: Variant in spellings:
+		if map.has(key):
+			return [key]
+	return []
+
+
 ## The method a step written as a call names, "get_viewport()" being get_viewport, or "" for a
 ## step that is a name.
 static func method_of(named: String) -> String:
@@ -228,6 +248,62 @@ static func _arguments_required(object: Object, method: String) -> int:
 	return -1
 
 
+## Why a path may not call [param method] on [param object], said about [param called_as], or ""
+## when it may.
+##
+## A path is read, and a wait reads it every frame, so a call in one has to be a read. The engine
+## marks its own reading methods const and `queue_free()`, `free()` and `set_name()` not, measured on
+## 4.7.2. A game's methods carry no such mark, so one declared `-> void` is taken at its word, as
+## 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:
+		return "%s has no method %s" % [called_as, method]
+	if required > 0:
+		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"]
+		)
+	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)
+		var type: int = returned.get("type", TYPE_NIL)
+		if type == TYPE_NIL and usage & PROPERTY_USAGE_NIL_IS_VARIANT == 0:
+			return (
+				"%s.%s is declared -> void, so it does something rather than answering%s"
+				% [called_as, method, READS_ONLY]
+			)
+		return ""
+	if _native_flags(object, method) & METHOD_FLAG_CONST == 0:
+		return "%s.%s changes what it is called on rather than reading it%s" % [called_as, method, READS_ONLY]
+	return ""
+
+
+## The entry a script attached to [param object] declares for [param method], or an empty one when
+## the method is the engine's.
+static func _script_method(object: Object, method: String) -> Dictionary:
+	var attached: Variant = object.get_script()
+	if not attached is Script:
+		return {}
+	var script: Script = attached
+	for entry: Dictionary in script.get_script_method_list():
+		if str(entry.get("name", "")) == method:
+			return entry
+	return {}
+
+
+## The flags the engine declares [param method] with on [param object].
+static func _native_flags(object: Object, method: String) -> int:
+	for entry: Dictionary in object.get_method_list():
+		if str(entry.get("name", "")) == method:
+			var flags: int = entry.get("flags", 0)
+			return flags
+	return 0
+
+
 ## Put [param value] where [param named] points. Only ever called once [method can_read] agrees,
 ## and lists and maps are reference types, so writing into one reaches the game's own copy.
 static func write(holder: Variant, named: String, value: Variant) -> void:
@@ -243,10 +319,7 @@ static func write(holder: Variant, named: String, value: Variant) -> void:
 		var map: Dictionary = holder
 		# Written back under the key it was found under, since a map keyed by StringName and one
 		# keyed by String both read the same way and a write to the wrong one adds a second entry.
-		if map.has(named):
-			map[named] = value
-		else:
-			map[StringName(named)] = value
+		map[_key_in(map, named)[0]] = value
 		return
 	var object: Object = holder
 	object.set(named, value)
@@ -265,9 +338,7 @@ static func read_under(holder: Variant, named: String) -> Variant:
 		return list[_index_in(named, len(holder))]
 	if holder is Dictionary:
 		var map: Dictionary = holder
-		if map.has(named):
-			return map[named]
-		return map[StringName(named)]
+		return map[_key_in(map, named)[0]]
 	var object: Object = holder
 	var method: String = method_of(named)
 	if not method.is_empty():
@@ -311,6 +382,14 @@ static func nothing_there(holder: Variant, named: String, called_as: String) ->
 			return container_calls_refused(called_as, "a map", container_call)
 		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
+		# saying the map has no key 3 while listing 3 among its keys contradicts itself.
+		for key: Variant in keys:
+			if str(key) == named:
+				return (
+					"%s has a key that reads %s, but it is %s, which a path step cannot name"
+					% [called_as, named, type_string(typeof(key))]
+				)
 		# Eight of them, because a map keyed by something unexpected is told by the first few and a
 		# map of two hundred would bury the sentence saying which key was missing.
 		var some: Array[String] = []
@@ -323,13 +402,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():
-		var required: int = _arguments_required(object, method)
-		if required == -1:
-			return "%s has no method %s" % [called_as, method]
-		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"]
-		)
+		return call_refused(object, method, called_as)
 	# 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):