Document preludes #415

Havvy · 2018-09-12T07:58:36Z

I set out to document no_std and ended up documenting preludes in general. This also led to the removal of the "Module-only attributes" section as one of its attributes was placed in the prelude attributes section while the other attribute is already documented pretty well on the modules page, so I just linked to it from the attributes page. I wanted to get rid of that section anyways. This means the only two sections in the attribute sections that need to be removed are "crate only attributes" and "misc. attributes". Though having all the sections subsumed under misc attributes was a mistake, and they need to be brought a level higher. I'll do that after this lands, while also sorting them alphabetically.

I am generally happy with the new prose I've written in this PR. I specifically added why no_std is useful because I see it as a frequently asked question.

petrochenkov · 2018-09-12T11:03:45Z

src/crates-and-source-files.md

+## Preludes and `no_std`
+
+All crates have a *prelude* that automatically inserts a [use declaration] into
+each [module] and an [`extern crate]` into the crate root module. By default,


This is not how it works and there are observable differences.
(Will explain later, need to go now.)

I'm still blocked on this explanation.

Sorry, I completely forgot about this.

Prelude names are not placed in any modules with use declarations, they are just added into scope.
So you can write Vec<T> in any module, but not self::Vec<T> - ther's no Vec in any module.

If we look at some other names that are placed into scope rather than into modules

{ let x = 10; { let x = 11; { let x = 12; { x } } } }

then we can extend this hierarchy with one more outer level and place prelude names there, that's the effect of std prelude injection.

A number of other names behaves in the same way, e.g. built-in types, or macros imported with #[macro_use] extern crate ..., or extern crates with feature(extern_prelude) (that's currently being stabilized in rust-lang/rust#54404),

So

#[prelude_import] use std::prelude::v1::*;

that you can see in the root module after running a crate through --pretty=expanded is not really a use item, it's just some arbitrary syntax that contains a module name that compiler can detect and do its job by putting names from that module into scope.
(It could be prelude std::prelude::v1; instead, or something, but we decided not to invent a new syntax for this implementation detail.)

Havvy · 2018-09-26T23:06:58Z

The last two weeks of work have been hard on me, but I finally got the energy to properly update this today. @petrochenkov, does this accurately describe the prelude now?

Paths and path resolution need a new look at in the future, so I'm not too worried with the writing about "in scope" or whatnot being technically specific at this moment.

petrochenkov · 2018-09-26T23:46:11Z

src/crates-and-source-files.md

-each [module] and an [`extern crate]` into the crate root module. By default,
-the *standard prelude* is used. The linked crate is [`std`] and the [use
-delcaration] uses [`std::prelude::v1::*`].
+All crates have a *prelude* that automatically inserts paths of a specific


"of" -> "from" would be better?

petrochenkov · 2018-09-26T23:49:54Z

src/items/modules.md

@@ -68,8 +68,12 @@ mod thread {
 }
 ```

-Modules implicitly have a [use declaration] specified by crate's [prelude]. The
-[use declaration] can be removed by using the `no_implicit_prelude` [attribute].
+Modules implicitly have some paths in scope. These paths are to built-in types,


"paths" -> "names", names are in scope.

Path is a higher level thing in general, the first segment is searched in the current scope, the following segments are searched in modules (or in impls if they are associated items). Path as a whole being in scope doesn't make much sense.

Havvy · 2018-10-03T01:28:14Z

Both changes have been made.

Havvy · 2018-10-08T07:29:52Z

Rebased against master.

r? @matthewjasper or @alercah

ehuss · 2018-10-08T18:13:55Z

src/crates-and-source-files.md

+All crates have a *prelude* that automatically inserts names from a specific
+module, the *prelude module*, into scope of each [module] and an [`extern
+crate]` into the crate root module. By default, the *standard prelude* is used.
+The linked crate is [`std`] and the prelude module is [`std::prelude::v1`].


I had a question. By default, aren't both std and core crates included in the extern prelude? I also think std is in the prelude for no_std, but that might change soon: rust-lang/rust#54658

Also, would it be helpful to describe the different preludes and scope layers? It may not be super relevant, but it might help clarify precedence when there are name conflicts (additions to the standard prelude will not shadow extern crates). IIUC, the layers are:

local variables

items in unnamed blocks

items in the current module

crate names in the "extern prelude"

standard library prelude

language prelude (built-in types)

(The reason I ask is that I was looking at updating extern crate for the edition, and I'm trying to wrap my head around it.)

Yes, all that would be helpful. I didn't know what all the layers were, but if this is the correct list, it's definitely something that should be included.

For core being included with std in the extern prelude, I think that's all supposed to change with rust-lang/rust#53128 but I'm not entirely sure.

matthewjasper · 2018-10-09T22:20:25Z

src/items/functions.md

-attributes], and [the optimization hint
-attributes].
+attributes], and [the optimization hint attributes]. Functions also accept
+macro attributes.


attribute macros?

matthewjasper · 2018-10-09T22:31:37Z

src/crates-and-source-files.md

-that have a *dynamic interpretation* govern the behavior of the program at
-run-time.
+semantic rules that have a *dynamic interpretation* govern the behavior of the
+program at run-time.


Unrelated, but does this distinction ever appear again?

Const functions perhaps? It's a paragraph that's survived since the reference was originally the guide.

Havvy · 2018-10-17T08:27:06Z

This is still waiting for merge, and I don't perceive an action I need to do in this PR.

matthewjasper · 2018-10-17T11:03:55Z

Thanks, I think I was just waiting to see if you wanted to address @ehuss' comment

petrochenkov reviewed Sep 12, 2018

View reviewed changes

petrochenkov reviewed Sep 26, 2018

View reviewed changes

petrochenkov approved these changes Oct 3, 2018

View reviewed changes

Havvy added 3 commits October 8, 2018 00:29

Document preludes

d5aa63d

The prelude is not a use statement

354dc3f

preludes: paths -> names

cb53ba3

Havvy force-pushed the no_std branch from ba6555f to cb53ba3 Compare October 8, 2018 07:29

ehuss reviewed Oct 8, 2018

View reviewed changes

matthewjasper approved these changes Oct 9, 2018

View reviewed changes

Functions: macro attributes -> attribute macros

61d5682

ehuss mentioned this pull request Oct 14, 2018

Path and module changes (RFC 2126) #291

Open

6 tasks

matthewjasper merged commit 8d7463f into rust-lang:master Oct 17, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document preludes #415

Document preludes #415

Havvy commented Sep 12, 2018

petrochenkov Sep 12, 2018

Havvy Sep 20, 2018

petrochenkov Sep 20, 2018

petrochenkov Sep 20, 2018

petrochenkov Sep 20, 2018

petrochenkov Sep 20, 2018 •

edited

Loading

Havvy commented Sep 26, 2018

petrochenkov Sep 26, 2018

petrochenkov Sep 26, 2018

petrochenkov Sep 26, 2018

Havvy commented Oct 3, 2018

Havvy commented Oct 8, 2018

ehuss Oct 8, 2018

Havvy Oct 13, 2018

matthewjasper Oct 9, 2018

matthewjasper Oct 9, 2018

Havvy Oct 13, 2018

Havvy commented Oct 17, 2018

matthewjasper commented Oct 17, 2018

Document preludes #415

Document preludes #415

Conversation

Havvy commented Sep 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petrochenkov Sep 20, 2018 • edited Loading

Choose a reason for hiding this comment

Havvy commented Sep 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy commented Oct 3, 2018

Havvy commented Oct 8, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy commented Oct 17, 2018

matthewjasper commented Oct 17, 2018

petrochenkov Sep 20, 2018 •

edited

Loading