rename `use` to `usingnamespace`

[andrewrk]

After deliberation, I believe that the use functionality of Zig will stay. Here is my reasoning:

This use case is valid (from https://github.com/andrewrk/tetris/blob/8c22d4956348d3ce64cdbeccc4fa8204d94a2eaa/src/c.zig):

c.zig

pub use @cImport({
 @cInclude("epoxy/gl.h");
 @cInclude("GLFW/glfw3.h");
 @cInclude("png.h");
 @cInclude("math.h");
 @cInclude("stdlib.h");
 @cInclude("stdio.h");
});

Usage looks like this:

const c = @import("c.zig");
test "example" {
 c.printf("hi\n");
}

If pub use wasn't possible, at the callsite it would look like this:

const c = @import("c.zig");
test "example" {
 c.c.printf("hi\n");
}

Indeed, every time a file wanted to expose its own dependency to its dependents, this would happen.

If this feature existed without "splatting" into the same file, it would still be possible to obtain the previous "use" behavior. Coders could introduce an indirect file which does all the splatting, and then in the file that imports it, const x = @import("indirect.zig");, and then when doing x.foo we're still in the same position as before: having to look at multiple use declarations to find the symbol.

So let's not pretend this isn't something Zig supports. Status quo use semantics are correct. Here's my proposal to stabilize this aspect of Zig language:

• rename use to usingnamespace
  • this is a smashedcase name, unlikely to collide with any identifiers, especially considering the style guide recommends against smashedcase anything. Frees up use for zig programmers to use.
  • it's abundantly clear what it's doing, especially if you consider that C++ has using namespace and it does exactly the same thing.
  • it's slightly long and annoying to type, which is how zig hints to programmers that maybe other options should be explored first.
• Previously I had avoided documenting use (See add docs for usingnamespace #1589) in part to discourage its use because I was not sure if it would get deleted or not. This proposal would make the feature considered relatively stable. So document it, make it clear that it should generally be avoided, and explain what are good situations for it.

One more unrelated argument for keeping it. Zig intends to beat C at its own game. Code can be translated pretty directly from C to Zig when you e.g. usingnamespace @cImport(@cInclude("stdlib.h"));.

[hryx]

Am I mistaken, or is the alternative to this:

const c = @import("c.zig");
test "example" {
 c.c.printf("hi\n");
}

...this?

const c = @import("c.zig").c;
test "example: {
 c.printf("hi\n");
}

I recognize it's a subtlety which could slow down and confuse newcomers, not to mention it's a slight annoyance. But does this one gotcha justify a new keyword and language feature?

If so, are there alternative proposals which are scoped purely to the problem described (providing cleaner, more obvious callsite usage)? My beef with use is that it has the power to create invisible (possibly colliding) declarations in the scope, which is not the goal or use case of this keyword, according to this proposal.

(For the record, I still think the keyword rename itself is a positive change.)

[raulgrell]

What about #2020 / #1047 ? I thought there was no longer a concept of "namespace"?

[andrewrk]

@raulgrell There's no longer a (namespace) type but there is the concept of a namespace - every struct, union, and enum creates one.

[andrewrk]

Done in b7a8228

zig fmt will auto update code. #2591 is set for milestone 0.6.0 which means as soon as 0.5.0 is released we can remove use keyword from the language. Until then zig fmt will be fixing things automatically.

[andrewrk]

@hryx

Am I mistaken, or is the alternative to this...this?

You are correct - that is the alternative.

But does this one gotcha justify a new keyword and language feature?

I agree with you if that was the only issue, I think it would not necessitate this feature. The standard library has some other examples of usage where I felt it was a proper use of the feature, most notably the "bits.zig" files (and where those are imported). If you are willing to create a proof of concept of how the std lib would be reorganized without the usingnamespace feature, I would reconsider deleting the feature.