Standard Library updates for 0.99

[NotTheDr01ds]

Updates for the Standard Library changes that will be a part of the 0.99 release.

[fdncred]

I generally approve of this PR but just had a couple comments. Thanks!

[NotTheDr01ds]

Thanks! Fix pushed for the missing language-specified, and also responded on the other one.

[kubouch]

Some of the following points go too much into how modules work, that's not necessary. We can link to https://www.nushell.sh/book/modules.html where it's explained already (although it also needs improvements).

Here you can just say that std is a “virtual” directory and the iter, help are submodules in it, defined as module directories. Linking to https://github.com/nushell/nushell/tree/main/crates/nu-std/std would be helpful to show the module directory structure.

We don't want to teach users to invoke magic incantations. std is a normal module like any other module. We shouldn't give an impression that there is anything special about it.

I think you can formulate the points as something like (very abbreviated version):

The std submodules were designed to be used in different ways

1. Import the submodule as subcommands
   Some modules follow a subcommand structure and meant to be imported as use std/<submodule>.
   a) E.g., use std/iter ... defines iter xxxsubcommands
   b) Same, but designed to shadow existing commands, e.g., use std/help.
   ... list all modules in this style
2. Import the contents of the module directly
   These modules were designed to make their content available in the current scope with use std/<submodule> *.
   ... list all modules in this style
3. Import specific definitions -- IMO this point is not necessary
4. Good

When in doubt, checked the source code of the module (linked above).

The terms “prefix” or “namespace” are not very well-defined in Nushell and can be confusing. You can use “scope”, or talk about defining subcommands.

[NotTheDr01ds]

I totally agree with you on both points. (1) We should be able to point to the Modules chapter, and yet (2) the Modules chapter needs a lot of attention. One of the things we should (i.e., I plan to do) is split out Modules into "Using Modules" and "Writing Modules". At the moment, a reader would have to wade through all of the "writing" information just to find out how to import the different forms.

I'd like to keep this section mostly intact for now, and as soon as I get a chance I'll work on the Modules rewrite. I can use std submodules for the examples in the "Using Modules" chapter (or subchapter) since:

1. As you mention std is just a standard module/submodule design - Nothing special.
2. It's already on the user's system with no need to come up with "fake examples"
3. I can just move (not duplicate) some of this to that chapter where it belongs.

Does that sound like an acceptable path?

[kubouch]

Left some comments, thanks for the write-up! I think the main thing is shortening / simplifying the importing instructions. Now, it seems like the stdlib somehow follows some special rules, but in fact, it only uses standard module syntax rules. You were kind of re-explaining how module imports work.

[NotTheDr01ds]

@kubouch Thanks! I've addressed most of the comments above. Except for ... ;-)

You were kind of re-explaining how module imports work.

Unfortunately, I'm not sure "re-explaining" is quite accurate here, since the current Modules chapter really doesn't explain it. In fact, only one example uses use <module>/<submodule> form, and that's only in context of creating another module that imports a module.

As I mentioned in the review reply above, I'd like to leave this section "over-explained" for now, and (as soon as I get a chance) work on moving it over into the Modules chapter.

My thought at this point is that we need to split the Modules chapter out into:

• "Using Modules" (Move much of this information from this write-up in there)
• "Writing Modules" (Which still needs, as you said, a lot of attention)

[kubouch]

OK, splitting Modules to a) using, b) writing sounds good. Most people will likely use a) the most, so that should be explained first.

The use <module>/<submodule> imports from a directory module that's located in the <module> directory. It uses an existing language feature. If you present it as a unique form of importing a module, that makes it confusing. I hope you get what I mean. We can over-specify the “how” instructions for now until the Modules chapter is improved. What I'm suggesting is to expand a bit on the “why”.

But honestly, it's good enough. The release is rolling off, let's merge it when it's out, and it can be improved later.

[NotTheDr01ds]

OK, splitting Modules to a) using, b) writing sounds good. Most people will likely use a) the most, so that should be explained first.

Agreed

It uses an existing language feature. If you present it as a unique form of importing a module, that makes it confusing. I hope you get what I mean.

Absolutely agreed - Nothing unique going on here in the import forms, which is why it should make for good examples in the "Using" chapter. We can definitely work on getting across the "Why" there.

Thanks!