sprinkle links to rustdoc through the HIR explanation
This commit is contained in:
Niko Matsakis
Who? Me?!
parent
581b5fc9cf
commit
f893fe8019
87
src/hir.md
87
src/hir.md
|
|
@ -20,13 +20,15 @@ You can view the HIR representation of your code by passing the
|
|||
|
||||
### Out-of-band storage and the `Crate` type
|
||||
|
||||
The top-level data-structure in the HIR is the `Crate`, which stores
|
||||
The top-level data-structure in the HIR is the [`Crate`], which stores
|
||||
the contents of the crate currently being compiled (we only ever
|
||||
construct HIR for the current crate). Whereas in the AST the crate
|
||||
data structure basically just contains the root module, the HIR
|
||||
`Crate` structure contains a number of maps and other things that
|
||||
serve to organize the content of the crate for easier access.
|
||||
|
||||
[`Crate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Crate.html
|
||||
|
||||
For example, the contents of individual items (e.g. modules,
|
||||
functions, traits, impls, etc) in the HIR are not immediately
|
||||
accessible in the parents. So, for example, if there is a module item
|
||||
|
|
@ -38,11 +40,13 @@ mod foo {
|
|||
}
|
||||
```
|
||||
|
||||
then in the HIR the representation of module `foo` (the `Mod`
|
||||
stuct) would only have the **`ItemId`** `I` of `bar()`. To get the
|
||||
then in the HIR the representation of module `foo` (the [`Mod`]
|
||||
struct) would only have the **`ItemId`** `I` of `bar()`. To get the
|
||||
details of the function `bar()`, we would lookup `I` in the
|
||||
`items` map.
|
||||
|
||||
[`Mod`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Mod.html
|
||||
|
||||
One nice result from this representation is that one can iterate
|
||||
over all items in the crate by iterating over the key-value pairs
|
||||
in these maps (without the need to trawl through the whole HIR).
|
||||
|
|
@ -51,12 +55,14 @@ as well as "bodies" (explained below).
|
|||
|
||||
The other reason to set up the representation this way is for better
|
||||
integration with incremental compilation. This way, if you gain access
|
||||
to an `&hir::Item` (e.g. for the mod `foo`), you do not immediately
|
||||
to an [`&hir::Item`] (e.g. for the mod `foo`), you do not immediately
|
||||
gain access to the contents of the function `bar()`. Instead, you only
|
||||
gain access to the **id** for `bar()`, and you must invoke some
|
||||
function to lookup the contents of `bar()` given its id; this gives the
|
||||
compiler a chance to observe that you accessed the data for `bar()`,
|
||||
and then record the dependency.
|
||||
function to lookup the contents of `bar()` given its id; this gives
|
||||
the compiler a chance to observe that you accessed the data for
|
||||
`bar()`, and then record the dependency.
|
||||
|
||||
[`&hir::Item`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Item.html
|
||||
|
||||
<a name="hir-id"></a>
|
||||
|
||||
|
|
@ -67,63 +73,86 @@ carry around references into the HIR, but rather to carry around
|
|||
*identifier numbers* (or just "ids"). Right now, you will find four
|
||||
sorts of identifiers in active use:
|
||||
|
||||
- `DefId`, which primarily names "definitions" or top-level items.
|
||||
- You can think of a `DefId` as being shorthand for a very explicit
|
||||
- [`DefId`], which primarily names "definitions" or top-level items.
|
||||
- You can think of a [`DefId`] as being shorthand for a very explicit
|
||||
and complete path, like `std::collections::HashMap`. However,
|
||||
these paths are able to name things that are not nameable in
|
||||
normal Rust (e.g. impls), and they also include extra information
|
||||
about the crate (such as its version number, as two versions of
|
||||
the same crate can co-exist).
|
||||
- A `DefId` really consists of two parts, a `CrateNum` (which
|
||||
- A [`DefId`] really consists of two parts, a `CrateNum` (which
|
||||
identifies the crate) and a `DefIndex` (which indixes into a list
|
||||
of items that is maintained per crate).
|
||||
- `HirId`, which combines the index of a particular item with an
|
||||
- [`HirId`], which combines the index of a particular item with an
|
||||
offset within that item.
|
||||
- the key point of a `HirId` is that it is *relative* to some item
|
||||
(which is named via a `DefId`).
|
||||
- `BodyId`, this is an absolute identifier that refers to a specific
|
||||
- the key point of a [`HirId`] is that it is *relative* to some item
|
||||
(which is named via a [`DefId`]).
|
||||
- [`BodyId`], this is an absolute identifier that refers to a specific
|
||||
body (definition of a function or constant) in the crate. It is currently
|
||||
effectively a "newtype'd" `NodeId`.
|
||||
- `NodeId`, which is an absolute id that identifies a single node in the HIR
|
||||
effectively a "newtype'd" [`NodeId`].
|
||||
- [`NodeId`], which is an absolute id that identifies a single node in the HIR
|
||||
tree.
|
||||
- While these are still in common use, **they are being slowly phased out**.
|
||||
- Since they are absolute within the crate, adding a new node anywhere in the
|
||||
tree causes the `NodeId`s of all subsequent code in the crate to change.
|
||||
tree causes the [`NodeId`]s of all subsequent code in the crate to change.
|
||||
This is terrible for incremental compilation, as you can perhaps imagine.
|
||||
|
||||
[`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/def_id/struct.DefId.html
|
||||
[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.HirId.html
|
||||
[`BodyId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.BodyId.html
|
||||
[`NodeId`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.NodeId.html
|
||||
|
||||
### The HIR Map
|
||||
|
||||
Most of the time when you are working with the HIR, you will do so via
|
||||
the **HIR Map**, accessible in the tcx via `tcx.hir` (and defined in
|
||||
the `hir::map` module). The HIR map contains a number of methods to
|
||||
the **HIR Map**, accessible in the tcx via [`tcx.hir`] (and defined in
|
||||
the [`hir::map`] module). The [HIR map] contains a [number of methods] to
|
||||
convert between IDs of various kinds and to lookup data associated
|
||||
with an HIR node.
|
||||
|
||||
For example, if you have a `DefId`, and you would like to convert it
|
||||
to a `NodeId`, you can use `tcx.hir.as_local_node_id(def_id)`. This
|
||||
[`tcx.hir`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/context/struct.GlobalCtxt.html#structfield.hir
|
||||
[`hir::map`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/index.html
|
||||
[HIR map]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html
|
||||
[number of methods]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#methods
|
||||
|
||||
For example, if you have a [`DefId`], and you would like to convert it
|
||||
to a [`NodeId`], you can use [`tcx.hir.as_local_node_id(def_id)`][as_local_node_id]. This
|
||||
returns an `Option<NodeId>` – this will be `None` if the def-id
|
||||
refers to something outside of the current crate (since then it has no
|
||||
HIR node), but otherwise returns `Some(n)` where `n` is the node-id of
|
||||
the definition.
|
||||
|
||||
Similarly, you can use `tcx.hir.find(n)` to lookup the node for a
|
||||
`NodeId`. This returns a `Option<Node<'tcx>>`, where `Node` is an enum
|
||||
[as_local_node_id]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.as_local_node_id
|
||||
|
||||
Similarly, you can use [`tcx.hir.find(n)`][find] to lookup the node for a
|
||||
[`NodeId`]. This returns a `Option<Node<'tcx>>`, where [`Node`] is an enum
|
||||
defined in the map; by matching on this you can find out what sort of
|
||||
node the node-id referred to and also get a pointer to the data
|
||||
itself. Often, you know what sort of node `n` is – e.g. if you know
|
||||
that `n` must be some HIR expression, you can do
|
||||
`tcx.hir.expect_expr(n)`, which will extract and return the
|
||||
`&hir::Expr`, panicking if `n` is not in fact an expression.
|
||||
[`tcx.hir.expect_expr(n)`][expect_expr], which will extract and return the
|
||||
[`&hir::Expr`][Expr], panicking if `n` is not in fact an expression.
|
||||
|
||||
[find]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.find
|
||||
[`Node`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/enum.Node.html
|
||||
[expect_expr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.expect_expr
|
||||
[Expr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Expr.html
|
||||
|
||||
Finally, you can use the HIR map to find the parents of nodes, via
|
||||
calls like `tcx.hir.get_parent_node(n)`.
|
||||
calls like [`tcx.hir.get_parent_node(n)`][get_parent_node].
|
||||
|
||||
[get_parent_node]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.get_parent_node
|
||||
|
||||
### HIR Bodies
|
||||
|
||||
A **body** represents some kind of executable code, such as the body
|
||||
A [`hir::Body`] represents some kind of executable code, such as the body
|
||||
of a function/closure or the definition of a constant. Bodies are
|
||||
associated with an **owner**, which is typically some kind of item
|
||||
(e.g. an `fn()` or `const`), but could also be a closure expression
|
||||
(e.g. `|x, y| x + y`). You can use the HIR map to find the body
|
||||
associated with a given def-id (`maybe_body_owned_by()`) or to find
|
||||
the owner of a body (`body_owner_def_id()`).
|
||||
associated with a given def-id ([`maybe_body_owned_by`]) or to find
|
||||
the owner of a body ([`body_owner_def_id`]).
|
||||
|
||||
[`hir::Body`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Body.html
|
||||
[`maybe_body_owned_by`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.maybe_body_owned_by
|
||||
[`body_owner_def_id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/map/struct.Map.html#method.body_owner_def_id
|
||||
|
|
|
|||
Loading…
Reference in New Issue