What makes `unit` be too late?

[arkiuat]

• The docs state (and have stated for many years) that a unit declaration at the beginning of a file may be preceded only by comments and use statements.
• However, any declaration of sub EXPORT must precede the unit declaration.
• Neither requirement seems to be tested in any roast tests that I could find (but I'm still a novice at searching in the roast repo).

The blocked docs issue Raku/doc#2148 is over seven years old, and the problem it describes is still in the current docs.

The statement at issue in the docs is in https://docs.raku.org/language/syntax#package,_module,_class,_role,_and_grammar_declaration and is currently worded as:

you can declare a unit package at the start of the file (preceded only by comments or use statements),

The conflicting (assuming that unit packages can make use of sub EXPORT) statement is in https://docs.raku.org/language/modules#EXPORT :

Please note that EXPORT can't be declared inside a package because it is part of the compunit rather than the package.

This issue is a re-open of the closed rakudo issue rakudo/rakudo#2020 as a problem-solving issue, as suggested at the time that issue was closed.

[librasteve]

does this mean that unit cannot be used with sub EXPORT -or- that you can declare sub EXPORT before the unit line?

[not asking for ROAST info - just what do es hte latest rakudo do in practice]

[arkiuat]

@librasteve, the original issue stated that you can in fact declare any number of subs before a unit package. I just tested declaring an empty sub EXPORT followed by a unit package and got no errors

[librasteve]

tx! so let's document that ;-)

[arkiuat]

There was some discussion of that on the other issues linked above, and there's reluctance to document things that ROAST doesn't require, which makes sense, since all such behavior is technically implementation detail and not part of the language we're documenting.

Discussion to come to a consensus (about what ROAST should require here) got bogged down in the now-closed rakudo issue rakudo/rakudo#2020, which is why I opened this one, because lack of such consensus is what's blocking the docs issue Raku/doc#2148.

My own opinion about what the consensus seemed to be groping toward is that sub EXPORTand the like should be allowed (like comments and use statements) before a unit declaration, but that any sub not explicitly allowed there should be disallowed.

By 'and the like' I mean any other ALL-CAPS subs clearly connected to the namespace in question (as EXPORT is) but which for some reason have to live outside that namespace. This is intended to cover both future developments and also possibly other existing language features that I haven't learned about yet: the general principle is that there's an allowlist for this, and anything not on it would cause squawking.

[librasteve]

@arkiuat - I agree