Module-level static declarations (closes #7452)

[nadako]

This PR implements module-level function, var and property declaration (proposed and discussed in HaxeFoundation/haxe-evolution#24):

final version = 4;

function main() {
    trace("Hello from version " + version);
}

Generated JS

function Main_main() {
	console.log("src/Main.hx:4:","Hello from version " + Main_version);
}
var Main_version = 4;
Main_main();

This is implemented the following way:

• Definition:
  • Parse such declarations into the new type_def variant: EStatic of (placed_access, class_field_kind) definition
  • When loading module, all its EStatics are collected into a list of static fields for an implicitly created class (fields are public unless explicitly defined as private, just like types)
  • Class is created with a special cl_kind: KModuleStatics of module_def
  • Class is then stored into its module using new field m_statics : tclass option
• Import:
  • import Mod will import all the module-level statics
  • import Mod.func [as name] will first try importing module-level func and Mod.func static field
  • import Mod.* will NOT import module-level statics (debatable, but consistent with it not importing other module-level declarations)
• Resolution:
  • Unqualified name will first search for this-module statics and then imported ones
  • Qualified path will first look for module-level statics and then fall back to sub-type and main-type-static resolution.
• Misc:
  • -main Mod works with module-level main function
  • using Mod will consider module-level static extension functions
  • Module-level macro functions are also supported
• Macro:
  • New haxe.macro.Type.ClassKind variant: KModuleStatics(module:String)
  • New haxe.macro.Expr.TypeDefKind variant: TDStatic(kind:FieldType, ?access:Array<Access>)
• Generation:
  • Target generator can choose to not generate KModuleStatics class and instead output functions and vars directly (implemented for JS)
  • If target still has to wrap them in class it can at least omit reflection helpers and apply extra optimizations (e.g. add static/final modifiers)

TODO checklist:

• handle imported module-statics resolution
• handle import pack.Module.moduleLevel
• handle import pack.Module.moduleLevel as otherName
• handle pack.Module.moduleLevel access (the MORDOR)
• refactor TyperDotPath into something readable
• finish parsing, support var, property, modifiers, etc.
• adjust haxe.macro.Expr API
• think of macro API to retrieve the statics class
• discuss and decide module-scoping or package scoping
• think of static extensions
• handle display stuff
  • resume
• double-check positions
• check access control (i.e. @:access)
• check @:rtti (ugh)
• check haxe.PosInfos
  • (not) solve this as part of haxe.PosInfos.className in abstract types #9214
• add tests
  • test module-level -main on different targets (e.g. java)
  • test Context.defineType/defineModule for statics
• support class-less main
• support class-less --macro calls and @:build (tame eval)
• flatten module-statics class in genjs (as an example)
• discuss import Mod.*
• filter out private when importing not to pollute the local namespace (prevents @:privateAccess but is consistent with private types)

---

Things that can be done after the merge: #9436

[RealyUniqueName]

Why is it called "globals" in AST but "module statics" after typing?

[nadako]

Why is it called "globals" in AST but "module statics" after typing?

Naming is hard :)

Well the idea is that the untyped AST does not care about whether it's implemented as statics or not, so it uses the term "global", which might as well be "module-local" or something, I'm not really sure.

In the typed AST it's implemented as statics collected in a class, so it makes sense to name it as that.

[nadako]

Well the idea is that the untyped AST does not care about whether it's implemented as statics or not, so it uses the term "global", which might as well be "module-local" or something, I'm not really sure.

Thinking about this with a "fresh" head, maybe we should officially call them module statics. It is easy to pronounce, close to the implementation and rather easy to understand: "like class statics, but module statics".

[nanjizal]

So you could have module level static functions, with module level properties and constants ( finals ) soon to be implemented, but are you going to change EGlobal to EModule ?

[nadako]

EStatic, I guess, but yeah :)

[fullofcaffeine]

Will modules have some kind of initialiser hook? I mean, in js you can just add code to the body to be ran when at runtime when the module is interpreted and it can be quite useful.

[nadako]

Will modules have some kind of initialiser hook? I mean, in js you can just add code to the body to be ran when at runtime when the module is interpreted and it can be quite useful.

I am not sure what exactly are you asking here. In JS modules are loaded at run-time, while in Haxe we just load them at compile-time to find and build the classes, there's no concept of a module at run-time.

[fullofcaffeine]

I'm aware that it's a compile-time feature. I was just curious if some abstraction for initialization would be provided that would then run at runtime, but I'm probably not fully aware of the implementation and how it's going to work.

[RealyUniqueName]

I wonder if defining function __init__() would automatically work with the same semantics as static function __init__() because module functions get compiled as static function of an auto-genetared class.

[nadako]

I think it will, but so will var initializations - both will be executed at program startup.

[nadako]

This should close #7452

[nadako]

(blindly) rebased on top development with all the latest changes, let's see if tests still pass

[nadako]

I need to check and add test for the behaviour of module-statics regarding #9367, and will merge afterwards.

[jeremyfa]

A fun side effect of this evolution is that one could create module level code in, say, Mod.hx and make it compatible with hscript very easily (no surrounding class etc...).

Looking awesome overall!

[uvtc]

Any guess as to what release this will land in?

[uvtc]

Whoops. Sorry, just realized https://github.com/HaxeFoundation/haxe-evolution/blob/master/proposals/0007-module-level-funcs.md says 4.2.0.

[codingthat]

Just curious, are these still to do, or just didn't get checked off formally?

[nadako]

Still kinda to do. For the "display stuff" there are separate issues now, rtti and access controls are... also waiting for specific issues :)