gdharness 1.2.30 → 1.2.32

package/build/godot/operations/audio_buses.gd

@@ -83,7 +83,20 @@ func get_audio_buses(_params: Dictionary) -> Dictionary:
 	var buses: Array[Dictionary] = []
 	for i: int in range(AudioServer.bus_count):
 		buses.append(_bus(i))
-	return {"bus_count": AudioServer.bus_count, "buses": buses, "layout": _layout_path()}
+	var layout: String = _layout_path()
+	var answer: Dictionary = {"bus_count": AudioServer.bus_count, "buses": buses, "layout": layout}
+	# The setting names a path whether or not anything is there, and a project that never changed a
+	# bus has no file: the path alone read as a layout the project keeps.
+	if not FileAccess.file_exists(layout):
+		answer["layout_on_disk"] = false
+		answer["note"] = (
+			(
+				"Nothing is at %s, so these are the engine's default buses; the first change to a bus "
+				+ "writes the layout there."
+			)
+			% layout
+		)
+	return answer
 
 
 func set_audio_bus_effect(params: Dictionary) -> Dictionary:

package/build/godot/operations/class_cache.gd

@@ -93,13 +93,13 @@ func _entry_for(path: String, skipped: Array[Dictionary]) -> Dictionary:
 	if declared.is_empty():
 		return {}
 
-	var base: String = _base_of(path, header, skipped)
-	if base.is_empty():
+	var base: Variant = _base_of(path, header, skipped)
+	if base == null:
 		return {}
 
 	# The field order is the editor's, so a rebuilt file reads as one the editor wrote.
 	return {
-		"base": StringName(base),
+		"base": StringName(str(base)),
 		"class": StringName(declared),
 		"icon": str(header.get("icon", "")),
 		"is_abstract": Read.as_bool(header.get("abstract", false)),
@@ -109,46 +109,157 @@ func _entry_for(path: String, skipped: Array[Dictionary]) -> Dictionary:
 	}
 
 
-# What the editor records as the base: the nearest ancestor with a class_name, else the native
-# class at the top of the chain. A script that extends by path is followed to its own header.
-func _base_of(path: String, header: Dictionary, skipped: Array[Dictionary]) -> String:
-	var visited: Array[String] = [path]
-	var current: Dictionary = header
+# What the editor records as the base, worked out as the engine's own class scan works it out,
+# measured on 4.7.2 against `--import`, so a rebuilt list is the one the editor would write and a
+# rebuild over a current list changes nothing:
+#
+# - nothing extended: RefCounted;
+# - one name, a global class or a native one: that name, unresolved;
+# - a dotted name, `Heard.Named`, an inner class of a global class: nothing, as the scan does not
+#   look names up;
+# - a path: what that script's class records, after walking into the inner classes named after
+#   the path, `"res://heard.gd".Named`, so a parent with a class_name is passed over for its own
+#   base. A path the engine cannot open records nothing, and it opens a relative one from the
+#   project root rather than from the script's folder.
+#
+# Null for a script that extends itself, which is left out of the list and named in [param skipped].
+func _base_of(path: String, header: Dictionary, skipped: Array[Dictionary]) -> Variant:
+	var visited: Array[String] = [path + ":"]
+	var extends_what: Variant = header.get("extends", null)
 	while true:
-		var extends_what: String = str(current.get("extends", ""))
-		if extends_what.is_empty():
+		if extends_what == null:
 			return "RefCounted"
-		if not (extends_what.begins_with('"') or extends_what.begins_with("'")):
-			return extends_what
-		var parent_path: String = extends_what.substr(1, extends_what.length() - 2)
-		if not parent_path.begins_with("res://"):
-			parent_path = visited[visited.size() - 1].get_base_dir().path_join(parent_path)
-		if not FileAccess.file_exists(parent_path):
-			skipped.append({"path": path, "reason": "extends a script that does not exist: " + parent_path})
+		var parts: Dictionary = _extends_parts(str(extends_what))
+		var parent_path: String = parts["path"]
+		var names: Array[String] = parts["names"]
+		if parent_path.is_empty():
+			return names[0] if names.size() == 1 else ""
+		var opened: String = _as_the_engine_opens(parent_path)
+		if not FileAccess.file_exists(opened):
 			return ""
-		if parent_path in visited:
+		var reached: String = opened + ":" + ".".join(PackedStringArray(names))
+		if reached in visited:
 			skipped.append({"path": path, "reason": "extends itself through " + parent_path})
+			return null
+		visited.append(reached)
+		var lines: PackedStringArray = FileAccess.get_file_as_string(opened).split("\n")
+		if names.is_empty():
+			extends_what = _header_in(lines).get("extends", null)
+			continue
+		var inner: Dictionary = _inner_class(lines, names)
+		if inner.is_empty():
 			return ""
-		visited.append(parent_path)
-		current = _header_of(parent_path)
-		var parent_name: String = str(current.get("class_name", ""))
-		if not parent_name.is_empty():
-			return parent_name
+		extends_what = inner.get("extends", null)
 	return ""
 
 
-# The declarations at the top of a script: class_name, what it extends (a class name, or a
-# quoted path), and the @tool, @abstract and @icon annotations. Reading stops at the first
-# statement that is none of those, which is where the body begins.
+# The path and the class names an `extends` names, from the text after the keyword:
+# `"res://heard.gd".Named` is the path and ["Named"], `Heard.Named` no path and two names. The
+# reading stops at whatever follows, a colon or a comment.
+static func _extends_parts(text: String) -> Dictionary:
+	var rest: String = text.strip_edges()
+	var path: String = ""
+	if rest.begins_with('"') or rest.begins_with("'"):
+		var closing: int = rest.find(rest[0], 1)
+		if closing == -1:
+			return {"path": "", "names": [] as Array[String]}
+		path = rest.substr(1, closing - 1)
+		rest = rest.substr(closing + 1)
+	var names: Array[String] = []
+	var name_at: RegEx = Patterns.compiled("^([A-Za-z_][A-Za-z0-9_]*)")
+	var dotted: bool = not path.is_empty()
+	while true:
+		if dotted:
+			if not rest.begins_with("."):
+				break
+			rest = rest.substr(1)
+		dotted = true
+		var found: RegExMatch = name_at.search(rest)
+		if found == null:
+			break
+		names.append(found.get_string(1))
+		rest = rest.substr(found.get_end())
+	return {"path": path, "names": names}
+
+
+# The file the engine's class scan reads for an `extends` path. It opens the path as written, and
+# the engine runs from the project root, so a relative path is read from there.
+static func _as_the_engine_opens(path: String) -> String:
+	if path.is_absolute_path():
+		return path
+	var absolute: String = ProjectSettings.globalize_path("res://").path_join(path).simplify_path()
+	return ProjectSettings.localize_path(absolute)
+
+
+# The inner class [param names] reaches in a script of [param lines], one class inside the
+# previous, as {"found": true, "extends": the text after its keyword} with no "extends" for one that
+# extends nothing, or {} when one of them is not there.
+func _inner_class(lines: PackedStringArray, names: Array[String]) -> Dictionary:
+	var class_line: RegEx = Patterns.compiled("^class\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*(.*)$")
+	var inline_extends: RegEx = Patterns.compiled("^extends\\s+(.*)$")
+	var start: int = 0
+	var end: int = lines.size()
+	var depth: int = 0
+	var found: Dictionary = {}
+	for name: String in names:
+		var at: int = -1
+		found = {"found": true}
+		for index: int in range(start, end):
+			var text: String = lines[index].strip_edges()
+			if text.is_empty() or text.begins_with("#") or _indent(lines[index]) != depth:
+				continue
+			var declared: RegExMatch = class_line.search(text)
+			if declared == null or declared.get_string(1) != name:
+				continue
+			at = index
+			var inline: RegExMatch = inline_extends.search(declared.get_string(2).strip_edges())
+			if inline != null:
+				found["extends"] = inline.get_string(1)
+			break
+		if at == -1:
+			return {}
+		start = at + 1
+		var body_end: int = start
+		var body_depth: int = -1
+		for index: int in range(start, end):
+			var text: String = lines[index].strip_edges()
+			if not text.is_empty() and not text.begins_with("#"):
+				var width: int = _indent(lines[index])
+				if width <= depth:
+					break
+				if body_depth == -1:
+					body_depth = width
+			body_end = index + 1
+		end = body_end
+		depth = body_depth
+		if not found.has("extends"):
+			var body: Dictionary = _header_in(lines.slice(start, end))
+			if body.has("extends"):
+				found["extends"] = body["extends"]
+	return found
+
+
+static func _indent(line: String) -> int:
+	return line.length() - line.lstrip(" \t").length()
+
+
 func _header_of(path: String) -> Dictionary:
+	if not FileAccess.file_exists(path):
+		return {}
+	return _header_in(FileAccess.get_file_as_string(path).split("\n"))
+
+
+# The declarations at the top of a script: class_name, what it extends (the text after the
+# keyword, a class name or a quoted path, either followed by inner class names), and the @tool,
+# @abstract and @icon annotations. Reading stops at the first statement that is none of those,
+# which is where the body begins.
+func _header_in(lines: PackedStringArray) -> Dictionary:
 	var header: Dictionary = {}
-	var file: FileAccess = FileAccess.open(path, FileAccess.READ)
-	if not file:
-		return header
 	var annotation: RegEx = Patterns.compiled('^@([a-z_]+)(?:\\(\\s*(?:"([^"]*)")?[^)]*\\))?\\s*')
-	var extends_line: RegEx = Patterns.compiled("^extends\\s+(\\S+)")
-	while not file.eof_reached():
-		var rest: String = file.get_line().strip_edges()
+	var extends_line: RegEx = Patterns.compiled("^extends\\s+(.*)$")
+	var same_line: RegEx = Patterns.compiled("^\\s+extends\\s+(.*)$")
+	for line: String in lines:
+		var rest: String = line.strip_edges()
 		# Annotations may share a line with what they annotate, as in `@abstract class_name X`.
 		var annotated: RegExMatch = annotation.search(rest)
 		while annotated != null:
@@ -167,15 +278,15 @@ func _header_of(path: String) -> Dictionary:
 			var declared: RegExMatch = Patterns.declared_class(rest)
 			if declared != null:
 				header["class_name"] = declared.get_string(1)
-				if not declared.get_string(2).is_empty():
-					header["extends"] = declared.get_string(2)
+				var after: RegExMatch = same_line.search(rest.substr(declared.get_end(1)))
+				if after != null:
+					header["extends"] = after.get_string(1)
 		elif rest.begins_with("extends"):
 			var parent: RegExMatch = extends_line.search(rest)
 			if parent != null:
 				header["extends"] = parent.get_string(1)
 		else:
 			break
-	file.close()
 	return header
 
 

package/build/godot/operations/classdb_queries.gd

@@ -2,6 +2,7 @@ extends RefCounted
 
 const Read = preload("reading.gd")
 const Log = preload("logger.gd")
+const Serialisation = preload("serialisation.gd")
 
 # The base classes each category name stands for. Kept to the list the tool's schema offers, which
 # a case holds: the schema offered physics3d and ui, which this refused, and physics answered the 3D
@@ -22,6 +23,7 @@ const CATEGORY_BASES: Dictionary = {
 }
 
 var _log: Log
+var _values: Serialisation = Serialisation.new()
 
 
 func _init(p_log: Log) -> void:
@@ -318,19 +320,24 @@ func _methods_of(class_name_str: String, include_inherited: bool) -> Array[Dicti
 				}
 			)
 		var return_info: Dictionary = m.get("return", {})
-		methods.append(
-			{
-				"name": m.get("name", ""),
-				"args": args,
-				"return":
+		(
+			methods
+			. append(
 				{
-					"type": return_info.get("type", 0),
-					"type_name": _type_name(return_info, "void"),
-					"class_name": return_info.get("class_name", "")
-				},
-				"flags": m.get("flags", 0),
-				"default_args": m.get("default_args", [])
-			}
+					"name": m.get("name", ""),
+					"args": args,
+					"return":
+					{
+						"type": return_info.get("type", 0),
+						"type_name": _type_name(return_info, "void"),
+						"class_name": return_info.get("class_name", "")
+					},
+					"flags": m.get("flags", 0),
+					# As values, tagged the way every other answer tags one: JSON writes a Vector2i it is
+					# handed as its text, so TileMapLayer.set_cell's default atlas coords read "(-1, -1)".
+					"default_args": _values.serialize_value(m.get("default_args", []))
+				}
+			)
 		)
 
 	return methods

package/build/godot/operations/file_reads.gd

@@ -0,0 +1,237 @@
+extends RefCounted
+
+## Scenes and resources read from their files, by the editor's tools and by a headless engine with
+## none connected, so a read answers the same either way.
+##
+## A scene is read off its SceneState rather than instantiated. Instantiating outside the editor
+## runs every script's member initialisers and _init (measured on 4.7.2, with or without -e), so a
+## read with no editor would have run the game's code on every node; the editor gets placeholders
+## and runs none. The state holds everything the file says, and the scenes it instances theirs,
+## without making a node. Loading the file still does what loading does in the game: static
+## initialisers run, and a resource with a script is made with it.
+
+const PropertyValues = preload("property_values.gd")
+const Read = preload("reading.gd")
+const Serialisation = preload("serialisation.gd")
+
+
+## The nodes of [param scene_path] as {name, type, path, children}, with instanceOf on a node that
+## instances another scene and every stored property when [param include_properties] is set, the
+## file's value or the default where it sets none. [param depth] -1 reads every level.
+static func scene_tree(scene_path: String, depth: int, include_properties: bool) -> Dictionary:
+	if not FileAccess.file_exists(scene_path):
+		return {"ok": false, "error": "Scene not found: " + scene_path}
+	# Loaded without naming the type, so a resource handed in by mistake loads as what it is and the
+	# refusal can say so, where asking for a PackedScene printed the loader's error and a backtrace.
+	var loaded: Resource = ResourceLoader.load(scene_path, "", ResourceLoader.CACHE_MODE_IGNORE)
+	if loaded == null:
+		return {"ok": false, "error": "Failed to load %s as a scene" % scene_path}
+	if not loaded is PackedScene:
+		return {
+			"ok": false,
+			"error":
+			(
+				"%s is a %s, not a scene: resource_edit read reads its properties."
+				% [scene_path, loaded.get_class()]
+			)
+		}
+	var packed: PackedScene = loaded
+	var nodes: Dictionary = {}
+	var refused: String = _lay(packed.get_state(), ".", nodes, [scene_path])
+	if not refused.is_empty():
+		return {"ok": false, "error": refused}
+	if not nodes.has("."):
+		return {"ok": false, "error": "%s holds no nodes" % scene_path}
+	return {"ok": true, "tree": _entry(nodes, ".", include_properties, depth, 0)}
+
+
+## Lays the nodes of [param state] into [param nodes] under [param prefix], keyed by their path
+## from the outermost root, each instanced scene laid where it is instanced and the instancing
+## file's own entries for it applied over it. Answers a refusal, or "".
+##
+## [param within] is the files being laid, outermost first, so a scene that instances one of them
+## is refused rather than laid forever; the engine refuses to load such a scene, so this is only
+## reached through a state built some other way.
+static func _lay(state: SceneState, prefix: String, nodes: Dictionary, within: Array) -> String:
+	var base: SceneState = state.get_base_scene_state()
+	if base != null and not nodes.has(prefix):
+		var refused: String = _lay(base, prefix, nodes, within)
+		if not refused.is_empty():
+			return refused
+	for index: int in state.get_node_count():
+		var path: String = _joined(prefix, str(state.get_node_path(index)))
+		var fresh: bool = not nodes.has(path)
+		if fresh:
+			var instance: PackedScene = state.get_node_instance(index)
+			if instance != null:
+				if within.has(instance.resource_path):
+					return "%s instances %s, which holds it" % [within.back(), instance.resource_path]
+				var refused: String = _lay(
+					instance.get_state(), path, nodes, within + [instance.resource_path]
+				)
+				if not refused.is_empty():
+					return refused
+				if not nodes.has(path):
+					return "%s holds no nodes" % instance.resource_path
+				nodes[path]["instanceOf"] = instance.resource_path
+			elif state.is_node_instance_placeholder(index):
+				nodes[path] = _made("InstancePlaceholder")
+				nodes[path]["instanceOf"] = state.get_node_instance_placeholder(index)
+			elif str(state.get_node_type(index)).is_empty():
+				# An entry for a node of an instance that no longer has it, which the engine skips too.
+				continue
+			else:
+				nodes[path] = _made(str(state.get_node_type(index)))
+		# The name is the state's even for an entry laid already, since an inherited scene names its
+		# root itself; a root instanced inside another scene is renamed by that scene once laid.
+		nodes[path]["name"] = str(state.get_node_name(index))
+		if fresh:
+			# The root of what is laid here is placed by whoever instanced it.
+			if path != prefix:
+				_place(
+					nodes,
+					_joined(prefix, str(state.get_node_path(index, true))),
+					path,
+					state.get_node_index(index)
+				)
+		var held: Dictionary = nodes[path]["properties"]
+		for property: int in state.get_node_property_count(index):
+			held[str(state.get_node_property_name(index, property))] = state.get_node_property_value(
+				index, property
+			)
+	return ""
+
+
+static func _made(type: String) -> Dictionary:
+	var children: Array[String] = []
+	return {"name": "", "type": type, "properties": {}, "children": children}
+
+
+## Puts [param path] among [param parent]'s children, at [param at] when the file says where (a node
+## added inside an instance) and last when it does not.
+static func _place(nodes: Dictionary, parent: String, path: String, at: int) -> void:
+	if not nodes.has(parent):
+		return
+	var children: Array[String] = nodes[parent]["children"]
+	if at >= 0 and at < children.size():
+		var _placed: int = children.insert(at, path)
+	else:
+		children.append(path)
+
+
+## [param given], a path as a SceneState gives it ("." or "./Body/Tail"), under [param prefix].
+static func _joined(prefix: String, given: String) -> String:
+	var relative: String = given.trim_prefix("./")
+	if relative == "." or relative.is_empty():
+		return prefix
+	if prefix == ".":
+		return relative
+	return prefix + "/" + relative
+
+
+static func _entry(
+	nodes: Dictionary, path: String, include_properties: bool, depth: int, current_depth: int
+) -> Dictionary:
+	var node: Dictionary = nodes[path]
+	var children: Array[Dictionary] = []
+	var data: Dictionary = {"name": node["name"], "type": node["type"], "path": path, "children": children}
+	# The root's file is the scene being read, so only another node's names a second scene.
+	if path != "." and node.has("instanceOf"):
+		data["instanceOf"] = node["instanceOf"]
+	if include_properties:
+		var given: Dictionary = node["properties"]
+		data["properties"] = _stored(str(node["type"]), given)
+	if depth >= 0 and current_depth >= depth:
+		return data
+	for child: String in node["children"]:
+		children.append(_entry(nodes, child, include_properties, depth, current_depth + 1))
+	return data
+
+
+## Every property a node of [param type] stores, with the value [param given] sets or the default,
+## read as a node holding those values would answer them.
+##
+## The engine's half is read off a bare node of the class with the file's values set on it, which
+## runs no script: what a node lists depends on its values (a thread group's settings appear only
+## once it has one) and some setters set others (a Control's anchors preset sets how it grows), so
+## the class's defaults and the file's entries alone answered neither. The script's half is its
+## declared defaults under the file's values.
+static func _stored(type: String, given: Dictionary) -> Dictionary:
+	var attached: Variant = given.get("script")
+	var script: Script = attached if attached is Script else null
+	var scripted: Dictionary = {}
+	if script != null:
+		for declared: Dictionary in script.get_script_property_list():
+			var property: String = str(declared.get("name", ""))
+			if not property.is_empty() and Read.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
+				scripted[property] = script.get_property_default_value(property)
+	var values: Dictionary = {}
+	if ClassDB.class_exists(type) and ClassDB.can_instantiate(type):
+		var bare: Object = ClassDB.instantiate(type)
+		for property: Variant in given:
+			if property != "script" and not scripted.has(property):
+				bare.set(str(property), given[property])
+		for declared: Dictionary in bare.get_property_list():
+			var property: String = str(declared.get("name", ""))
+			if not property.is_empty() and Read.as_int(declared.get("usage", 0)) & PROPERTY_USAGE_STORAGE:
+				values[property] = bare.get(property)
+		if bare is Node:
+			bare.free()
+	for property: String in scripted:
+		values[property] = scripted[property]
+	# Given last, which keeps what a bare node cannot hold: the script itself, and a path to a node
+	# for a property that holds the node once it is in a tree.
+	values.merge(given, true)
+	var serialiser: Serialisation = Serialisation.new()
+	var answered: Dictionary = {}
+	for property: Variant in values:
+		answered[property] = serialiser.serialize_value(values[property])
+	return answered
+
+
+## What a resource file holds, in the form modify takes, so a value read here can be written back.
+## Read from the file rather than a cached copy, since the file is what the writes change and what
+## the project loads.
+static func resource(res_path: String, include_defaults: bool) -> Dictionary:
+	if not FileAccess.file_exists(res_path):
+		return {"ok": false, "error": "No resource at " + res_path}
+	var loaded: Resource = ResourceLoader.load(res_path, "", ResourceLoader.CACHE_MODE_IGNORE)
+	if loaded == null:
+		return {"ok": false, "error": "%s did not load as a resource." % res_path}
+	# A scene's own properties are its packed bundle, which says nothing a caller can use.
+	if loaded is PackedScene:
+		return {
+			"ok": false,
+			"error":
+			"%s is a scene: scene_tree reads its nodes, and scene_node get one node's properties." % res_path
+		}
+
+	var script: Script = loaded.get_script()
+	var scripted: Dictionary = {}
+	if script != null:
+		for declared: Dictionary in script.get_script_property_list():
+			scripted[str(declared.get("name", ""))] = true
+	var serialiser: Serialisation = Serialisation.new()
+	var properties: Dictionary = {}
+	for p: Dictionary in loaded.get_property_list():
+		var property: String = str(p.get("name", ""))
+		if property.is_empty() or property == "script":
+			continue
+		if not (Read.as_int(p.get("usage", 0)) & PROPERTY_USAGE_STORAGE):
+			continue
+		var value: Variant = loaded.get(property)
+		if not include_defaults:
+			var default: Variant = (
+				script.get_property_default_value(property)
+				if scripted.has(property)
+				else ClassDB.class_get_property_default_value(loaded.get_class(), property)
+			)
+			if PropertyValues.same(value, default):
+				continue
+		properties[property] = serialiser.serialize_value(value)
+	var answer: Dictionary = {
+		"ok": true, "resourcePath": res_path, "resourceType": loaded.get_class(), "properties": properties
+	}
+	if script != null:
+		answer["script"] = script.resource_path
+	return answer