1
Fork 0

Add docs for crate_in_paths, extern_in_paths and extern_absolute_paths into the unstable book

This commit is contained in:
Vadim Petrochenkov 2018-01-03 19:14:46 +03:00
parent 32db83b16e
commit ef2b131144
3 changed files with 137 additions and 0 deletions

View file

@ -0,0 +1,54 @@
# `crate_in_paths`
The tracking issue for this feature is: [#44660]
[#44660]: https://github.com/rust-lang/rust/issues/44660
------------------------
The `crate_in_paths` feature allows to explicitly refer to the crate root in absolute paths
using keyword `crate`.
`crate` can be used *only* in absolute paths, i.e. either in `::crate::a::b::c` form or in `use`
items where the starting `::` is added implicitly.
Paths like `crate::a::b::c` are not accepted currently.
This feature is required in `feature(extern_absolute_paths)` mode to refer to any absolute path
in the local crate (absolute paths refer to extern crates by default in that mode), but can be
used without `feature(extern_absolute_paths)` as well.
```rust
#![feature(crate_in_paths)]
// Imports, `::` is added implicitly
use crate::m::f;
use crate as root;
mod m {
pub fn f() -> u8 { 1 }
pub fn g() -> u8 { 2 }
pub fn h() -> u8 { 3 }
// OK, visibilities implicitly add starting `::` as well, like imports
pub(in crate::m) struct S;
}
mod n
{
use crate::m::f;
use crate as root;
pub fn check() {
assert_eq!(f(), 1);
// `::` is required in non-import paths
assert_eq!(::crate::m::g(), 2);
assert_eq!(root::m::h(), 3);
}
}
fn main() {
assert_eq!(f(), 1);
assert_eq!(::crate::m::g(), 2);
assert_eq!(root::m::h(), 3);
n::check();
}
```

View file

@ -0,0 +1,43 @@
# `extern_absolute_paths`
The tracking issue for this feature is: [#44660]
[#44660]: https://github.com/rust-lang/rust/issues/44660
------------------------
The `extern_absolute_paths` feature enables mode allowing to refer to names from other crates
"inline", without introducing `extern crate` items, using absolute paths like `::my_crate::a::b`.
`::my_crate::a::b` will resolve to path `a::b` in crate `my_crate`.
`feature(crate_in_paths)` can be used in `feature(extern_absolute_paths)` mode for referring
to absolute paths in the local crate (`::crate::a::b`).
`feature(extern_in_paths)` provides the same effect by using keyword `extern` to refer to
paths from other crates (`extern::my_crate::a::b`).
```rust,ignore
#![feature(extern_absolute_paths)]
// Suppose we have a dependency crate `xcrate` available through `Cargo.toml`, or `--extern`
// options, or standard Rust distribution, or some other means.
use xcrate::Z;
fn f() {
use xcrate;
use xcrate as ycrate;
let s = xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = ycrate::Z;
assert_eq!(format!("{:?}", z), "Z");
}
fn main() {
let s = ::xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = Z;
assert_eq!(format!("{:?}", z), "Z");
}
```

View file

@ -0,0 +1,40 @@
# `extern_in_paths`
The tracking issue for this feature is: [#44660]
[#44660]: https://github.com/rust-lang/rust/issues/44660
------------------------
The `extern_in_paths` feature allows to refer to names from other crates "inline", without
introducing `extern crate` items, using keyword `extern`.
For example, `extern::my_crat::a::b` will resolve to path `a::b` in crate `my_crate`.
`feature(extern_absolute_paths)` mode provides the same effect by resolving absolute paths like
`::my_crate::a::b` to paths from extern crates by default.
```rust,ignore
#![feature(extern_in_paths)]
// Suppose we have a dependency crate `xcrate` available through `Cargo.toml`, or `--extern`
// options, or standard Rust distribution, or some other means.
use extern::xcrate::Z;
fn f() {
use extern::xcrate;
use extern::xcrate as ycrate;
let s = xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = ycrate::Z;
assert_eq!(format!("{:?}", z), "Z");
}
fn main() {
let s = extern::xcrate::S;
assert_eq!(format!("{:?}", s), "S");
let z = Z;
assert_eq!(format!("{:?}", z), "Z");
}
```