Private / non-exported bindings

[Beiri22]

Description

As far as I understand, each defined and imported function, varible and module inside a typ-file can be imported from another typ-file. I would wish for some way to tag the one that should not be imported from elsewhere (like helper functions, internal constants, modules only used internally) as private. Are there any plans for that?

Use Case

You write a library or template and don't want the user to see all internally used stuff in code completion...

[bluebear94]

You can already do something like this:

let (public-item-1, public-item-2, public-item-3) = {
  let public-item-1(x) = ...
  let private-item-1(x) = ...
  let private-item-2(x) = ...
  let public-item-2(x) = private-item-2(private-item-1(x))
  let public-item-3(x, y) = ...
  (public-item-1, public-item-2, public-item-3)
}

but this takes extra work, so being able to tag a function as private would be helpful.

[laurmaedje]

Another common pattern is a lib.typ that re-exports only the public stuff from impl.typ. But yeah, first-class support would be nice.

[tingerrr]

Another common pattern is a lib.typ that re-exports only the public stuff from impl.typ. But yeah, first-class support would be nice.

One downside is that this would only work for the top level module, or one would have to repeat it for each module.

I remember some prior discussion about this in the discord, I'll try to give a brief outline of what was discussed.

Both private by default and public by default were considered and have pros and cons:

• private by default
  • con: all existing code breaks, packages AND projects
  • con: new keyword required for exported bindings, further chance for breakage
  • pro: a good default for packages
  • con: a bad default for documents
• public by default
  • pro: no breakage at all
  • con: new keyword required for private bindings, further chance for breakage
  • pro: a good default for documents
  • con: a bad default for packages

Whether imports should be treated the same as let bindings is also an important question, as there is no difference in defining modules and importing them. Especially for public by default, exporting all imports by default makes designing good package APIs cumbersome.

Perhaps modules and re-exports from other modules must be declared explicitly as exports regardless of public or private by default bindings.

First class support is definitely important, because the current patterns don't make it easy for LSPs or doc generators to get a good grasp on what's in scope by deliberate choice.

I may have missed parts of the discussion, feel free to amend here.

[Enivex]

Could there be a global setting for public/private by default, in addition to more granular public/private keywords?

[tingerrr]

Could there be a global setting for public/private by default, in addition to more granular public/private keywords?

Perhaps, but I'm not sure if this is a good idea, where would it be configured, and how much would it affect?

[Enivex]

Could there be a global setting for public/private by default, in addition to more granular public/private keywords?

Perhaps, but I'm not sure if this is a good idea, where would it be configured, and how much would it affect?

I meant per-file. How exactly it would work I'm not sure. Presumably a flag at the top somewhere.

But it would solve the issue of wanting different defaults for documents and packages

[laurmaedje]

Aside from all private and all public, I see two further options:

• Exports are only needed on the package boundary, not the file boundary. Not sure how it would work in detail.

• Everything in a file is public unless at least one export is explicitly stated. This would be the opt-in flag so to speak, making the change mostly non-breaking.

[tingerrr]

Exports are only needed on the package boundary, not the file boundary. Not sure how it would work in detail.

So a package author can configure what's exported in @preview/package:0.1.0, but not any submodule?

[bluebear94]

Aside from all private and all public, I see two further options:

Both of the following solutions are workable, but:

* Exports are only needed on the package boundary, not the file boundary. Not sure how it would work in detail.

This one would make evolving from modules to packages a little harder. It also doesn’t help with maintaining more complex packages.

* Everything in a file is public unless at least one `export` is explicitly stated. This would be the opt-in flag so to speak, making the change mostly non-breaking.

This one would make the visibility of a binding require global knowledge of the module to determine.

[laurmaedje]

So a package author can configure what's exported in @preview/package:0.1.0, but not any submodule?

I was thinking more of let thing being sort of pub(crate) let thing in Rust-speak.