gdjn  Check-in [e72ff06ec2]

this was not as bad as it could have been. janet has something [^deficient magnificent] in its stdlib that every language should have: a PEG module. the resulting program, ["tool/class-compile.janet] is under 1k lines! just barely. this tool is fired off by the makefile for the ["src/*.gcd] files, generating a header file ["gen/*.h] and an object file ["out/*.o] that implements the class described in the file. the care and feeding of this file format is described in the [>gcd GCD section].

	deficient: it is deficient in one particular way: it only operates over bytestrings. so you can use a PEG to parse raw text, or you can use it to implement a lexer, but you can't have both a PEG lexer and parser, which is really fucking dumb and makes things like dealing with whitespace far more painful than it needs to be.)

##obj object model
godot uses a strongly javalike OOP system, which translates poorly to Janet's prototype-based OO. gdjn therefore uses the following convention to translate between the two.

the engine executes the "compile-time" phase of a janet script once it is finished loading. it is the responsibility of the compile-time thunk to set up the local environment to represent a class using def statements. the abstract serves as a proxy for method calls. when a lookup is performed against a class proxy, the proxy inspects its attached environment and returns an appropriate object.



unadorned immutable bindings are treated as constants. values with the [":field type] annotation are treated as object fields. when a new instance is created, space is allocated for a field of the appropriate type, and initialized to the value of the binding. public [`var] mutable bindins are treated as static variables.

~~~[janet] example bindings
(def name "Lisuan") # constant string
(def name :field "Lisuan") # field of type string, initializes to "Lisuan"
(def name {:field :variant} "Lisuan") field of type variant
(def- secret "swordfish") # private constant
(def- secret :field "swordfish") # private string field
(var count 0) # static variable of type int
(var- count 0) # private static variable of type int
~~~

unadorned functions are treated as static functions.

private functions (those declared with [`def-]) are available only within the class implementation. they are not exported as methods.

functions with the annotation [":method] are treated as methods. when invoked, they are passed a [`self]-reference as their first argument.

function type signatures can be specified with the annotations [":takes [...]] and [`:gives [$type]].

tables with the annotation [":subclass] are treated as environment tables specifying inner classes. the macro [`subclass] should generally be used to maintain uniform syntax between outer and inner classes, e.g.

~~~[janet]
(use core)
(use-classes Object RefCounted)
(declare outerClass :is Object)
(def val 10)
(prop v vec3)


(defclass innerClass :is RefCounted
	(def val 2))

# equivalent to
(import prim)
(def Object (prim/load-class :Object))
(def RefCounted (prim/load-class :RefCounted))
(def *class-name* :meta :outerClass)
(def *class-inherit* :meta Object)
(def val 10)



(def innerClass (do
	(def *class-inherit* :meta RefCounted)

	(let [env (table/setproto @{} (curenv))]
		(eval '(do
			(def val 2))
		env)
	env)))
~~~

since the annotations are somewhat verbose, macros are provided to automate the process.

+ janet + gdscript
| ["(def count 10)] | ["const count := 10]
| ["(def count {:field int} 10)] | ["var count: int = 10]
| ["(defn open [path] ...)] | ["static func open(path: Variant) ...]
| ["(defn open {:takes [:string] :gives :int} [path] ...)] | ["static func open(path: String) -> int:  ...]
| ["(defn close :method [me] ...)] |  func close() -> void: ...

this was not as bad as it could have been. janet has something [^deficient magnificent] in its stdlib that every language should have: a PEG module. the resulting program, ["tool/class-compile.janet] is under 1k lines! just barely. this tool is fired off by the makefile for the ["src/*.gcd] files, generating a header file ["gen/*.h] and an object file ["out/*.o] that implements the class described in the file. the care and feeding of this file format is described in the [>gcd GCD section].

	deficient: it is deficient in one particular way: it only operates over bytestrings. so you can use a PEG to parse raw text, or you can use it to implement a lexer, but you can't have both a PEG lexer and parser, which is really fucking dumb and makes things like dealing with whitespace far more painful than it needs to be.)

##obj object model
godot uses a strongly javalike OOP system, which translates poorly to Janet's prototype-based OO. gdjn therefore uses the following convention to translate between the two.

class definitions are represented by janet environments. any environment with the proper definitions and annotations can be treated as a class, whether from janet code or from GDScript. environments that do not define a class are treated as simple janet modules; their functionality is exported to GDScript by representing a janet module as an abstract class with only static members.

the engine/editor executes the "compile-time" phase of a janet script once it is finished loading or saving. it is the responsibility of the compile-time thunk to define the runtime behavior of the class by populating the environment with the proper bindings. 

unadorned immutable bindings are treated as constants. values with the [":field type] annotation are treated as object fields. when a new instance is created, space is allocated for a field of the appropriate type, and initialized to the value of the binding. public [`var] mutable bindings are treated as static variables.

~~~[janet] example bindings
(def name "Lisuan") # constant string
(def name :prop "Lisuan") # field of type string, initializes to "Lisuan"
(def name {:prop :variant} "Lisuan") field of type variant
(def- secret "swordfish") # private constant
(def- secret :prop "swordfish") # private string field
(var count 0) # static variable of type int
(var- count 0) # private static variable of type int
~~~

unadorned functions are treated as static functions.

private functions (those declared with [`def-]) are available only within the class implementation. they are not exported as methods.

functions with the annotation [":method] are treated as methods. when invoked, they are passed a [`self]-reference as their first argument.

function type signatures can be specified with the annotation ["{:method {:sig [ty name ...] :ret ret-type}}].

tables with the annotation [":subclass] are treated as environment tables specifying inner classes. the macro [`defclass] should generally be used to maintain uniform syntax between outer and inner classes, e.g.

~~~[janet]

(use-classes Object RefCounted)
(declare outerClass :is Object)
(def val 10)
(prop t :float 0)
(conf v :vec3 0 0 0)
(data x :packed-byte-array [])
(defclass innerClass :is RefCounted
	(def val 2))

# equivalent to
(use core) # implicit
(def Object (prim/load-class :Object))
(def RefCounted (prim/load-class :RefCounted))
(def @id :outerClass)
(def @inherit Object)
(def val 10)
(def t {:prop :float} 0)
(def v {:prop :vector3} :export 0)
(def x {:prop :packed-byte-array} :export-storage [])
(def innerClass (do

	(def @inherit RefCounted)
	(let [env (table/setproto @{} (curenv))]
		(eval '(do
			(def val 2))
		env)
	env)))
~~~

since the annotations are somewhat verbose, macros are provided to automate the process. note that while the subclass mechanism looks exceptionally tricksy and aggressively dynamic, all of the class definition code is executed completely at compile-time, so there is no runtime cost to defining a subclass rather than a top-level class.

+ janet + gdscript
| ["(def count 10)] | ["const count := 10]
| ["(def count {:field int} 10)] | ["var count: int = 10]
| ["(defn open [path] ...)] | ["static func open(path: Variant) ...]
| ["(defn open {:takes [:string] :gives :int} [path] ...)] | ["static func open(path: String) -> int:  ...]
| ["(defn close :method [me] ...)] |  func close() -> void: ...

			JanetString str = janet_unwrap_string(s);
			return (pstr) {
				.v = (char*)str,
				.sz = janet_string_length(str),
			};
		}



	};
	impl _reload(bool keepState) -> int {
		gd_array_clear(&me -> methodBinds);
		/* parse the class environment */
		JanetTable* const env = me -> env;
		printf("core reload\n");

			JanetString str = janet_unwrap_string(s);
			return (pstr) {
				.v = (char*)str,
				.sz = janet_string_length(str),
			};
		}
	};
	impl _get_script_method_list() -> array[dictionary] {
		return me -> methodBinds;
	};
	impl _reload(bool keepState) -> int {
		gd_array_clear(&me -> methodBinds);
		/* parse the class environment */
		JanetTable* const env = me -> env;
		printf("core reload\n");