Custom annotations through GDExtension / better annotations overall

[CREAsTIVE]

So i was trying to see if it possible to make custom annotations. I didn't find any documentation about it, so i got into source code too see if it possible to add custom annotations there.
All annotations being registered at gdscript_parser.cpp#L96, its seems that adding one would be easy, if only there was a public API of GDScriptParser instance at gdextension. Is it possible? If not, i would be happy to start a new proposal.

Also, IMO, annotations should be able to modify output node (pass node as Node *&p_target or Node **p_target at gdscript_parser.h#L1376), or even consume it and split another (like derive macro in rust) (requires to slitly fix all other annotations). In that way it will be possible to make custom complex annotations and more built-in annotations

For example decorator from python (used variadic syntax):

func sync(fn: Callable, base_args: Dictionary) -> Callable:
	var wrapper := func (...args: Array):
		print("Syncing method call with type: " + base_args["type"])
		return fn.callv(args)
	
	return wrapper

@decorator(sync, {type="Always"})
func test(text: String):
	print(text)

that will be converted into

func test(...args: Array):
	return sync(test, {type="Always"}).callv(args)

(You can actually already do this by modifying nodes inside actual function node, but its looks akwards)

---

I would like to open 3 issues (custom annotations through gdextension, modifying / consuming node and decorator annotation) and implement it.

---

related:

• Add an annotation for dependent/computed variables in GDScript #8525
• Allow custom GDScript annotations which can be read at runtime #1316

[dalexeev]

We discussed custom annotations at a GDScript team meeting some time ago, here are some thoughts that came up:

1. We would not want to expose GDScriptParser in any form (including via GDExtension), since then we would have to maintain AST compatibility and other exposed concepts.
2. Custom annotations should be declared/registered by GDScript itself, if at all. Maybe a generic annotation like @data, @tag, etc. would be enough. Or we could allow arbitrary annotations with some prefix, like @data_serialize or @@serialize without registration (but then there will be no way to validate them at compile time).
3. We are not entirely sure what functionality should be available. Should annotations be just metadata about class members, or should they allow some advanced functionality similar to built-in annotations. Custom annotations will probably never be as powerful as built-in ones, which would require exposing the internals of GDScript (p.1). So advanced metaprogramming is unlikely to be available.

[CREAsTIVE]

I see. That means no modifying at AST level.

Then is it will be okay to implement some basic annotations for shared usage? There some suggestions i would glad to implement:

---

@listen(fn: Callable, type: ListenType = ListenType.Before)

enum ListenType {
  Before, After, # variable setter OR function invokation
  BeforeFunc, AfterFunc, # function invokation
  BeforeSet, AfterSet, # variable setter
  BeforeGet, AfterGet # variable getter
}

Invokes fn, pass to it same args as was passed into called function / setter / getter and some metadata. fn signature could be look something like that:

func (method_name: String, method_class: String, args: Array) -> void

API:

• Callable.add_listener(fn: Callable, type: ListenType)
  Adds fn as listener for self
• Callable.remove_listener(fn: Callable, type: ListenType)
• Object.add_listener(field: String, fn: Callable, type: ListenType)
  Adds fn as listener for field field of self
• Object.remove_listener(field: String, fn: Callable, type: ListenType)

Good for custom network variables and methods invocations sync (main reason why i am doing this btw) or logging any change of variable and (probably) more.

Easy to implement with some overhead at runtime

---

@wrap(before: Callable, after: Callable)

(separate function: @wrap_getter(...))

More powerful version of @listen, that allow to modify input arguments and output value on function (or setter) invocation. Works more like some kind of patcher.

before signature (returns new set of args, that will be passed into function):

func (method_name: String, method_class: String, args: Array) -> Array # new args

after signature (returns new result, that will be returned from function):

func (method_name: String, method_class: String, args: Array, result: Variant) -> Variant # new result

API:

• Callable.wrap(before: Callable, after: Callable)
  Wraps function
• Callable.unwrap(before: Callable, after: Callable)
  Unwraps function if found a wrapper with same Callable..? idk
• Callable.wrap_getter(before: Callable, after: Callable)
• Callable.unwrap_getter(before: Callable, after: Callable)
• Object.wrap_field(field: String, before: Callable, after: Callable)
  Wraps field field of self
• Object.unwrap_field(field: String, before: Callable, after: Callable)
• Object.wrap_field_getter(field: String, before: Callable, after: Callable)
• Object.unwrap_field_getter(field: String, before: Callable, after: Callable)

Can be used as @listen. I don't sure if it really necessary to modify args and result, but it probably still can be useful in some rare cases.

Also easy to implement with some overhead at runtime

---

Maybe use some custom syntax for wrappers/listeners, like you mention. Instaed of @listen(something) do @@something

---

Let me know if any of that has chance to be added and i will open a issue with more technical realisation details

[CREAsTIVE]

I mean, do we really need to care if something is ugly or not if it were to only exist internally?

you will be able to access that functions, that the only reason i gave them names and don't keep them internal only.

[CREAsTIVE]

What if instead we add Callable.underlying to core, that will be nullable reference to a method? In that way it will be minimal performance impact and we can use it to store and expose underlying method

[leandro-benedet-garcia]

Why you want to expose a function that was generated by the annotation tho?

[CREAsTIVE]

@leandro-benedet-garcia see #12603 (reply in thread)

[leandro-benedet-garcia]

@leandro-benedet-garcia see #12603 (reply in thread)

Sorry, that doesn't explain, why do you want to access/expose the original function? That seems like an odd design decision and something that no other language really do

You can simply call a not annotated function inside an annotated one if you ever want to have the two different behaviors, for example:

var characters: Array[Node2D]

func manually_create_character(name: StringName, pos: Vector2):
    var isnt := Node2D.new()
    inst.name = name
    inst.position = pos
    return inst

@register_automatically
func create_character(name: StringName, pos: Vector2):
    var created = manually_create_character(name, pos)
    characters.append(created)

Using auto generated methods is always a bad idea because the name will be different, dirty and not good overall, and it's something very rare for you to actually want. Decorated methods have a different behavior and thus is a good idea to have them separated, localized inside your code base.

Not only that, people maintaining the code will not be able to find the function.